Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m45s
Foundation / checks (network) (push) Successful in 9m37s
Foundation / checks (client) (push) Successful in 12m14s
Foundation / checks (tsan) (push) Successful in 7m39s
Foundation / checks (checks) (push) Successful in 31m15s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 32m59s
Session protocol v1 (not yet deployed, amended in place) gains realtime intentions on datagrams with receipts and a cumulative simulated watermark, and account-scoped actions with stable ids, receipts, final outcomes and queries. IntentAdmission enforces session binding, rate, authority, epoch, vector, sequence, tick window, duplicates and the unresolved bound; RegionSessions and the client carry it over QUIC. Intentions and actions have no biological effect yet. ADR-0092. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
164 lines
7.1 KiB
C++
164 lines
7.1 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".
|
|
inline constexpr std::uint16_t session_protocol_version = 1;
|
|
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.
|
|
};
|
|
// 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;
|
|
};
|
|
using SessionMessage =
|
|
std::variant<SessionHello, SessionWelcome, SessionRefresh, SessionRefreshResult, SessionClose,
|
|
SessionIntention, IntentionReceipt, SimulatedThrough, SessionAction, ActionReceipt,
|
|
ActionOutcome, ActionQuery>;
|
|
|
|
[[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
|