evo-server gains an opt-in M10 listener (--m10-*, QUIC builds only): RegionSessions with the PostgreSQL control and action ledgers on their own connection under the host's lease, carried actions submitted to the host and its acknowledgements and drops turned into outcomes. evo-session-probe is a dev-only headless client. Real process tests cover intentions, durable action outcomes, SIGKILL before and after an action's commit, duplicate retries and the probe. The simulated watermark now reaches every session every tick, so clients always know the server tick. ADR-0092. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.9 KiB
M10 session protocol, version 1
Login, session control, intentions and actions over QUIC (ADR-0090 transport, ADR-0091
identity, ADR-0092 intentions and actions). Implemented by encode_session/decode_session
(include/evo/network/session_protocol.hpp), RegionSessions (server) and
RegionSessionClient (client). Stream messages are one framed QUIC reliable message
each; types 6-8 travel as one QUIC DATAGRAM each, and only after Welcome.
Integers little-endian. Every message has a fixed length for its type; any other length,
magic, version, nonzero flags, unknown type or out-of-range value is refused, and the
server then sends Close (unsupported_version for another version, otherwise
protocol) and closes the connection. v1 has not been deployed; it was amended in place
by M10.4 (types 6-12, Welcome server_tick). After its first deployment, changes need a
new version.
Header (8 bytes)
| Offset | Size | Field | Rule |
|---|---|---|---|
| 0 | 4 | magic | bytes EVSN |
| 4 | 2 | version | 1 |
| 6 | 1 | type | 1..12 below |
| 7 | 1 | flags | 0 |
Messages
| Type | Direction | Payload | Size |
|---|---|---|---|
| 1 Hello | client -> server | required_features u32 (0), grant (session-grant-v1, 160 bytes) | 164 |
| 2 Welcome | server -> client | session, epoch, world, frame, region, expires_at, server_seconds, server_tick (u64 each; session and epoch nonzero) | 64 |
| 3 Refresh | client -> server | newer grant for the same account (160 bytes) | 160 |
| 4 RefreshResult | server -> client | status u8 (0 accepted, else a close reason value), expires_at u64 | 9 |
| 5 Close | either | reason u8 | 1 |
| 6 Intention | client -> server, datagram | session, epoch, sequence, tick (u64), move_x, move_y (i16) | 36 |
| 7 IntentionReceipt | server -> client, datagram | sequence u64, status u8, server_tick u64 | 17 |
| 8 SimulatedThrough | server -> client, datagram | epoch, sequence, tick (u64) | 24 |
| 9 Action | client -> server | session, epoch, action_id (u64), kind u16, tick u64 | 34 |
| 10 ActionReceipt | server -> client | action_id u64, status u8, server_tick u64, tick u64 | 25 |
| 11 ActionOutcome | server -> client | action_id u64, result u8 (1..4), tick u64, commit_sequence u64 | 25 |
| 12 ActionQuery | client -> server | action_id u64 | 8 |
Admission status (wire 0..10): 0 admitted, 1 unknown_session, 2 stale_epoch, 3 outside_window, 4 rate_limited, 5 replayed, 6 invalid_vector, 7 too_many_unresolved, 8 invalid_action, 9 duplicate, 10 not_ready. Action kinds: 1 probe (no effect). Action results: 1 committed_no_effect, 2 not_committed (both final), 3 pending, 4 unknown (query answers only). Intentions carry no state claims; their vector ranges and every action field are checked by admission, which answers with a status rather than closing.
Close reasons (wire 1..13): 1 client_closed, 2 superseded, 3 expired, 4 stale_epoch,
5 unauthenticated, 6 wrong_scope, 7 stale_grant, 8 rate_limited, 9 capacity,
10 protocol, 11 timeout, 12 unsupported_version, 13 shutdown. Value 255
(connection_lost) is local only and never sent.
Sequence and rules
- The client sends Hello first, as soon as the pinned QUIC connection is up. The server
closes with
timeoutif no Hello arrives within 5 s of connecting, and refuses any other first message withprotocol. - Region-wide attempts are counted before the signature is checked (
rate_limited). The grant must verify with one of the region's issuer keys (unauthenticated) for the region's environment (wrong_scope), then pass session control: world/region scope, lifetime, expiry, serial (stale_grant), per-account attempts and capacity. - Welcome confirms the session;
expires_atis the grant's expiry. A newer grant for an account with an open session closes that session's connection withsuperseded. - Refresh renews the open session with a newer grant; a refusal leaves the session and
its expiry unchanged. The server closes a session with
expiredwhen its expiry passes, and every session withstale_epochwhen the region's ownership epoch advances. - Close is followed by closing the connection (the server waits up to 1 s for delivery).
A client that closes its connection without Close is treated as
client_closed. - Reconnecting needs a new connection and a newer grant (ADR-0089).
- Intentions (ADR-0092): one per tick, ticks and sequences increasing, tick within
server_tick + 1 ..= + 8. A receipt only says admitted or refused;
SimulatedThroughsays which admitted intentions' ticks have run (cumulative, sent every simulated tick, sequence 0 before the first; it is also the client's clock for the server tick). Any datagram other than an Intention, or before Welcome, closes withprotocol. - Actions (ADR-0092): ids unique per account and never admitted twice. A receipt only
says scheduled or refused;
ActionOutcomeis sent once the action is final, again after a duplicate of a final action, and in answer toActionQuery.