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>
152 lines
7.1 KiB
C++
152 lines
7.1 KiB
C++
#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
|