Wire M10.8c-1 region handoff: protocol v4, durable probes, crossing, ghosts
Foundation / checks (deploy) (push) Successful in 3m29s
Foundation / checks (ecs) (push) Successful in 2m0s
Foundation / checks (client) (push) Successful in 12m51s
Foundation / checks (network) (push) Successful in 13m0s
Foundation / checks (tsan) (push) Successful in 7m50s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 32m4s
Foundation / checks (postgres) (push) Canceled after 19m13s
Foundation / checks (deploy) (push) Successful in 3m29s
Foundation / checks (ecs) (push) Successful in 2m0s
Foundation / checks (client) (push) Successful in 12m51s
Foundation / checks (network) (push) Successful in 13m0s
Foundation / checks (tsan) (push) Successful in 7m50s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 32m4s
Foundation / checks (postgres) (push) Canceled after 19m13s
ADR-0096. Session protocol v4 (v3 is deployed and frozen) adds HandoffOffer, SessionRedirect, close reasons handed_off and moved, and ghost marker records. Sessions use the durable probe record: logins open it where it was saved (redirected when it lives elsewhere), and session ends save it. A marker crossing into a neighbour's area is frozen, prepared, its control released and a signed ticket offered; uncommitted transfers are aborted after the ticket's lifetime. The destination shows arriving probes as ghosts (schema v13 incoming_probe_transfers) and opens the marker where it crossed. Refreshes the dev session window. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -68,11 +68,12 @@ struct InterpolationLimits {
|
||||
struct RemoteMarker {
|
||||
std::uint64_t id{};
|
||||
network::motion::State state;
|
||||
bool ghost{}; // A probe being handed to this region (ADR-0096): read-only.
|
||||
};
|
||||
struct PresentedMarker {
|
||||
std::uint64_t id{};
|
||||
double x{}, y{}; // Micrometres.
|
||||
bool extrapolated{}, stale{};
|
||||
bool extrapolated{}, stale{}, ghost{};
|
||||
};
|
||||
struct InterpolationStats {
|
||||
std::uint64_t snapshots{}, ignored{}, extrapolated_frames{}, stale_frames{}, gap_snaps{};
|
||||
|
||||
@@ -74,6 +74,11 @@ class RegionSessionClient {
|
||||
[[nodiscard]] RegionSessionState state() const noexcept;
|
||||
[[nodiscard]] const std::optional<network::SessionWelcome>& welcome() const noexcept;
|
||||
[[nodiscard]] std::optional<network::SessionCloseReason> close_reason() const noexcept;
|
||||
// v4 (ADR-0096): the offer to continue at another region (kept until taken; the session
|
||||
// then closes with handed_off), and where the account's probe is when a login was closed
|
||||
// with moved.
|
||||
[[nodiscard]] std::optional<network::HandoffOffer> take_handoff();
|
||||
[[nodiscard]] const std::optional<network::RegionAddress>& redirect() const noexcept;
|
||||
// Why the QUIC connection itself ended (e.g. `untrusted`: the server answered but its
|
||||
// certificate failed the pinned check), when it ended without a session Close.
|
||||
[[nodiscard]] std::optional<network::quic::CloseCause> transport_cause() const noexcept;
|
||||
|
||||
@@ -133,13 +133,20 @@ enum class HandoffLedgerError : std::uint8_t {
|
||||
fenced, // This region's lease is not current.
|
||||
unavailable // Not decided (database unreachable, timeout, unknown outcome): retry later.
|
||||
};
|
||||
// What the destination now owns: the account's control lease and the probe's state after
|
||||
// the committed switch (its generation and position, in micrometres).
|
||||
struct HandoffAdmission {
|
||||
ControlLease lease;
|
||||
std::uint64_t generation{};
|
||||
std::int64_t x{}, y{};
|
||||
};
|
||||
class HandoffLedger {
|
||||
public:
|
||||
HandoffLedger() = default;
|
||||
HandoffLedger(const HandoffLedger&) = delete;
|
||||
HandoffLedger& operator=(const HandoffLedger&) = delete;
|
||||
virtual ~HandoffLedger() = default;
|
||||
[[nodiscard]] virtual std::expected<ControlLease, HandoffLedgerError>
|
||||
[[nodiscard]] virtual std::expected<HandoffAdmission, HandoffLedgerError>
|
||||
admit(const TicketClaims& ticket, std::uint64_t session) = 0;
|
||||
|
||||
protected:
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
#pragma once
|
||||
#include <array>
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <deque>
|
||||
#include <expected>
|
||||
#include <optional>
|
||||
#include <span>
|
||||
#include <vector>
|
||||
|
||||
// M10.6 probe-motion experiment (ADR-0094). EXPERIMENT, not a game rule: one
|
||||
@@ -47,6 +49,16 @@ struct Marker {
|
||||
std::uint64_t id{}, session{};
|
||||
State state;
|
||||
std::uint64_t applied_sequence{}; // Newest intention whose vector is in `state`.
|
||||
// M10.8c (ADR-0096): frozen markers neither move nor take intentions (a handoff is being
|
||||
// prepared); ghosts are read-only copies of probes being handed to this region (no
|
||||
// session, never moving).
|
||||
bool frozen{}, ghost{};
|
||||
};
|
||||
// A probe arriving here, shown read-only until its transfer commits (keyed by transfer id).
|
||||
struct Ghost {
|
||||
std::array<std::uint8_t, 16> transfer{};
|
||||
std::int64_t x{}, y{};
|
||||
friend bool operator==(const Ghost&, const Ghost&) = default;
|
||||
};
|
||||
enum class MarkerError : std::uint8_t { no_area, unknown_session, full, invalid };
|
||||
class ProbeMarkers {
|
||||
@@ -61,6 +73,15 @@ class ProbeMarkers {
|
||||
}
|
||||
// A marker for the session, at the spawn, holding no movement.
|
||||
[[nodiscard]] std::expected<std::uint64_t, MarkerError> open(std::uint64_t session);
|
||||
// The same at a given position (a durable probe's, clamped into the area).
|
||||
[[nodiscard]] std::expected<std::uint64_t, MarkerError> open_at(std::uint64_t session,
|
||||
std::int64_t x, std::int64_t y);
|
||||
// Moves the session's marker to a position (clamped into the area), keeping its vector.
|
||||
void place(std::uint64_t session, std::int64_t x, std::int64_t y);
|
||||
// Stops the session's marker where it is: no motion and no new intentions.
|
||||
void freeze(std::uint64_t session);
|
||||
// Replaces the ghosts (stable ids per transfer; at most max_markers).
|
||||
void set_ghosts(std::span<const Ghost> ghosts);
|
||||
void close(std::uint64_t session);
|
||||
// Removes every marker and forgets the tick (a new epoch may restart at an earlier one).
|
||||
void clear() noexcept;
|
||||
@@ -90,11 +111,16 @@ class ProbeMarkers {
|
||||
Marker marker;
|
||||
std::deque<Scheduled> scheduled; // Ascending tick, then sequence.
|
||||
};
|
||||
struct GhostEntry {
|
||||
Ghost ghost;
|
||||
std::uint64_t id{};
|
||||
};
|
||||
std::size_t max_markers_, max_scheduled_;
|
||||
std::optional<Area> area_;
|
||||
std::int64_t spawn_x_{}, spawn_y_{};
|
||||
std::vector<Marker> markers_; // Mirror of entries_ for readers, in id order.
|
||||
std::vector<Entry> entries_;
|
||||
std::vector<GhostEntry> ghosts_;
|
||||
std::uint64_t tick_{}, next_id_{1};
|
||||
void publish();
|
||||
};
|
||||
|
||||
@@ -120,6 +120,7 @@ struct ReplicatedMarker {
|
||||
motion::State state;
|
||||
std::int64_t z{};
|
||||
bool own{};
|
||||
bool ghost{}; // v4: a probe being handed to this region, read-only (ADR-0096).
|
||||
std::uint64_t applied_sequence{};
|
||||
motion::Area area;
|
||||
friend bool operator==(const ReplicatedMarker&, const ReplicatedMarker&) = default;
|
||||
|
||||
@@ -4,6 +4,7 @@
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
#include <span>
|
||||
#include <string>
|
||||
#include <variant>
|
||||
#include <vector>
|
||||
|
||||
@@ -17,9 +18,12 @@
|
||||
namespace evo::network {
|
||||
inline constexpr std::uint32_t session_magic = 0x4E535645; // Bytes "EVSN".
|
||||
// v2 (M10.5, ADR-0093): v1 plus interest, snapshot chunks and snapshot acks.
|
||||
// v3 (M10.6, ADR-0094): v2 plus probe marker records inside snapshot chunks; no new message
|
||||
// types. v1 and v2 were deployed to evolution-dev and are frozen; only v3 is accepted.
|
||||
inline constexpr std::uint16_t session_protocol_version = 3;
|
||||
// v3 (M10.6, ADR-0094): v2 plus probe marker records inside snapshot chunks.
|
||||
// v4 (M10.8c, ADR-0096): v3 plus HandoffOffer and SessionRedirect (stream), close reasons
|
||||
// handed_off and moved, and ghost marker records. v1-v3 were deployed to evolution-dev and
|
||||
// are frozen; only v4 is accepted.
|
||||
inline constexpr std::uint16_t session_protocol_version = 4;
|
||||
inline constexpr std::size_t session_address_bytes = 64; // Endpoint or server name field.
|
||||
inline constexpr std::size_t session_datagram_bytes = 1200; // Whole message, ADR-0089.
|
||||
inline constexpr std::size_t session_header_bytes = 8;
|
||||
inline constexpr std::size_t session_grant_wire_bytes = 160;
|
||||
@@ -39,7 +43,9 @@ enum class SessionMessageType : std::uint8_t {
|
||||
action_query, // Client -> server, stream: resolve an action by id.
|
||||
interest, // Client -> server, stream: spatial focus (v2).
|
||||
snapshot_chunk, // Server -> client, datagram: part of one snapshot (v2).
|
||||
snapshot_ack // Client -> server, datagram: newest complete snapshot (v2).
|
||||
snapshot_ack, // Client -> server, datagram: newest complete snapshot (v2).
|
||||
handoff_offer, // Server -> client, stream: continue at another region (v4).
|
||||
redirect // Server -> client, stream: the account's probe is elsewhere (v4).
|
||||
};
|
||||
// Admission answers for intentions and actions (wire 0..10).
|
||||
enum class AdmitStatus : std::uint8_t {
|
||||
@@ -80,6 +86,8 @@ enum class SessionCloseReason : std::uint8_t {
|
||||
timeout, // No Hello before the deadline.
|
||||
unsupported_version,
|
||||
shutdown,
|
||||
handed_off, // v4: the probe crossed to another region; a HandoffOffer preceded this.
|
||||
moved, // v4: the account's probe is owned by another region (a Redirect may precede).
|
||||
connection_lost = 255
|
||||
};
|
||||
enum class SessionCodecError : std::uint8_t {
|
||||
@@ -184,10 +192,31 @@ struct SnapshotAck {
|
||||
std::uint64_t epoch{}, tick{};
|
||||
friend bool operator==(const SnapshotAck&, const SnapshotAck&) = default;
|
||||
};
|
||||
// A region's public address as a client dials it: "host:port" and the certificate name,
|
||||
// printable ASCII (no spaces), 1-64 characters each.
|
||||
struct RegionAddress {
|
||||
std::uint64_t region{};
|
||||
std::string endpoint, server_name;
|
||||
friend bool operator==(const RegionAddress&, const RegionAddress&) = default;
|
||||
};
|
||||
// v4 (ADR-0096): the session's probe crossed into `destination`; log in there with `ticket`
|
||||
// (a handoff ticket, used in Hello's grant slot). The source then closes with handed_off.
|
||||
struct HandoffOffer {
|
||||
std::array<std::uint8_t, 16> transfer{};
|
||||
RegionAddress destination;
|
||||
WireGrant ticket{};
|
||||
friend bool operator==(const HandoffOffer&, const HandoffOffer&) = default;
|
||||
};
|
||||
// v4: at login, the account's probe is owned by `owner`; log in there with a grant for it.
|
||||
struct SessionRedirect {
|
||||
RegionAddress owner;
|
||||
friend bool operator==(const SessionRedirect&, const SessionRedirect&) = default;
|
||||
};
|
||||
using SessionMessage =
|
||||
std::variant<SessionHello, SessionWelcome, SessionRefresh, SessionRefreshResult, SessionClose,
|
||||
SessionIntention, IntentionReceipt, SimulatedThrough, SessionAction, ActionReceipt,
|
||||
ActionOutcome, ActionQuery, SessionInterest, SnapshotChunk, SnapshotAck>;
|
||||
ActionOutcome, ActionQuery, SessionInterest, SnapshotChunk, SnapshotAck,
|
||||
HandoffOffer, SessionRedirect>;
|
||||
|
||||
[[nodiscard]] std::vector<std::uint8_t> encode_session(const SessionMessage& message);
|
||||
// Exactly one message; any other length for its type rejects.
|
||||
|
||||
@@ -5,6 +5,7 @@
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
#include <optional>
|
||||
#include <vector>
|
||||
|
||||
// Linux-only calls to the probe record and handoff functions of schema v12 (ADR-0096,
|
||||
// migrations/0012_probe_handoff.sql). EXPERIMENT: probes are non-biological engineering
|
||||
@@ -75,4 +76,15 @@ abort_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const
|
||||
[[nodiscard]] std::expected<std::optional<ProbeTransfer>, ProbeStoreFailure>
|
||||
find_probe_transfer(Postgres& db, RegionKey key, const LeaseGrant& lease, const Uuid& transfer,
|
||||
std::chrono::milliseconds timeout);
|
||||
// Schema v13: the open (prepared or staged) transfers addressed to the caller's region, for
|
||||
// read-only ghosts (at most 256, oldest first).
|
||||
struct IncomingTransfer {
|
||||
Uuid transfer{}, account{};
|
||||
std::uint64_t source{};
|
||||
std::int64_t x{}, y{}, z{};
|
||||
friend bool operator==(const IncomingTransfer&, const IncomingTransfer&) = default;
|
||||
};
|
||||
[[nodiscard]] std::expected<std::vector<IncomingTransfer>, ProbeStoreFailure>
|
||||
incoming_probe_transfers(Postgres& db, RegionKey key, const LeaseGrant& lease,
|
||||
std::chrono::milliseconds timeout);
|
||||
} // namespace evo::persistence
|
||||
|
||||
@@ -2,10 +2,12 @@
|
||||
#include "evo/network/handoff_ticket.hpp"
|
||||
#include "evo/persistence/probe_store.hpp"
|
||||
#include "evo/server/pg_slot.hpp"
|
||||
#include "evo/server/probe_ledger.hpp"
|
||||
#include <chrono>
|
||||
#include <functional>
|
||||
#include <optional>
|
||||
#include <utility>
|
||||
#include <vector>
|
||||
|
||||
// M10.8b destination side of a ticket login over PostgreSQL (ADR-0096, schema v12). Linux
|
||||
// only; owned by the region host's thread, on its own connection slot. For a verified ticket:
|
||||
@@ -21,7 +23,7 @@ class PostgresHandoffLedger final : public network::HandoffLedger {
|
||||
std::chrono::milliseconds duration = std::chrono::milliseconds{20000},
|
||||
std::chrono::milliseconds timeout = std::chrono::milliseconds{2000})
|
||||
: db_{&db}, key_{key}, lease_{std::move(lease)}, duration_{duration}, timeout_{timeout} {}
|
||||
[[nodiscard]] std::expected<network::ControlLease, network::HandoffLedgerError>
|
||||
[[nodiscard]] std::expected<network::HandoffAdmission, network::HandoffLedgerError>
|
||||
admit(const network::TicketClaims& ticket, std::uint64_t session) override;
|
||||
|
||||
private:
|
||||
@@ -30,4 +32,34 @@ class PostgresHandoffLedger final : public network::HandoffLedger {
|
||||
LeaseSource lease_;
|
||||
std::chrono::milliseconds duration_, timeout_;
|
||||
};
|
||||
|
||||
// M10.8c the region's durable probe records over PostgreSQL (ADR-0096, schema v12-13), on the
|
||||
// host's lease and its own connection slot. Undecided or failed calls report `unavailable`
|
||||
// (the session layer retries or refuses); a fenced lease reports `fenced`.
|
||||
class PostgresProbeLedger final : public ProbeLedger {
|
||||
public:
|
||||
using LeaseSource = std::function<std::optional<persistence::LeaseGrant>()>;
|
||||
static constexpr std::uint64_t inventory = 1000; // EXPERIMENT test inventory per probe.
|
||||
PostgresProbeLedger(PgSlot& db, persistence::RegionKey key, LeaseSource lease,
|
||||
std::chrono::milliseconds timeout = std::chrono::milliseconds{2000})
|
||||
: db_{&db}, key_{key}, lease_{std::move(lease)}, timeout_{timeout} {}
|
||||
[[nodiscard]] std::expected<ProbeHome, ProbeLedgerError> open(const network::AccountId& account,
|
||||
std::int64_t x, std::int64_t y,
|
||||
std::int64_t z) override;
|
||||
void save(const network::AccountId& account, std::uint64_t generation, std::int64_t x,
|
||||
std::int64_t y, std::int64_t z) override;
|
||||
[[nodiscard]] std::expected<void, ProbeLedgerError>
|
||||
prepare(const network::AccountId& account, std::uint64_t generation,
|
||||
const network::TransferId& transfer, std::uint64_t destination, std::int64_t x,
|
||||
std::int64_t y, std::int64_t z) override;
|
||||
[[nodiscard]] std::expected<bool, ProbeLedgerError>
|
||||
abort(const network::TransferId& transfer) override;
|
||||
[[nodiscard]] std::expected<std::vector<IncomingProbe>, ProbeLedgerError> incoming() override;
|
||||
|
||||
private:
|
||||
PgSlot* db_;
|
||||
persistence::RegionKey key_;
|
||||
LeaseSource lease_;
|
||||
std::chrono::milliseconds timeout_;
|
||||
};
|
||||
} // namespace evo::server
|
||||
|
||||
@@ -0,0 +1,51 @@
|
||||
#pragma once
|
||||
#include "evo/network/handoff_ticket.hpp"
|
||||
#include "evo/network/session_control.hpp"
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
#include <vector>
|
||||
|
||||
// M10.8c (ADR-0096): the region's durable probe records as the session layer uses them.
|
||||
// Transport-neutral; the host implements it over PostgreSQL (PostgresProbeLedger), tests use
|
||||
// fakes. EXPERIMENT: probes are non-biological engineering entities (ADR-0094).
|
||||
namespace evo::server {
|
||||
struct ProbeHome {
|
||||
std::uint64_t owner{}, generation{};
|
||||
std::int64_t x{}, y{};
|
||||
bool frozen{}; // An open transfer: neither this region nor the owner may act yet.
|
||||
};
|
||||
struct IncomingProbe {
|
||||
network::TransferId transfer{};
|
||||
std::int64_t x{}, y{};
|
||||
};
|
||||
enum class ProbeLedgerError : std::uint8_t { fenced, unavailable };
|
||||
class ProbeLedger {
|
||||
public:
|
||||
ProbeLedger() = default;
|
||||
ProbeLedger(const ProbeLedger&) = delete;
|
||||
ProbeLedger& operator=(const ProbeLedger&) = delete;
|
||||
virtual ~ProbeLedger() = default;
|
||||
// The account's probe, created here at the position when the world has none.
|
||||
[[nodiscard]] virtual std::expected<ProbeHome, ProbeLedgerError>
|
||||
open(const network::AccountId& account, std::int64_t x, std::int64_t y, std::int64_t z) = 0;
|
||||
// Best effort: the owned, active probe's position (session end).
|
||||
virtual void save(const network::AccountId& account, std::uint64_t generation, std::int64_t x,
|
||||
std::int64_t y, std::int64_t z) = 0;
|
||||
// Freezes the probe at its final position for `destination`.
|
||||
[[nodiscard]] virtual std::expected<void, ProbeLedgerError>
|
||||
prepare(const network::AccountId& account, std::uint64_t generation,
|
||||
const network::TransferId& transfer, std::uint64_t destination, std::int64_t x,
|
||||
std::int64_t y, std::int64_t z) = 0;
|
||||
// Abandons a transfer whose client never arrived: true when aborted (the probe is active
|
||||
// here again), false when it had been committed.
|
||||
[[nodiscard]] virtual std::expected<bool, ProbeLedgerError>
|
||||
abort(const network::TransferId& transfer) = 0;
|
||||
// Open transfers addressed to this region (shown as ghosts).
|
||||
[[nodiscard]] virtual std::expected<std::vector<IncomingProbe>, ProbeLedgerError>
|
||||
incoming() = 0;
|
||||
|
||||
protected:
|
||||
ProbeLedger(ProbeLedger&&) = default;
|
||||
ProbeLedger& operator=(ProbeLedger&&) = default;
|
||||
};
|
||||
} // namespace evo::server
|
||||
@@ -7,6 +7,7 @@
|
||||
#include "evo/network/session_control.hpp"
|
||||
#include "evo/network/session_grant.hpp"
|
||||
#include "evo/network/session_protocol.hpp"
|
||||
#include "evo/server/probe_ledger.hpp"
|
||||
#include <chrono>
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
@@ -46,6 +47,11 @@ struct IssuerKey {
|
||||
std::uint32_t key_id{};
|
||||
network::GrantPublicKey public_key{};
|
||||
};
|
||||
// A region whose area adjoins this one: where its clients dial and the area it owns.
|
||||
struct Neighbour {
|
||||
network::RegionAddress address;
|
||||
network::motion::Area area; // Micrometres, same slice as this region's.
|
||||
};
|
||||
// A neighbouring region's handoff public key (ADR-0096): tickets it signs are accepted here.
|
||||
struct HandoffKey {
|
||||
std::uint64_t source_region{};
|
||||
@@ -73,6 +79,15 @@ struct RegionSessionsConfig {
|
||||
// ticket also needs a HandoffLedger (control must move durably with the transfer).
|
||||
std::vector<HandoffKey> handoff_keys;
|
||||
network::HandoffLedger* handoff{};
|
||||
// M10.8c: with probe records, a session's marker is the account's durable probe (it opens
|
||||
// where it was saved, a login whose probe lives elsewhere is redirected). With this
|
||||
// region's handoff key and neighbours as well, a marker crossing into a neighbour's area
|
||||
// is frozen, prepared and handed over with a ticket.
|
||||
ProbeLedger* probes{};
|
||||
std::shared_ptr<const network::HandoffSigningKey> handoff_key;
|
||||
std::vector<Neighbour> neighbours;
|
||||
std::uint64_t ticket_lifetime{30}; // Seconds a handoff ticket is valid.
|
||||
std::chrono::milliseconds ghost_poll{1000}; // Incoming transfers read this often.
|
||||
};
|
||||
// The region host's authority, read once per poll.
|
||||
struct HostFacts {
|
||||
@@ -119,7 +134,8 @@ class RegionSessions {
|
||||
const network::Perceives& perceives = {});
|
||||
[[nodiscard]] network::ReplicationStats replication_stats() const;
|
||||
// Where probe markers live and spawn (ADR-0094); sessions already established receive a
|
||||
// marker. False for an invalid area.
|
||||
// marker. False for an invalid area. With neighbours (ADR-0096), markers move within the
|
||||
// bounding box of this area and the neighbours' areas, and leaving this area hands off.
|
||||
[[nodiscard]] bool set_motion_area(const network::motion::Area& area, std::int64_t spawn_x,
|
||||
std::int64_t spawn_y);
|
||||
[[nodiscard]] const network::motion::ProbeMarkers& markers() const noexcept;
|
||||
|
||||
Reference in New Issue
Block a user