Files
aevolution/include/evo/network/session_protocol.hpp
T
dingoandClaude Opus 5.5 e640b6d3a3
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m58s
Foundation / checks (client) (push) Failing after 9m57s
Foundation / checks (network) (push) Successful in 11m17s
Foundation / checks (tsan) (push) Successful in 7m49s
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 25m43s
Foundation / checks (postgres) (push) Canceled after 15m44s
Add M10.5a session protocol v2 and snapshot replication core
Session protocol v2 adds Interest, SnapshotChunk and SnapshotAck (v1 is refused).
ReplicationServer filters by a server-capped client focus and a perception
predicate, sends per-tick entity deltas against the acknowledged baseline (kept
up to 40 ticks), nearest first within 16 KiB with a slower distant tier, as
self-contained datagram chunks. SnapshotAssembler applies complete snapshots to
one of two baselines and validates them as presentations. ADR-0093.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 10:22:11 -04:00

196 lines
8.9 KiB
C++

#pragma once
#include <array>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <span>
#include <variant>
#include <vector>
// M10 session protocol v1 (ADR-0091 session, ADR-0092 intentions and actions;
// schemas/network/session-v1.md). Session, action and outcome messages travel on the QUIC
// reliable stream (one message per framed QUIC message); intentions, their receipts and the
// simulated watermark travel as QUIC DATAGRAMs.
// Each starts with an 8-byte header: magic "EVSN", version u16, type u8, flags u8 (0);
// every payload has a fixed size and explicit little-endian fields. Grants are opaque
// 160-byte credentials here. Later M10 segments add message types under a new version.
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. v1 is frozen
// and no longer accepted (it was only ever deployed to evolution-dev, with the probe).
inline constexpr std::uint16_t session_protocol_version = 2;
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;
enum class SessionMessageType : std::uint8_t {
hello = 1, // Client -> server: grant.
welcome, // Server -> client.
refresh, // Client -> server: newer grant for the open session.
refresh_result, // Server -> client.
close, // Either way, then the sender closes the connection.
intention, // Client -> server, datagram: realtime movement intention.
intention_receipt, // Server -> client, datagram.
simulated_through, // Server -> client, datagram: cumulative simulated watermark.
action, // Client -> server, stream: discrete action with a stable id.
action_receipt, // Server -> client, stream.
action_outcome, // Server -> client, stream: final.
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).
};
// Admission answers for intentions and actions (wire 0..10).
enum class AdmitStatus : std::uint8_t {
admitted = 0,
unknown_session, // Not this connection's session.
stale_epoch,
outside_window, // Tick not in server_tick + 1 ..= server_tick + window.
rate_limited, // Every attempt counts toward the window budget.
replayed, // Intention sequence not above the last admitted one.
invalid_vector,
too_many_unresolved,
invalid_action, // Unknown kind or zero action id.
duplicate, // Action id already known for this account: its state follows.
not_ready // The region has no current authority (starting, recovering, draining).
};
// Wire u16 (SessionAction::kind carries the raw value; admission validates it).
enum class ActionKind : std::uint8_t {
probe = 1 // No effect on biology: proves admission, scheduling and durability (M10.4).
};
enum class ActionResult : std::uint8_t {
committed_no_effect = 1, // Durable in commit `commit_sequence`; changed nothing.
not_committed, // Final: never part of a committed batch.
pending, // Query answer only: admitted, not yet final.
unknown // Query answer only: no record of this action id.
};
// Wire values 1..13. `connection_lost` is local only (the transport ended without a Close).
enum class SessionCloseReason : std::uint8_t {
client_closed = 1,
superseded, // A newer grant for the same account opened another session.
expired,
stale_epoch,
unauthenticated,
wrong_scope, // Environment, world or region.
stale_grant, // Replayed or older than a grant already presented.
rate_limited,
capacity,
protocol,
timeout, // No Hello before the deadline.
unsupported_version,
shutdown,
connection_lost = 255
};
enum class SessionCodecError : std::uint8_t {
truncated,
bad_magic,
unsupported_version,
unknown_type,
reserved_flags,
wrong_length,
invalid_value
};
using WireGrant = std::array<std::uint8_t, session_grant_wire_bytes>;
struct SessionHello {
std::uint32_t required_features{}; // Must be zero in v1.
WireGrant grant{};
};
struct SessionWelcome {
std::uint64_t session{}, epoch{}, world{}, frame{}, region{}, expires_at{};
std::uint64_t server_seconds{}; // Server wall clock at Welcome, for refresh timing.
std::uint64_t server_tick{}; // Simulated tick at Welcome, for scheduling.
friend bool operator==(const SessionWelcome&, const SessionWelcome&) = default;
};
struct SessionRefresh {
WireGrant grant{};
};
// accepted: 0 and the new expiry. Otherwise a refusal reason (stale_grant,
// unauthenticated, wrong_scope, expired, rate_limited); the session keeps its expiry.
struct SessionRefreshResult {
std::uint8_t status{};
std::uint64_t expires_at{};
friend bool operator==(const SessionRefreshResult&, const SessionRefreshResult&) = default;
};
struct SessionClose {
SessionCloseReason reason{};
};
// A movement intention carries only what the player wants: never position, energy or any
// other state claim. Vector components within the M9 bound (norm <= 1000).
struct SessionIntention {
std::uint64_t session{}, epoch{}, sequence{}, tick{};
std::int16_t move_x{}, move_y{};
friend bool operator==(const SessionIntention&, const SessionIntention&) = default;
};
struct IntentionReceipt {
std::uint64_t sequence{};
AdmitStatus status{};
std::uint64_t server_tick{};
friend bool operator==(const IntentionReceipt&, const IntentionReceipt&) = default;
};
// Every admitted intention up to `sequence` whose tick is <= `tick` has been simulated in
// `epoch` (cumulative, so a lost datagram is covered by the next).
struct SimulatedThrough {
std::uint64_t epoch{}, sequence{}, tick{};
friend bool operator==(const SimulatedThrough&, const SimulatedThrough&) = default;
};
struct SessionAction {
std::uint64_t session{}, epoch{}, action_id{};
std::uint16_t kind{}; // Raw wire value: an unknown kind is refused by admission.
std::uint64_t tick{};
friend bool operator==(const SessionAction&, const SessionAction&) = default;
};
// Receipt only: admitted means scheduled for `tick`, never simulated or durable.
struct ActionReceipt {
std::uint64_t action_id{};
AdmitStatus status{};
std::uint64_t server_tick{}, tick{};
friend bool operator==(const ActionReceipt&, const ActionReceipt&) = default;
};
struct ActionOutcome {
std::uint64_t action_id{};
ActionResult result{};
std::uint64_t tick{}, commit_sequence{}; // Zero unless committed_no_effect.
friend bool operator==(const ActionOutcome&, const ActionOutcome&) = default;
};
struct ActionQuery {
std::uint64_t action_id{};
friend bool operator==(const ActionQuery&, const ActionQuery&) = default;
};
// The client's spatial focus: one Z slice, a centre and a radius in cells. The server
// clamps the radius to its maximum and filters authoritatively (ADR-0093).
struct SessionInterest {
std::int64_t x{}, y{}, z{};
std::uint16_t radius{};
friend bool operator==(const SessionInterest&, const SessionInterest&) = default;
};
// One self-contained part of snapshot `tick`, a delta against snapshot `baseline` (0: a
// fresh baseline). `records` are whole entity records (replication.hpp); the snapshot is
// complete when all `count` chunks arrived.
struct SnapshotChunk {
std::uint64_t epoch{}, tick{}, baseline{}, field_revision{}, organism_revision{};
std::uint32_t mask{};
std::int64_t slice_z{};
std::uint8_t index{}, count{};
std::vector<std::uint8_t> records;
friend bool operator==(const SnapshotChunk&, const SnapshotChunk&) = default;
};
inline constexpr std::size_t snapshot_chunk_header_bytes = (5 * 8) + 4 + 8 + 2;
inline constexpr std::size_t max_snapshot_records_bytes =
session_datagram_bytes - session_header_bytes - snapshot_chunk_header_bytes;
// The newest snapshot the client assembled completely and applied.
struct SnapshotAck {
std::uint64_t epoch{}, tick{};
friend bool operator==(const SnapshotAck&, const SnapshotAck&) = default;
};
using SessionMessage =
std::variant<SessionHello, SessionWelcome, SessionRefresh, SessionRefreshResult, SessionClose,
SessionIntention, IntentionReceipt, SimulatedThrough, SessionAction, ActionReceipt,
ActionOutcome, ActionQuery, SessionInterest, SnapshotChunk, SnapshotAck>;
[[nodiscard]] std::vector<std::uint8_t> encode_session(const SessionMessage& message);
// Exactly one message; any other length for its type rejects.
[[nodiscard]] std::expected<SessionMessage, SessionCodecError>
decode_session(std::span<const std::uint8_t> bytes);
} // namespace evo::network