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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user