Add M10.5a session protocol v2 and snapshot replication core
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
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
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>
This commit is contained in:
+4
-2
@@ -32,7 +32,8 @@ add_subdirectory("${mbedtls_source}" "${PROJECT_BINARY_DIR}/mbedtls" EXCLUDE_FRO
|
||||
# Dependency-free protocol: framing, envelopes, admission. No Mbed TLS types.
|
||||
add_library(evo_network_protocol STATIC src/network/protocol/codec.cpp
|
||||
src/network/protocol/admission.cpp src/network/protocol/session_control.cpp
|
||||
src/network/protocol/session_protocol.cpp src/network/protocol/intent_admission.cpp)
|
||||
src/network/protocol/session_protocol.cpp src/network/protocol/intent_admission.cpp
|
||||
src/network/protocol/replication.cpp)
|
||||
target_link_libraries(evo_network_protocol PUBLIC evo_client_views evo_client_controls)
|
||||
evo_owned_target(evo_network_protocol)
|
||||
# Mbed TLS adapters: dev grants (HMAC-SHA256 via PSA) and the TLS 1.3 channel.
|
||||
@@ -59,7 +60,8 @@ target_link_libraries(evo-dev-session PRIVATE evo_network_session)
|
||||
evo_owned_target(evo-dev-session)
|
||||
if(BUILD_TESTING)
|
||||
add_executable(evo-network-tests tests/network_protocol.cpp tests/network_tls.cpp
|
||||
tests/network_session.cpp tests/network_control.cpp tests/network_main.cpp)
|
||||
tests/network_session.cpp tests/network_control.cpp tests/network_replication.cpp
|
||||
tests/network_main.cpp)
|
||||
# The TLS tests generate throwaway dev certificates with Mbed TLS directly.
|
||||
target_link_libraries(evo-network-tests PRIVATE evo_network_session evo_identity mbedtls)
|
||||
evo_owned_target(evo-network-tests)
|
||||
|
||||
+3
-1
@@ -525,7 +525,9 @@ session control done; 10.3b QUIC session login (schemas/network/session-v1.md) d
|
||||
10.4a intention/action protocol and admission done; 10.4b durable action records
|
||||
(schema v11, same transaction as the checkpoint) done; 10.4c evo-server QUIC listener and
|
||||
headless client with process kill tests done. The engineering GUI client still uses the
|
||||
M9 dev path. 10.5-10.9 planned.
|
||||
M9 dev path. 10.5 split (ADR-0093): 10.5a session protocol v2 and the replication core
|
||||
done; 10.5b wiring and process evidence and 10.5c the GUI client switch follow.
|
||||
10.6-10.9 planned.
|
||||
|
||||
**Entry:** M9 client/session evidence and M7/M8 dev/stage durability. Read
|
||||
NETWORK_ARCHITECTURE, PERSISTENCE_ARCHITECTURE and ADR-0017. The M9 transport is
|
||||
|
||||
@@ -42,6 +42,11 @@ behind the ADR-0087 route; session protocol v1 is therefore frozen. The route ad
|
||||
only TCP 7400 while QUIC is UDP, so it is changed to UDP 7400 (ADR-0087 amendment). The
|
||||
route is not yet verified end to end: the edge firewall rule (UDP 7400 from
|
||||
172.10.1.0/24), internal DNS to 172.10.1.202 and a probe run through the VIP remain.
|
||||
M10.5a (ADR-0093) adds session protocol v2 (interest, snapshot chunks, snapshot acks; v1 is
|
||||
refused) and the replication core: server-capped interest with a perception boundary,
|
||||
entity deltas against the acknowledged baseline, nearest first within 16 KiB per tick with
|
||||
a slower distant tier, datagram chunks and client assembly. Next: 10.5b wiring, then the
|
||||
GUI client switch (10.5c).
|
||||
|
||||
## Previous gate - 2026-10-02
|
||||
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# ADR-0093: M10 snapshots, spatial interest and session protocol v2
|
||||
|
||||
## Status
|
||||
Accepted for M10.5 (2026-10-06). Decisions confirmed with the maintainer on 2026-10-06:
|
||||
interest is a client-declared focus capped by the server; snapshots travel as datagram
|
||||
chunks with acknowledgements; 10.5 replicates environment cells plus the organism entity
|
||||
class (currently empty) with a perception boundary; the GUI engineering client moves to
|
||||
M10 sessions within 10.5. Delivery: 10.5a protocol v2 and the replication core (this text),
|
||||
10.5b server/client wiring, probe and process evidence, 10.5c the GUI client switch
|
||||
(msquic.dll in the package, dev grant files). Each segment amends this ADR.
|
||||
|
||||
## Context
|
||||
ADR-0089 fixed per-tick snapshots for entities in interest, a fresh baseline on join, epoch
|
||||
change and loss, at most 4 server baselines of at most 40 ticks per session and 2 on the
|
||||
client, and at most 16 KiB of replication per session per tick; ADR-0090 put superseding
|
||||
state on 1,200-byte QUIC DATAGRAMs. The M9 dev session sent the whole environment view of
|
||||
one slice every tick over TCP (up to 256 cells of about 170 bytes). Session protocol v1 is
|
||||
deployed in evolution-dev and frozen (ADR-0087 amendment). The region has no placed
|
||||
organisms yet; its organism presentation is empty.
|
||||
|
||||
## Decision (10.5a)
|
||||
**Session protocol v2** (schemas/network/session-v2.md) is v1 plus `Interest` (stream),
|
||||
`SnapshotChunk` (datagram) and `SnapshotAck` (datagram). v1 is no longer accepted: its only
|
||||
deployed client was the development probe.
|
||||
|
||||
**Interest.** A session declares one Z slice, a centre and a radius. The server clamps the
|
||||
radius to 7 (15 x 15 cells, within the 256-cell presentation limit) and filters
|
||||
authoritatively: an entity outside the square or the slice is never encoded. Organisms then
|
||||
pass a perception predicate (the extension boundary for concealment and, later, the
|
||||
controlled organism's senses). Records carry the presentation fields only: no controller,
|
||||
owner, account or player/NPC label exists in them. Interest changes restart from a fresh
|
||||
baseline.
|
||||
|
||||
**Snapshots.** Every tick, each interested session gets snapshot `tick`: entity-level
|
||||
upserts and removals against the newest snapshot the client acknowledged, or against
|
||||
nothing (a fresh baseline). The server keeps the acknowledged snapshot plus the newest
|
||||
others, at most 4, none older than 40 ticks; an ack for an evicted or another epoch's
|
||||
snapshot is ignored. Changed entities are sent nearest first (Chebyshev distance from the
|
||||
focus). Distant ones (beyond radius 3) refresh at most every 4 ticks (the lower-rate tier);
|
||||
anything not sent keeps the value the client already holds, so the snapshot's state is
|
||||
exactly what the client will have. A snapshot never exceeds 16 KiB: a fresh 225-cell
|
||||
baseline arrives over about two ticks, nearest first. Unchanged ticks send one empty chunk
|
||||
(the per-tick cadence).
|
||||
|
||||
**Chunks.** A snapshot is split into at most 16 self-contained chunks of whole records,
|
||||
each one datagram of at most 1,200 bytes including headers. The client assembles a snapshot
|
||||
when all chunks arrived, applies it to its baseline (one of its 2 newest applied snapshots),
|
||||
validates the result through the presentation constructors and acknowledges it. A lost
|
||||
chunk leaves the snapshot incomplete; the next delta is against the older acknowledged
|
||||
snapshot. At most 4 snapshots are in assembly. Stale, foreign-epoch and unassemblable chunks
|
||||
are ignored; malformed records, a slice mismatch or disagreeing chunk headers are errors.
|
||||
|
||||
## Consequences and limits
|
||||
- Development-reference figures (32 sessions, 40 ticks, a changing row every tick, record
|
||||
size about 114 bytes): at most 16,320 bytes per session per tick, mean 1,404 bytes, 28,800
|
||||
retained entity states (about 3.5 MB) across all baselines.
|
||||
- Entity-level deltas: a changed cell is resent whole. Field-level deltas or quantization
|
||||
are not needed at this size and are left for measurement (10.9).
|
||||
- Wiring into RegionSessions, evo-server and the clients is 10.5b; until then v2 messages
|
||||
exist but no server sends snapshots.
|
||||
@@ -98,6 +98,7 @@ design. No unadopted candidate is a link dependency of the proof.
|
||||
|
||||
- [ADR-0084: Engineering UI toolkit](0084-engineering-ui-toolkit.md) - Dear ImGui 1.92.9b pinned (M9.8a) and integrated as the engineering client overlay with toolkit-first input routing (M9.8c).
|
||||
- [ADR-0090: M10 QUIC transport](0090-m10-quic-transport.md) - msquic 2.6.2 with OpenSSL 3.5.9 LTS (TLS 1.3 only) from pinned sources on Windows and Linux; DATAGRAM frames for superseding state, streams for reliable actions; M9 TLS/TCP kept as dev fallback; owned impairment relay; exact CA pinning due in 10.2b.
|
||||
- [ADR-0093: M10 snapshots and interest](0093-m10-snapshots-and-interest.md) - session protocol v2: client-declared, server-capped interest (radius <= 7) with a perception boundary; per-tick snapshot chunks as datagrams, entity deltas against the acknowledged baseline (<= 4, <= 40 ticks), nearest first within 16 KiB, distant tier every 4 ticks; client assembly with 2 baselines.
|
||||
- [ADR-0092: M10 intentions and durable outcomes](0092-m10-intentions-and-durable-outcomes.md) - realtime intentions (datagram receipts and a cumulative simulated watermark) and account-scoped actions with stable ids, receipts and final outcomes (committed_no_effect / not_committed); no biological effect until organisms exist; durable action records in the commit transaction (10.4b).
|
||||
- [ADR-0091: M10 session identity and control](0091-m10-session-identity-and-control.md) - provider-independent 128-bit AccountIds, ECDSA P-256 session grants (regions hold public keys only, signed environment byte), per-account serials where the newest grant wins, takeover of an existing session, in-session refresh, bounded attempt rates; identity adapter and issuer as a library; durable control lease follows (10.3c).
|
||||
- [ADR-0089: M10 timing and budgets](0089-m10-timing-and-budgets.md) - ratified 50 ms tick, 1 s flush with final outcomes p95 <= 1.5 s, responsiveness LAN p95 <= 150 ms / 100 ms RTT <= 250 ms, reference hardware; derived scheduling, sequence, baseline, queue/byte/work budgets and exact/tolerant determinism; biological rates will be time-based with deterministic tick conversion and versioned migration in M11.1.
|
||||
|
||||
@@ -4347,3 +4347,36 @@ Probe changes: host names are resolved (IPv4) and printed (`resolved HOST ADDRES
|
||||
`closed` lines name the QUIC transport cause (`RegionSessionClient::transport_cause`).
|
||||
Executed: Windows MSVC preset `quic` build; Linux GCC preset `quic` CTest 4/4; clang-tidy 19
|
||||
on the client, probe and evo-server sources.
|
||||
|
||||
## 2026-10-06 — M10.5a session protocol v2 and replication core (ADR-0093)
|
||||
|
||||
Implemented session protocol v2 (`Interest`, `SnapshotChunk`, `SnapshotAck`; version 1
|
||||
refused), `ReplicationServer` and `SnapshotAssembler` (`include/evo/network/replication.hpp`)
|
||||
and `tests/network_replication.cpp` (part of `evo-network-tests`).
|
||||
Tests: v2 codec round trips, version 1 refused, chunk header rules (baseline >= tick, index
|
||||
>= count, count 0 or > 16, zero epoch or tick), exactly one datagram of records accepted and
|
||||
one byte more refused, every header truncation refused; radius clamped to 7; a fresh
|
||||
225-cell baseline arriving nearest first within 16 KiB per tick over two ticks; nothing
|
||||
outside the interest square ever received; converged ticks sending one empty chunk; a near
|
||||
change sent at once and a far change deferred exactly 4 ticks; removal; a dropped chunk
|
||||
leaving the snapshot unacknowledged and the next delta against the older baseline; the
|
||||
acknowledged baseline kept 40 ticks and a fresh baseline after that; acks for evicted or
|
||||
another epoch's snapshots ignored; a new interest restarting from a fresh baseline with only
|
||||
the new square; concealment (an organism one session may not perceive and organisms outside
|
||||
interest absent from the encoded bytes); client rejection of truncated, unknown-kind and
|
||||
other-slice records and disagreeing chunk headers, stale and foreign-epoch chunks ignored,
|
||||
deltas against unknown baselines dropped, at most 4 assemblies; 32 dense sessions for 40
|
||||
ticks with a changing row (report: max 16,320 bytes per session per tick, mean 1,404,
|
||||
28,800 retained entity states).
|
||||
|
||||
Found and fixed during development: eviction of the acknowledged baseline when acks lag
|
||||
four or more ticks (normal at 100 ms RTT) would have forced fresh baselines (it is now always
|
||||
kept); a dangling reference to an erased assembly entry; enum values cast before validation
|
||||
in the record reader; MSVC narrowing in tuple keys and an ambiguous map erase.
|
||||
|
||||
Executed: Linux GCC 14 preset `quic` CTest 4/4; session tests 10/10 repeated; Clang 19
|
||||
ASan/UBSan session and network tests; clang-tidy 19 on the new and changed sources and
|
||||
tests; format check (only unrelated uncommitted files of the maintainer fail it); Windows
|
||||
MSVC 19.44 preset `quic` build and CTest 4/4 (binaries rebuilt, timestamps checked).
|
||||
Not done: wiring into RegionSessions, evo-server and the clients (10.5b); the GUI client
|
||||
(10.5c).
|
||||
|
||||
@@ -0,0 +1,151 @@
|
||||
#pragma once
|
||||
#include "evo/client/environment_view.hpp"
|
||||
#include "evo/client/organism_view.hpp"
|
||||
#include "evo/network/session_protocol.hpp"
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <deque>
|
||||
#include <expected>
|
||||
#include <functional>
|
||||
#include <map>
|
||||
#include <optional>
|
||||
#include <tuple>
|
||||
#include <utility>
|
||||
#include <vector>
|
||||
|
||||
// M10.5 bounded snapshot replication with spatial interest (ADR-0093). Transport-neutral and
|
||||
// single-owner on both sides.
|
||||
//
|
||||
// Server: every tick, each session's snapshot is a delta against the newest snapshot the
|
||||
// client acknowledged (kept at most `max_baseline_age` ticks, at most `max_baselines` per
|
||||
// session, always including the acknowledged one) or a fresh baseline. Records are whole entities:
|
||||
// upserts and removals. Interest is a client focus (one Z slice, centre, radius) clamped by the
|
||||
// server; organisms also pass a perception predicate, so concealed state is never encoded. Changed
|
||||
// entities are sent nearest first within the per-tick byte budget; distant ones (beyond
|
||||
// `near_radius`) refresh every `far_interval` ticks; anything deferred keeps the value the client
|
||||
// already holds. A snapshot is split into self-contained chunks of whole records, one datagram
|
||||
// each.
|
||||
//
|
||||
// Client: chunks are assembled per snapshot; a complete snapshot is applied to its baseline
|
||||
// (one of the two newest applied snapshots) and acknowledged; presentations are rebuilt
|
||||
// through the validated presentation constructors.
|
||||
namespace evo::network {
|
||||
struct ReplicationLimits {
|
||||
std::uint16_t max_radius{7}; // 15 x 15 cells <= the 256-cell presentation limit.
|
||||
std::uint16_t near_radius{3}; // Updated every tick.
|
||||
std::uint64_t far_interval{4}; // Ticks between updates beyond near_radius.
|
||||
std::size_t max_baselines{4}; // Per session (ADR-0089).
|
||||
std::uint64_t max_baseline_age{40}; // Ticks (2 s, ADR-0089).
|
||||
std::size_t tick_budget_bytes{16384}; // Per session per tick (ADR-0089).
|
||||
std::size_t max_sessions{32};
|
||||
};
|
||||
// The authority's state around one interest, as the host can see it: environment cells
|
||||
// and organisms of one Z slice (already copied out of the region; no store handles).
|
||||
struct ReplicationSource {
|
||||
world::WorldIdentity identity;
|
||||
std::uint64_t field_revision{}, organism_revision{};
|
||||
std::uint32_t mask{};
|
||||
std::vector<client::EnvironmentCell> environment;
|
||||
std::vector<client::OrganismCell> organisms;
|
||||
};
|
||||
// Whether a session may perceive an organism (the perception extension boundary). Spatial
|
||||
// interest is applied first; this decides concealment. Default: everything in interest.
|
||||
using Perceives = std::function<bool(std::uint64_t session, const client::OrganismCell&)>;
|
||||
struct ReplicationStats {
|
||||
std::uint64_t snapshots{}, chunks{}, bytes{}, records{}, deferred{}, fresh_baselines{};
|
||||
std::size_t retained_entities{}; // Entity states held in all sessions' baselines.
|
||||
};
|
||||
enum class ReplicationError : std::uint8_t { invalid_config, unknown_session, full };
|
||||
|
||||
class ReplicationServer {
|
||||
public:
|
||||
[[nodiscard]] static std::expected<ReplicationServer, ReplicationError>
|
||||
create(ReplicationLimits limits);
|
||||
[[nodiscard]] std::expected<void, ReplicationError> open(std::uint64_t session,
|
||||
std::uint64_t epoch);
|
||||
void close(std::uint64_t session);
|
||||
// Clamped to max_radius. A new interest drops the session's baselines (fresh baseline).
|
||||
[[nodiscard]] std::expected<SessionInterest, ReplicationError>
|
||||
set_interest(std::uint64_t session, SessionInterest interest);
|
||||
[[nodiscard]] std::optional<SessionInterest> interest(std::uint64_t session) const;
|
||||
// The client completely applied snapshot `tick` (older or unknown acks are ignored).
|
||||
void acknowledge(std::uint64_t session, const SnapshotAck& ack);
|
||||
// Builds every interested session's snapshot for `tick`. `source` is called once per
|
||||
// distinct interest. `payload` is the largest whole message per datagram.
|
||||
[[nodiscard]] std::vector<std::pair<std::uint64_t, std::vector<SnapshotChunk>>>
|
||||
tick(std::uint64_t tick, const std::function<ReplicationSource(const SessionInterest&)>& source,
|
||||
const Perceives& perceives, std::size_t payload = session_datagram_bytes);
|
||||
[[nodiscard]] ReplicationStats stats() const;
|
||||
|
||||
private:
|
||||
// (kind, x | id, y, z): environment by voxel, organisms by id.
|
||||
using Key = std::tuple<std::uint8_t, std::int64_t, std::int64_t, std::int64_t>;
|
||||
struct Entry {
|
||||
std::vector<std::uint8_t> record; // Encoded upsert record.
|
||||
std::uint64_t updated{}; // Tick this value was sent.
|
||||
bool operator==(const Entry&) const = default;
|
||||
};
|
||||
struct Snapshot {
|
||||
std::uint64_t tick{};
|
||||
std::map<Key, Entry> state;
|
||||
};
|
||||
struct Session {
|
||||
std::uint64_t id{}, epoch{}, acked{};
|
||||
std::optional<SessionInterest> interest;
|
||||
std::deque<Snapshot> baselines;
|
||||
};
|
||||
explicit ReplicationServer(ReplicationLimits limits) : limits_{limits} {}
|
||||
ReplicationLimits limits_;
|
||||
std::vector<Session> sessions_;
|
||||
ReplicationStats stats_;
|
||||
};
|
||||
|
||||
// One applied snapshot as the client holds it.
|
||||
struct ReplicatedView {
|
||||
std::uint64_t tick{}, field_revision{}, organism_revision{};
|
||||
std::uint32_t mask{};
|
||||
std::int64_t slice_z{};
|
||||
std::vector<client::EnvironmentCell> environment; // Sorted by voxel.
|
||||
std::vector<client::OrganismCell> organisms; // Sorted by id.
|
||||
};
|
||||
enum class AssemblyError : std::uint8_t { malformed, invalid_view };
|
||||
|
||||
class SnapshotAssembler {
|
||||
public:
|
||||
explicit SnapshotAssembler(world::WorldIdentity identity, std::uint64_t epoch)
|
||||
: identity_{identity}, epoch_{epoch} {}
|
||||
// A complete snapshot yields its acknowledgement. Stale, foreign-epoch or
|
||||
// unassemblable chunks are ignored; malformed records or views are errors.
|
||||
[[nodiscard]] std::expected<std::optional<SnapshotAck>, AssemblyError>
|
||||
accept(const SnapshotChunk& chunk);
|
||||
[[nodiscard]] const ReplicatedView* latest() const noexcept {
|
||||
return applied_.empty() ? nullptr : &applied_.back();
|
||||
}
|
||||
[[nodiscard]] std::expected<client::EnvironmentPresentation, client::ViewError>
|
||||
environment() const;
|
||||
[[nodiscard]] std::expected<client::OrganismPresentation, client::ViewError> organisms() const;
|
||||
[[nodiscard]] std::size_t partial() const noexcept {
|
||||
return partial_.size();
|
||||
}
|
||||
|
||||
private:
|
||||
struct Partial {
|
||||
SnapshotChunk first; // Header fields of the snapshot.
|
||||
std::vector<std::optional<std::vector<std::uint8_t>>> chunks;
|
||||
};
|
||||
world::WorldIdentity identity_;
|
||||
std::uint64_t epoch_;
|
||||
std::deque<ReplicatedView> applied_; // At most 2 (ADR-0089).
|
||||
std::map<std::uint64_t, Partial> partial_; // At most 4 snapshots in assembly.
|
||||
};
|
||||
|
||||
// Record codec, exposed for tests: one record per entity.
|
||||
enum class RecordKind : std::uint8_t {
|
||||
environment_upsert = 1,
|
||||
environment_remove,
|
||||
organism_upsert,
|
||||
organism_remove
|
||||
};
|
||||
[[nodiscard]] std::vector<std::uint8_t> encode_record(const client::EnvironmentCell& cell);
|
||||
[[nodiscard]] std::vector<std::uint8_t> encode_record(const client::OrganismCell& cell);
|
||||
} // namespace evo::network
|
||||
@@ -16,7 +16,10 @@
|
||||
// 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;
|
||||
// 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;
|
||||
|
||||
@@ -32,7 +35,10 @@ enum class SessionMessageType : std::uint8_t {
|
||||
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.
|
||||
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 {
|
||||
@@ -151,10 +157,36 @@ 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>;
|
||||
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.
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
# M10 session protocol, version 1
|
||||
|
||||
**Superseded by [version 2](session-v2.md) (ADR-0093, 2026-10-06).** Kept as the record of
|
||||
what was deployed in evolution-dev from 2026-10-05; servers built since refuse 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
|
||||
|
||||
@@ -0,0 +1,95 @@
|
||||
# M10 session protocol, version 2
|
||||
|
||||
Login, session control, intentions, actions and snapshots over QUIC (ADR-0090 transport,
|
||||
ADR-0091 identity, ADR-0092 intentions and actions, ADR-0093 snapshots and interest).
|
||||
Version 2 is [version 1](session-v1.md) plus types 13-15; types 1-12 are unchanged. 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, 14 and 15 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. Version 1 messages are refused
|
||||
(`unsupported_version`). Once v2 is deployed it is frozen like v1.
|
||||
|
||||
## Header (8 bytes)
|
||||
| Offset | Size | Field | Rule |
|
||||
|---|---|---|---|
|
||||
| 0 | 4 | magic | bytes `EVSN` |
|
||||
| 4 | 2 | version | 2 |
|
||||
| 6 | 1 | type | 1..15 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 |
|
||||
| 13 Interest | client -> server | x, y, z (i64), radius u16 | 26 |
|
||||
| 14 SnapshotChunk | server -> client, datagram | epoch, tick, baseline, field_revision, organism_revision (u64), mask u32, slice_z i64, index u8, count u8, records | 54 + records, at most 1,200 in all |
|
||||
| 15 SnapshotAck | client -> server, datagram | epoch, tick (u64) | 16 |
|
||||
|
||||
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 `timeout` if no Hello arrives within 5 s of connecting, and refuses any
|
||||
other first message with `protocol`.
|
||||
- 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_at` is the grant's expiry. A newer grant for an
|
||||
account with an open session closes that session's connection with `superseded`.
|
||||
- Refresh renews the open session with a newer grant; a refusal leaves the session and
|
||||
its expiry unchanged. The server closes a session with `expired` when its expiry
|
||||
passes, and every session with `stale_epoch` when 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; `SimulatedThrough`
|
||||
says 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 with `protocol`.
|
||||
- Actions (ADR-0092): ids unique per account and never admitted twice. A receipt only
|
||||
says scheduled or refused; `ActionOutcome` is sent once the action is final, again
|
||||
after a duplicate of a final action, and in answer to `ActionQuery`.
|
||||
- Interest (ADR-0093): the server clamps the radius to 7 and sends only entities in that
|
||||
square of the slice that the session may perceive. A new interest restarts from a fresh
|
||||
baseline.
|
||||
- SnapshotChunk: epoch and tick nonzero; baseline 0 (fresh) or an earlier tick; 1 <= count
|
||||
<= 16; index < count. Records are whole entities, concatenated:
|
||||
|
||||
| Kind | Body |
|
||||
|---|---|
|
||||
| 1 environment upsert | x, y, z (i64), chunk_revision u64, habitat x, y, z, width, height, depth (u32 um), volume u64, substrate, terrain_material, terrain_fill (u16), then per field (10): presence u8 (0 not requested, 1 missing, 2 present) and quantity u64 when present, moisture_status u8 (0..3) and numerator, denominator u64 when available (3) |
|
||||
| 2 environment remove | x, y, z (i64) |
|
||||
| 3 organism upsert | id u64, x, y, z (i64), offset x, y (u32 um), structural_mass, membrane_mass, total_mass (u64), extent u32, surface, maintenance (u64), movement_speed u32, ingestion_rate u64, conversion_per_thousand, thermal_shortfall, realized_per_thousand, damage_per_thousand (u32), state u8 (0 alive, 1 dead) |
|
||||
| 4 organism remove | id u64 |
|
||||
|
||||
Every record's z equals slice_z. The client applies a complete snapshot to its baseline
|
||||
and validates the result as presentations; a malformed record or disagreeing chunk
|
||||
headers are errors.
|
||||
- SnapshotAck names the newest snapshot applied completely; the server sends later deltas
|
||||
against it while it is at most 40 ticks old.
|
||||
@@ -0,0 +1,491 @@
|
||||
#include "evo/network/replication.hpp"
|
||||
#include <algorithm>
|
||||
#include <limits>
|
||||
|
||||
namespace evo::network {
|
||||
namespace {
|
||||
constexpr std::uint8_t max_chunks = 16;
|
||||
constexpr std::size_t max_partial = 4;
|
||||
constexpr std::size_t max_applied = 2;
|
||||
constexpr auto last_presence = static_cast<std::uint8_t>(client::FieldPresence::present);
|
||||
constexpr auto last_moisture = static_cast<std::uint8_t>(world::MoistureStatus::available);
|
||||
constexpr auto last_state = static_cast<std::uint8_t>(client::OrganismState::dead);
|
||||
|
||||
void put(std::vector<std::uint8_t>& out, std::uint64_t v, std::size_t count) {
|
||||
for (std::size_t i = 0; i < count; ++i)
|
||||
out.push_back(static_cast<std::uint8_t>(v >> (8 * i)));
|
||||
}
|
||||
void put_signed(std::vector<std::uint8_t>& out, std::int64_t v) {
|
||||
put(out, static_cast<std::uint64_t>(v), 8);
|
||||
}
|
||||
|
||||
// Bounds-checked little-endian reader; any overrun latches failure.
|
||||
class Reader {
|
||||
public:
|
||||
explicit Reader(std::span<const std::uint8_t> bytes) : bytes_{bytes} {}
|
||||
std::uint64_t u(std::size_t count) {
|
||||
if (!ok_ || bytes_.size() - at_ < count) {
|
||||
ok_ = false;
|
||||
return 0;
|
||||
}
|
||||
std::uint64_t v = 0;
|
||||
for (std::size_t i = 0; i < count; ++i)
|
||||
v |= static_cast<std::uint64_t>(bytes_[at_ + i]) << (8 * i);
|
||||
at_ += count;
|
||||
return v;
|
||||
}
|
||||
std::int64_t i64() {
|
||||
return static_cast<std::int64_t>(u(8));
|
||||
}
|
||||
// An out-of-range value fails the read and yields 0, never an invalid enumerator.
|
||||
std::uint8_t enumerator(std::uint8_t last) {
|
||||
const auto v = static_cast<std::uint8_t>(u(1));
|
||||
if (v > last) {
|
||||
ok_ = false;
|
||||
return 0;
|
||||
}
|
||||
return v;
|
||||
}
|
||||
[[nodiscard]] bool ok() const noexcept {
|
||||
return ok_;
|
||||
}
|
||||
[[nodiscard]] bool done() const noexcept {
|
||||
return at_ == bytes_.size();
|
||||
}
|
||||
|
||||
private:
|
||||
std::span<const std::uint8_t> bytes_;
|
||||
std::size_t at_{};
|
||||
bool ok_{true};
|
||||
};
|
||||
|
||||
std::vector<std::uint8_t> remove_environment(const world::VoxelAddress& v) {
|
||||
std::vector<std::uint8_t> out{static_cast<std::uint8_t>(RecordKind::environment_remove)};
|
||||
for (const auto c : {v.x, v.y, v.z})
|
||||
put_signed(out, c);
|
||||
return out;
|
||||
}
|
||||
std::vector<std::uint8_t> remove_organism(std::uint64_t id) {
|
||||
std::vector<std::uint8_t> out{static_cast<std::uint8_t>(RecordKind::organism_remove)};
|
||||
put(out, id, 8);
|
||||
return out;
|
||||
}
|
||||
std::uint64_t distance(std::int64_t x, std::int64_t y, const SessionInterest& i) {
|
||||
const auto dx =
|
||||
x > i.x ? static_cast<std::uint64_t>(x - i.x) : static_cast<std::uint64_t>(i.x - x);
|
||||
const auto dy =
|
||||
y > i.y ? static_cast<std::uint64_t>(y - i.y) : static_cast<std::uint64_t>(i.y - y);
|
||||
return std::max(dx, dy); // Chebyshev: the interest is a square.
|
||||
}
|
||||
} // namespace
|
||||
|
||||
std::vector<std::uint8_t> encode_record(const client::EnvironmentCell& c) {
|
||||
std::vector<std::uint8_t> out{static_cast<std::uint8_t>(RecordKind::environment_upsert)};
|
||||
for (const auto v : {c.voxel.x, c.voxel.y, c.voxel.z})
|
||||
put_signed(out, v);
|
||||
put(out, c.chunk_revision, 8);
|
||||
for (const auto v : {c.habitat.x, c.habitat.y, c.habitat.z, c.habitat.width, c.habitat.height,
|
||||
c.habitat.depth})
|
||||
put(out, static_cast<std::uint32_t>(v.value), 4); // Validated <= 1e6 um.
|
||||
put(out, c.volume.value, 8);
|
||||
put(out, c.substrate.value, 2);
|
||||
put(out, c.terrain_material.value, 2);
|
||||
put(out, c.terrain_fill, 2);
|
||||
for (std::size_t k = 0; k < world::field_count; ++k) {
|
||||
out.push_back(static_cast<std::uint8_t>(c.presence.at(k)));
|
||||
if (c.presence.at(k) == client::FieldPresence::present)
|
||||
put(out, c.quantity.at(k), 8);
|
||||
}
|
||||
out.push_back(static_cast<std::uint8_t>(c.moisture_status));
|
||||
if (c.moisture_status == world::MoistureStatus::available) {
|
||||
put(out, c.moisture.numerator, 8);
|
||||
put(out, c.moisture.denominator, 8);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
std::vector<std::uint8_t> encode_record(const client::OrganismCell& c) {
|
||||
std::vector<std::uint8_t> out{static_cast<std::uint8_t>(RecordKind::organism_upsert)};
|
||||
const auto& p = c.phenotype;
|
||||
put(out, c.id, 8);
|
||||
for (const auto v : {c.voxel.x, c.voxel.y, c.voxel.z})
|
||||
put_signed(out, v);
|
||||
put(out, static_cast<std::uint32_t>(c.x.value), 4); // Validated < 1e6 um.
|
||||
put(out, static_cast<std::uint32_t>(c.y.value), 4);
|
||||
put(out, p.structural_mass, 8);
|
||||
put(out, p.membrane_mass, 8);
|
||||
put(out, p.total_mass, 8);
|
||||
put(out, p.extent, 4);
|
||||
put(out, p.surface, 8);
|
||||
put(out, p.maintenance, 8);
|
||||
put(out, p.movement_speed, 4);
|
||||
put(out, p.ingestion_rate, 8);
|
||||
put(out, p.conversion_per_thousand, 4);
|
||||
put(out, p.thermal_shortfall, 4);
|
||||
put(out, c.growth.realized_per_thousand, 4);
|
||||
put(out, c.growth.damage_per_thousand, 4);
|
||||
out.push_back(static_cast<std::uint8_t>(c.state));
|
||||
return out;
|
||||
}
|
||||
|
||||
std::expected<ReplicationServer, ReplicationError> ReplicationServer::create(ReplicationLimits l) {
|
||||
if (l.max_radius == 0 || l.max_radius > 7 || l.near_radius > l.max_radius ||
|
||||
l.far_interval == 0 || l.max_baselines == 0 || l.max_baselines > 16 ||
|
||||
l.max_baseline_age == 0 || l.tick_budget_bytes < session_datagram_bytes ||
|
||||
l.tick_budget_bytes > std::size_t{max_chunks} * session_datagram_bytes ||
|
||||
l.max_sessions == 0 || l.max_sessions > 1024)
|
||||
return std::unexpected(ReplicationError::invalid_config);
|
||||
return ReplicationServer{l};
|
||||
}
|
||||
|
||||
std::expected<void, ReplicationError> ReplicationServer::open(std::uint64_t session,
|
||||
std::uint64_t epoch) {
|
||||
if (session == 0 || epoch == 0 ||
|
||||
std::ranges::any_of(sessions_, [&](const Session& s) { return s.id == session; }))
|
||||
return std::unexpected(ReplicationError::invalid_config);
|
||||
if (sessions_.size() >= limits_.max_sessions)
|
||||
return std::unexpected(ReplicationError::full);
|
||||
Session s;
|
||||
s.id = session;
|
||||
s.epoch = epoch;
|
||||
sessions_.push_back(std::move(s));
|
||||
return {};
|
||||
}
|
||||
|
||||
void ReplicationServer::close(std::uint64_t session) {
|
||||
std::erase_if(sessions_, [&](const Session& s) { return s.id == session; });
|
||||
}
|
||||
|
||||
std::expected<SessionInterest, ReplicationError>
|
||||
ReplicationServer::set_interest(std::uint64_t session, SessionInterest interest) {
|
||||
const auto it =
|
||||
std::ranges::find_if(sessions_, [&](const Session& s) { return s.id == session; });
|
||||
if (it == sessions_.end())
|
||||
return std::unexpected(ReplicationError::unknown_session);
|
||||
interest.radius = std::min(interest.radius, limits_.max_radius);
|
||||
if (it->interest != interest) {
|
||||
it->interest = interest;
|
||||
it->baselines.clear(); // Another area: start from a fresh baseline.
|
||||
it->acked = 0;
|
||||
}
|
||||
return interest;
|
||||
}
|
||||
|
||||
std::optional<SessionInterest> ReplicationServer::interest(std::uint64_t session) const {
|
||||
const auto it =
|
||||
std::ranges::find_if(sessions_, [&](const Session& s) { return s.id == session; });
|
||||
return it == sessions_.end() ? std::nullopt : it->interest;
|
||||
}
|
||||
|
||||
void ReplicationServer::acknowledge(std::uint64_t session, const SnapshotAck& ack) {
|
||||
const auto it =
|
||||
std::ranges::find_if(sessions_, [&](const Session& s) { return s.id == session; });
|
||||
if (it == sessions_.end() || ack.epoch != it->epoch || ack.tick <= it->acked)
|
||||
return;
|
||||
if (std::ranges::any_of(it->baselines, [&](const Snapshot& b) { return b.tick == ack.tick; }))
|
||||
it->acked = ack.tick;
|
||||
}
|
||||
|
||||
std::vector<std::pair<std::uint64_t, std::vector<SnapshotChunk>>>
|
||||
ReplicationServer::tick(std::uint64_t tick,
|
||||
const std::function<ReplicationSource(const SessionInterest&)>& source,
|
||||
const Perceives& perceives, std::size_t payload) {
|
||||
std::vector<std::pair<std::uint64_t, std::vector<SnapshotChunk>>> out;
|
||||
payload = std::min(payload, session_datagram_bytes);
|
||||
const auto overhead = session_header_bytes + snapshot_chunk_header_bytes;
|
||||
if (tick == 0 || payload <= overhead)
|
||||
return out;
|
||||
const auto capacity = payload - overhead; // Record bytes per chunk.
|
||||
std::vector<std::pair<SessionInterest, ReplicationSource>> sources;
|
||||
for (auto& s : sessions_) {
|
||||
if (!s.interest || (!s.baselines.empty() && s.baselines.back().tick >= tick))
|
||||
continue;
|
||||
const auto& in = *s.interest;
|
||||
auto cached = std::ranges::find_if(sources, [&](const auto& e) { return e.first == in; });
|
||||
if (cached == sources.end()) {
|
||||
sources.emplace_back(in, source(in));
|
||||
cached = std::prev(sources.end());
|
||||
}
|
||||
const auto& src = cached->second;
|
||||
// Spatial filter, then perception: nothing outside either is ever encoded.
|
||||
std::map<Key, std::pair<std::vector<std::uint8_t>, std::uint64_t>> truth;
|
||||
for (const auto& c : src.environment)
|
||||
if (c.voxel.z == in.z && distance(c.voxel.x, c.voxel.y, in) <= in.radius)
|
||||
truth[Key{std::uint8_t{1}, c.voxel.x, c.voxel.y, c.voxel.z}] = {
|
||||
encode_record(c), distance(c.voxel.x, c.voxel.y, in)};
|
||||
for (const auto& o : src.organisms)
|
||||
if (o.voxel.z == in.z && distance(o.voxel.x, o.voxel.y, in) <= in.radius &&
|
||||
(!perceives || perceives(s.id, o)))
|
||||
truth[Key{std::uint8_t{3}, static_cast<std::int64_t>(o.id), 0, 0}] = {
|
||||
encode_record(o), distance(o.voxel.x, o.voxel.y, in)};
|
||||
// Baselines older than the limit are forgotten; an expired ack means a fresh one.
|
||||
while (!s.baselines.empty() && tick - s.baselines.front().tick > limits_.max_baseline_age)
|
||||
s.baselines.pop_front();
|
||||
const auto base = std::ranges::find_if(
|
||||
s.baselines, [&](const Snapshot& b) { return s.acked != 0 && b.tick == s.acked; });
|
||||
const bool fresh = base == s.baselines.end();
|
||||
static const std::map<Key, Entry> empty;
|
||||
const auto& base_state = fresh ? empty : base->state;
|
||||
struct Candidate {
|
||||
std::uint64_t distance{}, staleness{};
|
||||
Key key;
|
||||
const std::vector<std::uint8_t>* record{};
|
||||
};
|
||||
std::vector<std::vector<std::uint8_t>> removals;
|
||||
std::vector<Key> removed;
|
||||
for (const auto& [key, entry] : base_state)
|
||||
if (!truth.contains(key)) {
|
||||
removals.push_back(
|
||||
std::get<0>(key) == 1
|
||||
? remove_environment({std::get<1>(key), std::get<2>(key), std::get<3>(key)})
|
||||
: remove_organism(static_cast<std::uint64_t>(std::get<1>(key))));
|
||||
removed.push_back(key);
|
||||
}
|
||||
std::vector<Candidate> candidates;
|
||||
std::uint64_t deferred = 0;
|
||||
for (const auto& [key, value] : truth) {
|
||||
const auto known = base_state.find(key);
|
||||
if (known != base_state.end() && known->second.record == value.first)
|
||||
continue; // The client already holds this value.
|
||||
const bool due = known == base_state.end() || value.second <= limits_.near_radius ||
|
||||
tick - known->second.updated >= limits_.far_interval;
|
||||
if (!due) {
|
||||
++deferred;
|
||||
continue;
|
||||
}
|
||||
const auto staleness = known == base_state.end()
|
||||
? std::numeric_limits<std::uint64_t>::max()
|
||||
: tick - known->second.updated;
|
||||
candidates.push_back({value.second, staleness, key, &value.first});
|
||||
}
|
||||
std::ranges::sort(candidates, [](const Candidate& a, const Candidate& b) {
|
||||
return std::tie(a.distance, b.staleness, a.key) <
|
||||
std::tie(b.distance, a.staleness, b.key);
|
||||
});
|
||||
// Pack whole records: removals first, then the nearest changes, within the budget.
|
||||
std::vector<std::vector<std::uint8_t>> chunks(1);
|
||||
std::size_t bytes = overhead;
|
||||
const auto fits = [&](const std::vector<std::uint8_t>& record) {
|
||||
if (chunks.back().size() + record.size() <= capacity) {
|
||||
if (bytes + record.size() > limits_.tick_budget_bytes)
|
||||
return false;
|
||||
} else {
|
||||
if (chunks.size() >= max_chunks || record.size() > capacity ||
|
||||
bytes + overhead + record.size() > limits_.tick_budget_bytes)
|
||||
return false;
|
||||
chunks.emplace_back();
|
||||
bytes += overhead;
|
||||
}
|
||||
chunks.back().insert(chunks.back().end(), record.begin(), record.end());
|
||||
bytes += record.size();
|
||||
return true;
|
||||
};
|
||||
auto state = base_state;
|
||||
std::uint64_t sent = 0;
|
||||
for (std::size_t i = 0; i < removals.size(); ++i) {
|
||||
if (!fits(removals[i])) {
|
||||
deferred += removals.size() - i; // Removed next tick; the client keeps them.
|
||||
break;
|
||||
}
|
||||
state.erase(removed[i]);
|
||||
++sent;
|
||||
}
|
||||
for (std::size_t i = 0; i < candidates.size(); ++i) {
|
||||
if (!fits(*candidates[i].record)) {
|
||||
deferred += candidates.size() - i;
|
||||
break;
|
||||
}
|
||||
state[candidates[i].key] = Entry{*candidates[i].record, tick};
|
||||
++sent;
|
||||
}
|
||||
std::vector<SnapshotChunk> messages;
|
||||
for (std::size_t i = 0; i < chunks.size(); ++i) {
|
||||
SnapshotChunk m;
|
||||
m.epoch = s.epoch;
|
||||
m.tick = tick;
|
||||
m.baseline = fresh ? 0 : base->tick;
|
||||
m.field_revision = src.field_revision;
|
||||
m.organism_revision = src.organism_revision;
|
||||
m.mask = src.mask;
|
||||
m.slice_z = in.z;
|
||||
m.index = static_cast<std::uint8_t>(i);
|
||||
m.count = static_cast<std::uint8_t>(chunks.size());
|
||||
m.records = std::move(chunks[i]);
|
||||
messages.push_back(std::move(m));
|
||||
}
|
||||
stats_.snapshots += 1;
|
||||
stats_.chunks += messages.size();
|
||||
stats_.bytes += bytes;
|
||||
stats_.deferred += deferred;
|
||||
stats_.fresh_baselines += fresh ? 1 : 0;
|
||||
stats_.records += sent;
|
||||
s.baselines.push_back({tick, std::move(state)});
|
||||
// Keep the acknowledged baseline (acks lag by the round trip) and the newest others.
|
||||
while (s.baselines.size() > limits_.max_baselines)
|
||||
s.baselines.erase(std::ranges::find_if(
|
||||
s.baselines, [&](const Snapshot& b) { return b.tick != s.acked; }));
|
||||
out.emplace_back(s.id, std::move(messages));
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
ReplicationStats ReplicationServer::stats() const {
|
||||
auto s = stats_;
|
||||
s.retained_entities = 0;
|
||||
for (const auto& session : sessions_)
|
||||
for (const auto& b : session.baselines)
|
||||
s.retained_entities += b.state.size();
|
||||
return s;
|
||||
}
|
||||
|
||||
std::expected<std::optional<SnapshotAck>, AssemblyError>
|
||||
SnapshotAssembler::accept(const SnapshotChunk& chunk) {
|
||||
const std::uint64_t newest = applied_.empty() ? 0 : applied_.back().tick;
|
||||
if (chunk.epoch != epoch_ || chunk.tick <= newest)
|
||||
return std::optional<SnapshotAck>{}; // Stale or another epoch: ignored.
|
||||
auto found = partial_.find(chunk.tick);
|
||||
if (found == partial_.end()) {
|
||||
if (partial_.size() >= max_partial)
|
||||
partial_.erase(partial_.begin()); // The oldest assembly gives way.
|
||||
Partial p;
|
||||
p.first = chunk;
|
||||
p.first.records.clear();
|
||||
p.chunks.resize(chunk.count);
|
||||
found = partial_.emplace(chunk.tick, std::move(p)).first;
|
||||
}
|
||||
auto& p = found->second;
|
||||
const auto h = p.first; // A copy: the assembly entry is erased below.
|
||||
if (h.baseline != chunk.baseline || h.count != chunk.count || h.mask != chunk.mask ||
|
||||
h.slice_z != chunk.slice_z || h.field_revision != chunk.field_revision ||
|
||||
h.organism_revision != chunk.organism_revision)
|
||||
return std::unexpected(AssemblyError::malformed);
|
||||
if (!p.chunks.at(chunk.index))
|
||||
p.chunks.at(chunk.index) = chunk.records;
|
||||
if (std::ranges::any_of(p.chunks, [](const auto& c) { return !c.has_value(); }))
|
||||
return std::optional<SnapshotAck>{};
|
||||
// Complete: apply to its baseline, which must be one this client still holds.
|
||||
const ReplicatedView* base = nullptr;
|
||||
if (h.baseline != 0) {
|
||||
const auto it = std::ranges::find_if(
|
||||
applied_, [&](const ReplicatedView& v) { return v.tick == h.baseline; });
|
||||
if (it == applied_.end()) {
|
||||
partial_.erase(found);
|
||||
return std::optional<SnapshotAck>{}; // The server falls back to a fresh baseline.
|
||||
}
|
||||
base = &*it;
|
||||
}
|
||||
std::map<std::pair<std::int64_t, std::int64_t>, client::EnvironmentCell> environment;
|
||||
std::map<std::uint64_t, client::OrganismCell> organisms;
|
||||
if (base) {
|
||||
for (const auto& c : base->environment)
|
||||
environment[{c.voxel.x, c.voxel.y}] = c;
|
||||
for (const auto& o : base->organisms)
|
||||
organisms[o.id] = o;
|
||||
}
|
||||
for (const auto& records : p.chunks) {
|
||||
if (!records)
|
||||
return std::unexpected(AssemblyError::malformed); // Unreachable: all present.
|
||||
Reader r{*records};
|
||||
while (r.ok() && !r.done()) {
|
||||
const auto kind = r.u(1);
|
||||
if (kind == static_cast<std::uint8_t>(RecordKind::environment_upsert)) {
|
||||
client::EnvironmentCell c;
|
||||
c.voxel = {r.i64(), r.i64(), r.i64()};
|
||||
c.chunk_revision = r.u(8);
|
||||
c.habitat = {{r.u(4)}, {r.u(4)}, {r.u(4)}, {r.u(4)}, {r.u(4)}, {r.u(4)}};
|
||||
c.volume = {r.u(8)};
|
||||
c.substrate = {static_cast<std::uint16_t>(r.u(2))};
|
||||
c.terrain_material = {static_cast<std::uint16_t>(r.u(2))};
|
||||
c.terrain_fill = static_cast<std::uint16_t>(r.u(2));
|
||||
for (std::size_t k = 0; k < world::field_count; ++k) {
|
||||
c.presence.at(k) =
|
||||
static_cast<client::FieldPresence>(r.enumerator(last_presence));
|
||||
if (c.presence.at(k) == client::FieldPresence::present)
|
||||
c.quantity.at(k) = r.u(8);
|
||||
}
|
||||
c.moisture_status = static_cast<world::MoistureStatus>(r.enumerator(last_moisture));
|
||||
if (c.moisture_status == world::MoistureStatus::available)
|
||||
c.moisture = {r.u(8), r.u(8)};
|
||||
if (c.voxel.z != h.slice_z)
|
||||
return std::unexpected(AssemblyError::malformed);
|
||||
environment[{c.voxel.x, c.voxel.y}] = c;
|
||||
} else if (kind == static_cast<std::uint8_t>(RecordKind::environment_remove)) {
|
||||
const auto x = r.i64(), y = r.i64(), z = r.i64();
|
||||
if (z != h.slice_z)
|
||||
return std::unexpected(AssemblyError::malformed);
|
||||
environment.erase({x, y});
|
||||
} else if (kind == static_cast<std::uint8_t>(RecordKind::organism_upsert)) {
|
||||
client::OrganismCell o;
|
||||
o.id = r.u(8);
|
||||
o.voxel = {r.i64(), r.i64(), r.i64()};
|
||||
o.x = {r.u(4)};
|
||||
o.y = {r.u(4)};
|
||||
auto& ph = o.phenotype;
|
||||
ph.structural_mass = r.u(8);
|
||||
ph.membrane_mass = r.u(8);
|
||||
ph.total_mass = r.u(8);
|
||||
ph.extent = static_cast<std::uint32_t>(r.u(4));
|
||||
ph.surface = r.u(8);
|
||||
ph.maintenance = r.u(8);
|
||||
ph.movement_speed = static_cast<std::uint32_t>(r.u(4));
|
||||
ph.ingestion_rate = r.u(8);
|
||||
ph.conversion_per_thousand = static_cast<std::uint32_t>(r.u(4));
|
||||
ph.thermal_shortfall = static_cast<std::uint32_t>(r.u(4));
|
||||
o.growth.realized_per_thousand = static_cast<std::uint32_t>(r.u(4));
|
||||
o.growth.damage_per_thousand = static_cast<std::uint32_t>(r.u(4));
|
||||
o.state = static_cast<client::OrganismState>(r.enumerator(last_state));
|
||||
if (o.voxel.z != h.slice_z)
|
||||
return std::unexpected(AssemblyError::malformed);
|
||||
organisms[o.id] = o;
|
||||
} else if (kind == static_cast<std::uint8_t>(RecordKind::organism_remove)) {
|
||||
organisms.erase(r.u(8));
|
||||
} else {
|
||||
return std::unexpected(AssemblyError::malformed);
|
||||
}
|
||||
}
|
||||
if (!r.ok())
|
||||
return std::unexpected(AssemblyError::malformed);
|
||||
}
|
||||
ReplicatedView view;
|
||||
view.tick = h.tick;
|
||||
view.field_revision = h.field_revision;
|
||||
view.organism_revision = h.organism_revision;
|
||||
view.mask = h.mask;
|
||||
view.slice_z = h.slice_z;
|
||||
for (auto& [voxel, cell] : environment)
|
||||
view.environment.push_back(cell);
|
||||
for (auto& [id, organism] : organisms)
|
||||
view.organisms.push_back(organism);
|
||||
// The same validation as any presentation: a snapshot that cannot be shown is refused.
|
||||
if (!client::EnvironmentPresentation::create({identity_, view.tick, view.field_revision},
|
||||
view.mask, view.slice_z, view.environment) &&
|
||||
!view.environment.empty())
|
||||
return std::unexpected(AssemblyError::invalid_view);
|
||||
if (!client::OrganismPresentation::create({identity_, view.tick, view.organism_revision},
|
||||
view.slice_z, view.organisms))
|
||||
return std::unexpected(AssemblyError::invalid_view);
|
||||
applied_.push_back(std::move(view));
|
||||
while (applied_.size() > max_applied)
|
||||
applied_.pop_front();
|
||||
std::erase_if(partial_, [&](const auto& e) { return e.first <= h.tick; });
|
||||
return std::optional<SnapshotAck>{SnapshotAck{epoch_, applied_.back().tick}};
|
||||
}
|
||||
|
||||
std::expected<client::EnvironmentPresentation, client::ViewError>
|
||||
SnapshotAssembler::environment() const {
|
||||
if (applied_.empty())
|
||||
return std::unexpected(client::ViewError::empty_slice);
|
||||
const auto& v = applied_.back();
|
||||
return client::EnvironmentPresentation::create({identity_, v.tick, v.field_revision}, v.mask,
|
||||
v.slice_z, v.environment);
|
||||
}
|
||||
|
||||
std::expected<client::OrganismPresentation, client::ViewError>
|
||||
SnapshotAssembler::organisms() const {
|
||||
if (applied_.empty())
|
||||
return std::unexpected(client::ViewError::empty_slice);
|
||||
const auto& v = applied_.back();
|
||||
return client::OrganismPresentation::create({identity_, v.tick, v.organism_revision}, v.slice_z,
|
||||
v.organisms);
|
||||
}
|
||||
} // namespace evo::network
|
||||
@@ -16,6 +16,9 @@ constexpr std::size_t action_receipt_bytes = 8 + 1 + 8 + 8;
|
||||
constexpr std::size_t action_outcome_bytes = 8 + 1 + 8 + 8;
|
||||
constexpr std::size_t action_query_bytes = 8;
|
||||
constexpr std::uint8_t max_admit_status = static_cast<std::uint8_t>(AdmitStatus::not_ready);
|
||||
constexpr std::size_t interest_bytes = (3 * std::size_t{8}) + 2;
|
||||
constexpr std::size_t snapshot_ack_bytes = 2 * std::size_t{8};
|
||||
constexpr std::uint8_t max_snapshot_chunks = 16;
|
||||
|
||||
void put(std::vector<std::uint8_t>& out, std::uint64_t v, std::size_t count) {
|
||||
for (std::size_t i = 0; i < count; ++i)
|
||||
@@ -128,6 +131,32 @@ std::vector<std::uint8_t> encode_session(const SessionMessage& message) {
|
||||
put(out, m.action_id, 8);
|
||||
return out;
|
||||
}
|
||||
std::vector<std::uint8_t> operator()(const SessionInterest& m) const {
|
||||
auto out = header(SessionMessageType::interest, interest_bytes);
|
||||
for (const auto v : {m.x, m.y, m.z})
|
||||
put(out, static_cast<std::uint64_t>(v), 8);
|
||||
put(out, m.radius, 2);
|
||||
return out;
|
||||
}
|
||||
std::vector<std::uint8_t> operator()(const SnapshotChunk& m) const {
|
||||
auto out = header(SessionMessageType::snapshot_chunk,
|
||||
snapshot_chunk_header_bytes + m.records.size());
|
||||
for (const auto v :
|
||||
{m.epoch, m.tick, m.baseline, m.field_revision, m.organism_revision})
|
||||
put(out, v, 8);
|
||||
put(out, m.mask, 4);
|
||||
put(out, static_cast<std::uint64_t>(m.slice_z), 8);
|
||||
out.push_back(m.index);
|
||||
out.push_back(m.count);
|
||||
out.insert(out.end(), m.records.begin(), m.records.end());
|
||||
return out;
|
||||
}
|
||||
std::vector<std::uint8_t> operator()(const SnapshotAck& m) const {
|
||||
auto out = header(SessionMessageType::snapshot_ack, snapshot_ack_bytes);
|
||||
put(out, m.epoch, 8);
|
||||
put(out, m.tick, 8);
|
||||
return out;
|
||||
}
|
||||
};
|
||||
return std::visit(Encoder{}, message);
|
||||
}
|
||||
@@ -243,6 +272,40 @@ decode_session(std::span<const std::uint8_t> bytes) {
|
||||
return std::unexpected(SessionCodecError::wrong_length);
|
||||
return ActionQuery{get(payload, 0, 8)};
|
||||
}
|
||||
case static_cast<std::uint8_t>(SessionMessageType::interest): {
|
||||
if (!expect(interest_bytes))
|
||||
return std::unexpected(SessionCodecError::wrong_length);
|
||||
return SessionInterest{static_cast<std::int64_t>(get(payload, 0, 8)),
|
||||
static_cast<std::int64_t>(get(payload, 8, 8)),
|
||||
static_cast<std::int64_t>(get(payload, 16, 8)),
|
||||
static_cast<std::uint16_t>(get(payload, 24, 2))};
|
||||
}
|
||||
case static_cast<std::uint8_t>(SessionMessageType::snapshot_chunk): {
|
||||
// Variable length: a fixed header and up to one datagram of records.
|
||||
if (payload.size() < snapshot_chunk_header_bytes ||
|
||||
payload.size() > snapshot_chunk_header_bytes + max_snapshot_records_bytes)
|
||||
return std::unexpected(SessionCodecError::wrong_length);
|
||||
SnapshotChunk m;
|
||||
m.epoch = get(payload, 0, 8);
|
||||
m.tick = get(payload, 8, 8);
|
||||
m.baseline = get(payload, 16, 8);
|
||||
m.field_revision = get(payload, 24, 8);
|
||||
m.organism_revision = get(payload, 32, 8);
|
||||
m.mask = static_cast<std::uint32_t>(get(payload, 40, 4));
|
||||
m.slice_z = static_cast<std::int64_t>(get(payload, 44, 8));
|
||||
m.index = payload[52];
|
||||
m.count = payload[53];
|
||||
if (m.epoch == 0 || m.tick == 0 || m.baseline >= m.tick || m.count == 0 ||
|
||||
m.count > max_snapshot_chunks || m.index >= m.count)
|
||||
return std::unexpected(SessionCodecError::invalid_value);
|
||||
m.records.assign(payload.begin() + snapshot_chunk_header_bytes, payload.end());
|
||||
return m;
|
||||
}
|
||||
case static_cast<std::uint8_t>(SessionMessageType::snapshot_ack): {
|
||||
if (!expect(snapshot_ack_bytes))
|
||||
return std::unexpected(SessionCodecError::wrong_length);
|
||||
return SnapshotAck{get(payload, 0, 8), get(payload, 8, 8)};
|
||||
}
|
||||
default:
|
||||
return std::unexpected(SessionCodecError::unknown_type);
|
||||
}
|
||||
|
||||
@@ -362,12 +362,12 @@ void session_codec() {
|
||||
mutated.at(0) ^= 1;
|
||||
CHECK(refused(decode_session(mutated), SessionCodecError::bad_magic));
|
||||
mutated = bytes;
|
||||
mutated.at(4) = 2;
|
||||
mutated.at(4) = 3;
|
||||
CHECK(refused(decode_session(mutated), SessionCodecError::unsupported_version));
|
||||
mutated = bytes;
|
||||
mutated.at(7) = 1;
|
||||
CHECK(refused(decode_session(mutated), SessionCodecError::reserved_flags));
|
||||
for (const auto type : std::array<std::uint8_t, 3>{0, 13, 255}) {
|
||||
for (const auto type : std::array<std::uint8_t, 3>{0, 16, 255}) {
|
||||
mutated = bytes;
|
||||
mutated.at(6) = type;
|
||||
CHECK(refused(decode_session(mutated), SessionCodecError::unknown_type));
|
||||
|
||||
@@ -7,6 +7,7 @@ int main() try {
|
||||
evo::network_test::tls_tests();
|
||||
evo::network_test::session_tests();
|
||||
evo::network_test::control_tests();
|
||||
evo::network_test::replication_tests();
|
||||
std::puts("network tests passed");
|
||||
return 0;
|
||||
} catch (const std::exception& e) {
|
||||
|
||||
@@ -0,0 +1,393 @@
|
||||
// M10.5 replication tests (ADR-0093): session protocol v2 snapshot messages, server-side
|
||||
// interest, deltas, budgets, baselines and concealment; client-side assembly.
|
||||
#include "evo/biology/genome.hpp"
|
||||
#include "evo/network/replication.hpp"
|
||||
#include "network_test.hpp"
|
||||
#include <algorithm>
|
||||
#include <cstdio>
|
||||
#include <map>
|
||||
#include <set>
|
||||
#include <vector>
|
||||
|
||||
namespace evo::network_test {
|
||||
namespace {
|
||||
using namespace evo::network;
|
||||
constexpr world::WorldIdentity identity{11, 12};
|
||||
constexpr std::uint32_t mask = (1U << 0) | (1U << 1) | (1U << 7);
|
||||
constexpr std::int64_t slice = -7;
|
||||
|
||||
client::EnvironmentCell cell(std::int64_t x, std::int64_t y, std::uint64_t quantity = 30) {
|
||||
client::EnvironmentCell c;
|
||||
c.voxel = {x, y, slice};
|
||||
c.chunk_revision = 40;
|
||||
c.habitat = {{100}, {200}, {0}, {1000}, {500}, {10}};
|
||||
c.volume = {1000ULL * 500 * 10};
|
||||
c.substrate = {1};
|
||||
c.terrain_material = {2};
|
||||
c.terrain_fill = 1000;
|
||||
c.presence[0] = client::FieldPresence::present;
|
||||
c.quantity[0] = quantity;
|
||||
c.presence[1] = client::FieldPresence::missing;
|
||||
c.presence[7] = client::FieldPresence::present;
|
||||
c.quantity[7] = 0xFFFF'FFFF'FFFF'0000ULL;
|
||||
c.moisture_status = world::MoistureStatus::available;
|
||||
c.moisture = {3, 50};
|
||||
return c;
|
||||
}
|
||||
client::OrganismCell organism(std::uint64_t id, std::int64_t x, std::int64_t y) {
|
||||
using biology::Capability;
|
||||
const auto genome = biology::Genome::create({7,
|
||||
1,
|
||||
1,
|
||||
{},
|
||||
{{Capability::energy_conversion, 400, 0},
|
||||
{Capability::membrane, 10, 0},
|
||||
{Capability::movement, 50, 0},
|
||||
{Capability::target_size, 8'000'000, 0}}});
|
||||
CHECK(genome);
|
||||
const biology::EnvironmentState temperate{
|
||||
293'150, {{1'000'000'000}, {accounting::Femtograms{1'000'000'000}, {}, {}, {}}}};
|
||||
auto c = client::present_organism(id, {x, y, slice}, {100}, {200}, *genome, {500, 0}, temperate,
|
||||
client::OrganismState::alive);
|
||||
CHECK(c);
|
||||
return *c;
|
||||
}
|
||||
// A 21 x 21 slice centred on the origin, plus organisms.
|
||||
struct World {
|
||||
std::map<std::pair<std::int64_t, std::int64_t>, std::uint64_t> quantity;
|
||||
std::vector<client::OrganismCell> organisms;
|
||||
std::uint64_t revision{1};
|
||||
World() {
|
||||
for (std::int64_t x = -10; x <= 10; ++x)
|
||||
for (std::int64_t y = -10; y <= 10; ++y)
|
||||
quantity[{x, y}] = 30;
|
||||
}
|
||||
ReplicationSource source() const {
|
||||
ReplicationSource s;
|
||||
s.identity = identity;
|
||||
s.field_revision = revision;
|
||||
s.organism_revision = revision;
|
||||
s.mask = mask;
|
||||
for (const auto& [xy, q] : quantity)
|
||||
s.environment.push_back(cell(xy.first, xy.second, q));
|
||||
s.organisms = organisms;
|
||||
return s;
|
||||
}
|
||||
};
|
||||
ReplicationLimits limits() {
|
||||
return ReplicationLimits{};
|
||||
}
|
||||
// Delivers chunks (optionally dropping some) and returns the acknowledgements.
|
||||
std::vector<SnapshotAck> deliver(SnapshotAssembler& client,
|
||||
const std::vector<SnapshotChunk>& chunks,
|
||||
const std::set<std::size_t>& drop = {}) {
|
||||
std::vector<SnapshotAck> acks;
|
||||
for (std::size_t i = 0; i < chunks.size(); ++i) {
|
||||
if (drop.contains(i))
|
||||
continue;
|
||||
// Every chunk crosses the real codec as one datagram.
|
||||
const auto bytes = encode_session(chunks[i]);
|
||||
CHECK(bytes.size() <= session_datagram_bytes);
|
||||
const auto decoded = decode_session(bytes);
|
||||
CHECK(decoded && std::get<SnapshotChunk>(*decoded) == chunks[i]);
|
||||
const auto accepted = client.accept(std::get<SnapshotChunk>(*decoded));
|
||||
CHECK(accepted);
|
||||
const auto complete = accepted.value_or(std::nullopt);
|
||||
if (complete)
|
||||
acks.push_back(*complete);
|
||||
}
|
||||
return acks;
|
||||
}
|
||||
std::size_t bytes_of(const std::vector<SnapshotChunk>& chunks) {
|
||||
std::size_t n = 0;
|
||||
for (const auto& c : chunks)
|
||||
n += encode_session(c).size();
|
||||
return n;
|
||||
}
|
||||
const std::vector<SnapshotChunk>&
|
||||
for_session(const std::vector<std::pair<std::uint64_t, std::vector<SnapshotChunk>>>& out,
|
||||
std::uint64_t session) {
|
||||
const auto it = std::ranges::find_if(out, [&](const auto& e) { return e.first == session; });
|
||||
CHECK(it != out.end());
|
||||
return it->second;
|
||||
}
|
||||
|
||||
void codec_v2() {
|
||||
const SessionInterest interest{-3, 4, -7, 7};
|
||||
const auto i = decode_session(encode_session(interest));
|
||||
CHECK(i && std::get<SessionInterest>(*i) == interest);
|
||||
const SnapshotAck ack{5, 9};
|
||||
CHECK(std::get<SnapshotAck>(*decode_session(encode_session(ack))) == ack);
|
||||
SnapshotChunk chunk{5, 9, 7, 3, 4, mask, -7, 1, 2, {1, 2, 3}};
|
||||
auto bytes = encode_session(chunk);
|
||||
CHECK(std::get<SnapshotChunk>(*decode_session(bytes)) == chunk);
|
||||
// Version 1 messages are no longer accepted.
|
||||
auto v1 = encode_session(ack);
|
||||
v1.at(4) = 1;
|
||||
CHECK(refused(decode_session(v1), SessionCodecError::unsupported_version));
|
||||
// Header rules: fresh baselines are 0 and always older; index < count <= 16; epoch, tick.
|
||||
for (const auto& bad : {SnapshotChunk{5, 9, 9, 3, 4, mask, -7, 0, 1, {}},
|
||||
SnapshotChunk{5, 9, 0, 3, 4, mask, -7, 1, 1, {}},
|
||||
SnapshotChunk{5, 9, 0, 3, 4, mask, -7, 0, 17, {}},
|
||||
SnapshotChunk{5, 9, 0, 3, 4, mask, -7, 0, 0, {}},
|
||||
SnapshotChunk{0, 9, 0, 3, 4, mask, -7, 0, 1, {}},
|
||||
SnapshotChunk{5, 0, 0, 3, 4, mask, -7, 0, 1, {}}})
|
||||
CHECK(refused(decode_session(encode_session(bad)), SessionCodecError::invalid_value));
|
||||
chunk.records.assign(max_snapshot_records_bytes, 0);
|
||||
CHECK(encode_session(chunk).size() == session_datagram_bytes &&
|
||||
decode_session(encode_session(chunk)));
|
||||
chunk.records.push_back(0); // One byte more than a datagram.
|
||||
CHECK(refused(decode_session(encode_session(chunk)), SessionCodecError::wrong_length));
|
||||
const auto empty = encode_session(SnapshotChunk{5, 9, 0, 3, 4, mask, -7, 0, 1, {}});
|
||||
for (std::size_t n = 0; n < empty.size(); ++n) // Every truncation of the header.
|
||||
CHECK(!decode_session(std::span{empty}.first(n)));
|
||||
}
|
||||
|
||||
void convergence_and_deltas() {
|
||||
auto server = *ReplicationServer::create(limits());
|
||||
World world;
|
||||
CHECK(server.open(1, 5));
|
||||
const auto clamped = server.set_interest(1, {0, 0, slice, 30});
|
||||
CHECK(clamped && clamped->radius == 7); // 15 x 15 = 225 cells at most.
|
||||
SnapshotAssembler client{identity, 5};
|
||||
const auto source = [&](const SessionInterest&) { return world.source(); };
|
||||
// A fresh 225-cell baseline exceeds 16 KiB: it arrives nearest first over a few ticks.
|
||||
std::uint64_t tick = 1;
|
||||
std::size_t first_size = 0;
|
||||
for (; tick <= 6; ++tick) {
|
||||
const auto out = server.tick(tick, source, {});
|
||||
const auto& chunks = for_session(out, 1);
|
||||
CHECK(bytes_of(chunks) <= 16384 && chunks.size() <= 16);
|
||||
CHECK(chunks.front().baseline == (tick == 1 ? 0 : tick - 1));
|
||||
for (const auto& a : deliver(client, chunks))
|
||||
server.acknowledge(1, a);
|
||||
if (tick == 1)
|
||||
first_size = client.latest()->environment.size();
|
||||
if (client.latest()->environment.size() == 225)
|
||||
break;
|
||||
}
|
||||
CHECK(first_size > 50 && first_size < 225 && tick <= 4);
|
||||
// Nearest first: the first snapshot holds the cells closest to the focus.
|
||||
// Leak assertion: nothing outside the interest square ever arrives.
|
||||
const auto env = client.environment();
|
||||
CHECK(env && env->cells().size() == 225);
|
||||
CHECK(std::ranges::all_of(env->cells(), [](const auto& c) {
|
||||
return c.voxel.x >= -7 && c.voxel.x <= 7 && c.voxel.y >= -7 && c.voxel.y <= 7;
|
||||
}));
|
||||
// Converged and unchanged: one empty chunk per tick keeps the cadence.
|
||||
++tick;
|
||||
auto out = server.tick(tick, source, {});
|
||||
CHECK(for_session(out, 1).size() == 1 && for_session(out, 1)[0].records.empty());
|
||||
for (const auto& a : deliver(client, for_session(out, 1)))
|
||||
server.acknowledge(1, a);
|
||||
const auto find = [&](std::int64_t x, std::int64_t y) {
|
||||
return std::ranges::find_if(client.latest()->environment, [&](const auto& c) {
|
||||
return c.voxel.x == x && c.voxel.y == y;
|
||||
});
|
||||
};
|
||||
const auto step = [&] {
|
||||
out = server.tick(++tick, source, {});
|
||||
for (const auto& a : deliver(client, for_session(out, 1)))
|
||||
server.acknowledge(1, a);
|
||||
};
|
||||
for (int i = 0; i < 4; ++i)
|
||||
step(); // Every cell was last sent at least 4 ticks ago.
|
||||
// Changes are sent when due: near every tick, far (radius > 3) every 4 ticks.
|
||||
world.quantity[{1, 1}] = 99;
|
||||
world.quantity[{6, 6}] = 77;
|
||||
step(); // Both were last sent long ago: both due.
|
||||
CHECK(find(1, 1)->quantity[0] == 99 && find(6, 6)->quantity[0] == 77);
|
||||
world.quantity[{1, 1}] = 100;
|
||||
world.quantity[{6, 6}] = 78;
|
||||
step(); // Near again at once; the far cell was updated a tick ago and waits.
|
||||
CHECK(for_session(out, 1)[0].records == encode_record(cell(1, 1, 100)));
|
||||
CHECK(find(1, 1)->quantity[0] == 100 && find(6, 6)->quantity[0] == 77);
|
||||
int waited = 1;
|
||||
while (find(6, 6)->quantity[0] != 78 && waited < 8) {
|
||||
step();
|
||||
++waited;
|
||||
}
|
||||
CHECK(find(6, 6)->quantity[0] == 78 && waited == 4);
|
||||
// Removal: a cell that disappears is removed from the client's view.
|
||||
world.quantity.erase(std::pair<std::int64_t, std::int64_t>{0, 0});
|
||||
++tick;
|
||||
for (const auto& a : deliver(client, for_session(server.tick(tick, source, {}), 1)))
|
||||
server.acknowledge(1, a);
|
||||
CHECK(find(0, 0) == client.latest()->environment.end() &&
|
||||
client.latest()->environment.size() == 224);
|
||||
// Loss: a dropped chunk leaves the snapshot incomplete (no ack); the next delta is
|
||||
// against the older acknowledged snapshot and the client still converges.
|
||||
for (std::int64_t x = -7; x <= 7; ++x)
|
||||
world.quantity[{x, 2}] = 500; // Enough changes for several chunks.
|
||||
++tick;
|
||||
out = server.tick(tick, source, {});
|
||||
CHECK(for_session(out, 1).size() > 1);
|
||||
CHECK(deliver(client, for_session(out, 1), {0}).empty());
|
||||
const auto acked_before = client.latest()->tick;
|
||||
++tick;
|
||||
out = server.tick(tick, source, {});
|
||||
CHECK(for_session(out, 1).front().baseline == acked_before);
|
||||
for (const auto& a : deliver(client, for_session(out, 1)))
|
||||
server.acknowledge(1, a);
|
||||
CHECK(client.latest()->tick == tick && find(3, 2)->quantity[0] == 500);
|
||||
// Without acks for more than 40 ticks the server falls back to a fresh baseline.
|
||||
const auto fresh_before = server.stats().fresh_baselines;
|
||||
for (int i = 0; i < 40; ++i) // The acknowledged baseline survives 40 ticks...
|
||||
CHECK(for_session(server.tick(++tick, source, {}), 1).front().baseline != 0);
|
||||
out = server.tick(++tick, source, {});
|
||||
CHECK(for_session(out, 1).front().baseline == 0 &&
|
||||
server.stats().fresh_baselines == fresh_before + 1);
|
||||
// Baselines are bounded: an ack for an evicted snapshot is ignored (still fresh).
|
||||
server.acknowledge(1, {5, tick - 30});
|
||||
out = server.tick(++tick, source, {});
|
||||
CHECK(for_session(out, 1).front().baseline == 0);
|
||||
server.acknowledge(1, {4, tick}); // Another epoch: ignored.
|
||||
out = server.tick(++tick, source, {});
|
||||
CHECK(for_session(out, 1).front().baseline == 0);
|
||||
// A new interest starts from a fresh baseline; the client's view follows it.
|
||||
server.acknowledge(1, {5, tick});
|
||||
CHECK(server.set_interest(1, {5, 5, slice, 2}));
|
||||
out = server.tick(++tick, source, {});
|
||||
CHECK(for_session(out, 1).front().baseline == 0);
|
||||
SnapshotAssembler moved{identity, 5};
|
||||
for (const auto& a : deliver(moved, for_session(out, 1)))
|
||||
server.acknowledge(1, a);
|
||||
const auto small = moved.environment();
|
||||
CHECK(small && small->cells().size() == 25 &&
|
||||
std::ranges::all_of(small->cells(), [](const auto& c) {
|
||||
return c.voxel.x >= 3 && c.voxel.x <= 7 && c.voxel.y >= 3 && c.voxel.y <= 7;
|
||||
}));
|
||||
}
|
||||
|
||||
void concealment() {
|
||||
auto server = *ReplicationServer::create(limits());
|
||||
World world;
|
||||
world.organisms = {organism(1, 0, 0), organism(2, 1, 1), organism(3, 9, 9)};
|
||||
CHECK(server.open(1, 5) && server.open(2, 5));
|
||||
CHECK(server.set_interest(1, {0, 0, slice, 3}) && server.set_interest(2, {0, 0, slice, 3}));
|
||||
// Session 1 cannot perceive organism 2 (e.g. concealed); session 2 can.
|
||||
const Perceives perceives = [](std::uint64_t session, const client::OrganismCell& o) {
|
||||
return !(session == 1 && o.id == 2);
|
||||
};
|
||||
const auto out =
|
||||
server.tick(1, [&](const SessionInterest&) { return world.source(); }, perceives);
|
||||
std::vector<std::uint8_t> one, two;
|
||||
for (const auto& c : for_session(out, 1))
|
||||
one.insert(one.end(), c.records.begin(), c.records.end());
|
||||
for (const auto& c : for_session(out, 2))
|
||||
two.insert(two.end(), c.records.begin(), c.records.end());
|
||||
const auto contains = [](const std::vector<std::uint8_t>& hay,
|
||||
const std::vector<std::uint8_t>& needle) {
|
||||
return std::search(hay.begin(), hay.end(), needle.begin(), needle.end()) != hay.end();
|
||||
};
|
||||
// Leak assertions on the encoded bytes: concealed and out-of-interest organisms are absent.
|
||||
CHECK(contains(one, encode_record(world.organisms[0])) &&
|
||||
!contains(one, encode_record(world.organisms[1])));
|
||||
CHECK(contains(two, encode_record(world.organisms[1])));
|
||||
CHECK(!contains(one, encode_record(world.organisms[2])) &&
|
||||
!contains(two, encode_record(world.organisms[2])));
|
||||
SnapshotAssembler client{identity, 5};
|
||||
(void)deliver(client, for_session(out, 1));
|
||||
const auto seen = client.organisms();
|
||||
CHECK(seen && seen->cells().size() == 1 && seen->cells()[0].id == 1);
|
||||
}
|
||||
|
||||
void client_robustness() {
|
||||
SnapshotAssembler client{identity, 5};
|
||||
const auto record = encode_record(cell(0, 0));
|
||||
SnapshotChunk c{5, 3, 0, 1, 1, mask, slice, 0, 1, record};
|
||||
CHECK(client.accept(c) && client.latest() && client.latest()->tick == 3);
|
||||
// Stale and foreign-epoch chunks are ignored.
|
||||
c.tick = 2;
|
||||
CHECK(client.accept(c) && client.latest()->tick == 3);
|
||||
c.tick = 4;
|
||||
c.epoch = 6;
|
||||
CHECK(client.accept(c) && client.latest()->tick == 3);
|
||||
c.epoch = 5;
|
||||
// Malformed records: truncated, unknown kind, another slice, an invalid enumerator.
|
||||
auto truncated = c;
|
||||
truncated.records.pop_back();
|
||||
CHECK(refused(client.accept(truncated), AssemblyError::malformed));
|
||||
auto unknown = c;
|
||||
unknown.tick = 5;
|
||||
unknown.records = {9};
|
||||
CHECK(refused(client.accept(unknown), AssemblyError::malformed));
|
||||
auto other = c;
|
||||
other.tick = 6;
|
||||
other.records = encode_record([] {
|
||||
auto x = cell(0, 0);
|
||||
x.voxel.z = slice + 1;
|
||||
return x;
|
||||
}());
|
||||
CHECK(refused(client.accept(other), AssemblyError::malformed));
|
||||
// Parts of one snapshot must agree; a delta against an unknown baseline is dropped.
|
||||
SnapshotChunk part{5, 10, 0, 1, 1, mask, slice, 0, 2, record};
|
||||
CHECK(client.accept(part));
|
||||
auto disagree = part;
|
||||
disagree.index = 1;
|
||||
disagree.mask = 1;
|
||||
CHECK(refused(client.accept(disagree), AssemblyError::malformed));
|
||||
SnapshotChunk orphan{5, 11, 7, 1, 1, mask, slice, 0, 1, {}};
|
||||
CHECK(client.accept(orphan) && client.latest()->tick == 3);
|
||||
// At most four snapshots in assembly.
|
||||
for (std::uint64_t t = 20; t < 30; ++t)
|
||||
CHECK(client.accept(SnapshotChunk{5, t, 0, 1, 1, mask, slice, 0, 2, record}));
|
||||
CHECK(client.partial() <= 4);
|
||||
}
|
||||
|
||||
// Dense interest: 32 sessions with different foci over a 41 x 41 slice; every snapshot within
|
||||
// the per-tick budget; a bandwidth and memory report for the record.
|
||||
void dense_report() {
|
||||
auto server = *ReplicationServer::create(limits());
|
||||
World world;
|
||||
world.quantity.clear();
|
||||
for (std::int64_t x = -20; x <= 20; ++x)
|
||||
for (std::int64_t y = -20; y <= 20; ++y)
|
||||
world.quantity[{x, y}] = 30;
|
||||
std::vector<SnapshotAssembler> clients;
|
||||
for (std::uint64_t s = 1; s <= 32; ++s) {
|
||||
CHECK(server.open(s, 5));
|
||||
// Centres within +-13, so every 15 x 15 interest lies inside the 41 x 41 slice.
|
||||
CHECK(server.set_interest(s, {static_cast<std::int64_t>(s % 8) * 3 - 10,
|
||||
static_cast<std::int64_t>(s / 8) * 5 - 10, slice, 7}));
|
||||
clients.emplace_back(identity, 5);
|
||||
}
|
||||
CHECK(refused(server.open(33, 5), ReplicationError::full));
|
||||
std::size_t max_bytes = 0, total = 0;
|
||||
for (std::uint64_t tick = 1; tick <= 40; ++tick) {
|
||||
for (std::int64_t x = -20; x <= 20; ++x) // Every tick, a changing row.
|
||||
world.quantity[{x, static_cast<std::int64_t>(tick % 41) - 20}] = 100 + tick;
|
||||
const auto out =
|
||||
server.tick(tick, [&](const SessionInterest&) { return world.source(); }, {});
|
||||
CHECK(out.size() == 32);
|
||||
for (const auto& [session, chunks] : out) {
|
||||
const auto n = bytes_of(chunks);
|
||||
max_bytes = std::max(max_bytes, n);
|
||||
total += n;
|
||||
for (const auto& a : deliver(clients[session - 1], chunks))
|
||||
server.acknowledge(session, a);
|
||||
}
|
||||
}
|
||||
CHECK(max_bytes <= 16384);
|
||||
CHECK(std::ranges::all_of(clients, [](const auto& c) {
|
||||
return c.latest() && c.latest()->environment.size() == 225;
|
||||
}));
|
||||
const auto stats = server.stats();
|
||||
CHECK(stats.retained_entities <= std::size_t{32} * 4 * 225);
|
||||
std::printf(
|
||||
"replication_report sessions=32 ticks=40 max_bytes_per_tick=%zu mean_bytes_per_tick=%zu "
|
||||
"chunks=%llu records=%llu deferred=%llu retained_entities=%zu\n",
|
||||
max_bytes, total / (std::size_t{32} * 40), static_cast<unsigned long long>(stats.chunks),
|
||||
static_cast<unsigned long long>(stats.records),
|
||||
static_cast<unsigned long long>(stats.deferred), stats.retained_entities);
|
||||
}
|
||||
} // namespace
|
||||
|
||||
void replication_tests() {
|
||||
codec_v2();
|
||||
convergence_and_deltas();
|
||||
concealment();
|
||||
client_robustness();
|
||||
dense_report();
|
||||
}
|
||||
} // namespace evo::network_test
|
||||
@@ -27,5 +27,6 @@ void protocol_tests();
|
||||
void tls_tests();
|
||||
void session_tests();
|
||||
void control_tests();
|
||||
void replication_tests();
|
||||
} // namespace evo::network_test
|
||||
#define CHECK(...) ::evo::network_test::check(static_cast<bool>(__VA_ARGS__))
|
||||
|
||||
@@ -301,7 +301,7 @@ void login_rules(const Files& f) {
|
||||
CHECK(raw_peer(h, std::nullopt) == Reason::timeout);
|
||||
CHECK(raw_peer(h, std::vector<std::uint8_t>{1, 2, 3}) == Reason::protocol);
|
||||
auto future = encode_session(SessionHello{0, h.issuer.grant(carol, 2, start + 60)});
|
||||
future.at(4) = 2;
|
||||
future.at(4) = 3;
|
||||
CHECK(raw_peer(h, future) == Reason::unsupported_version);
|
||||
CHECK(raw_peer(h, encode_session(SessionClose{Reason::client_closed})) == Reason::protocol);
|
||||
CHECK(raw_peer(h, encode_session(SessionHello{1, h.issuer.grant(carol, 3, start + 60)})) ==
|
||||
|
||||
Reference in New Issue
Block a user