Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m52s
Foundation / checks (client) (push) Failing after 4m25s
Foundation / checks (network) (push) Failing after 3m2s
Foundation / checks (tsan) (push) Failing after 33s
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 5m47s
Foundation / checks (postgres) (push) Canceled after 1m24s
228 lines
12 KiB
C++
228 lines
12 KiB
C++
#pragma once
|
|
#include "evo/network/session_control.hpp"
|
|
#include "evo/network/session_protocol.hpp"
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
#include <deque>
|
|
#include <expected>
|
|
#include <optional>
|
|
#include <span>
|
|
#include <utility>
|
|
#include <vector>
|
|
|
|
// M10.4 admission of realtime intentions and discrete actions for one region (ADR-0092).
|
|
// Transport-neutral and single-owner; the host serializes calls. Three distinct answers:
|
|
// - receipt: admitted (scheduled for a tick) or a refusal, never more than that;
|
|
// - simulated: the cumulative watermark of admitted intentions whose tick has run;
|
|
// - final (actions only): committed_no_effect with its commit, or not_committed.
|
|
// Intentions are per session (sequence strictly increasing, superseded by later ones).
|
|
// Actions are per account, with client-chosen ids that are never admitted twice, so a
|
|
// retry or a reconnect resolves to the same outcome. Neither changes biology in M10.4.
|
|
namespace evo::network {
|
|
struct IntentLimits {
|
|
std::uint32_t intent_window{8}; // Ticks ahead of the server tick (ADR-0089).
|
|
std::uint32_t window_ticks{8}; // Rate window.
|
|
std::uint32_t max_intents_per_window{8}; // Every attempt counts.
|
|
std::uint32_t max_actions_per_window{4}; // Every attempt counts.
|
|
std::size_t max_unresolved{256}; // Intentions plus actions per session.
|
|
std::size_t max_sessions{32};
|
|
std::size_t max_finals{2048}; // Recent final outcomes kept for duplicates and queries.
|
|
// Ticks between watermarks to each session (1: every simulated tick). The watermark is
|
|
// also every client's clock for the server tick until snapshots carry it (10.5).
|
|
std::uint64_t watermark_every{1};
|
|
// M10.9d (ADR-0097): while a session's watermark advances, at most one per this many
|
|
// ticks (it is cumulative: nothing is lost, "simulated" is learned up to N-1 ticks later).
|
|
// 1 keeps one per advance. Datagram sends dominate the session layer under load.
|
|
std::uint64_t watermark_coalesce{1};
|
|
};
|
|
// The host's authority as admission must see it.
|
|
struct AdmissionFacts {
|
|
bool ready{};
|
|
std::uint64_t epoch{}, server_tick{};
|
|
};
|
|
// An action the host must record durably with the batch that covers its tick.
|
|
struct CarriedAction {
|
|
AccountId account;
|
|
std::uint64_t action_id{}, tick{};
|
|
ActionKind kind{};
|
|
std::optional<std::array<std::uint8_t, cellular_action_input_bytes>> cellular_input;
|
|
friend bool operator==(const CarriedAction&, const CarriedAction&) = default;
|
|
};
|
|
struct AccountOutcome {
|
|
AccountId account;
|
|
ActionOutcome outcome;
|
|
ActionKind kind{ActionKind::probe};
|
|
std::optional<std::array<std::uint8_t, cellular_action_input_bytes>> cellular_input;
|
|
};
|
|
struct ScheduledCellularIntention {
|
|
AccountId account;
|
|
CellularIntention intention;
|
|
friend bool operator==(const ScheduledCellularIntention&,
|
|
const ScheduledCellularIntention&) = default;
|
|
};
|
|
enum class IntentConfigError : std::uint8_t { invalid };
|
|
// Durable action records (10.4b): the region host implements it over its lease (schema v11);
|
|
// tests use fakes. `find` answers with the committed outcome, nothing when the action was
|
|
// never committed, or `unavailable` when it cannot decide. `find_all` answers several in
|
|
// order, all or nothing (M10.9d, ADR-0097: one store round trip instead of one per action);
|
|
// the default asks `find` for each.
|
|
enum class ActionLedgerError : std::uint8_t { unavailable };
|
|
struct ActionKey {
|
|
AccountId account;
|
|
std::uint64_t action_id{};
|
|
};
|
|
struct DurableActionRecord {
|
|
ActionOutcome outcome;
|
|
// Present only for cellular actions. This is the canonical 24-byte biological
|
|
// input, independent of the session and epoch used to deliver a retry.
|
|
std::optional<std::array<std::uint8_t, cellular_action_input_bytes>> cellular_input;
|
|
friend bool operator==(const DurableActionRecord&, const DurableActionRecord&) = default;
|
|
};
|
|
class ActionLedger {
|
|
public:
|
|
ActionLedger() = default;
|
|
ActionLedger(const ActionLedger&) = delete;
|
|
ActionLedger& operator=(const ActionLedger&) = delete;
|
|
virtual ~ActionLedger() = default;
|
|
[[nodiscard]] virtual std::expected<std::optional<ActionOutcome>, ActionLedgerError>
|
|
find(const AccountId& account, std::uint64_t action_id) = 0;
|
|
[[nodiscard]] virtual std::expected<std::vector<std::optional<ActionOutcome>>,
|
|
ActionLedgerError>
|
|
find_all(std::span<const ActionKey> keys);
|
|
// Input-aware queries are used by v7 cellular actions. The compatibility
|
|
// default preserves legacy ledgers; absence of cellular_input cannot prove
|
|
// an exact cellular retry and must be treated as an identity conflict.
|
|
[[nodiscard]] virtual std::expected<std::optional<DurableActionRecord>, ActionLedgerError>
|
|
find_record(const AccountId& account, std::uint64_t action_id);
|
|
[[nodiscard]] virtual std::expected<std::vector<std::optional<DurableActionRecord>>,
|
|
ActionLedgerError>
|
|
find_all_records(std::span<const ActionKey> keys);
|
|
|
|
protected:
|
|
ActionLedger(ActionLedger&&) = default;
|
|
ActionLedger& operator=(ActionLedger&&) = default;
|
|
};
|
|
|
|
class IntentAdmission {
|
|
public:
|
|
[[nodiscard]] static std::expected<IntentAdmission, IntentConfigError>
|
|
create(IntentLimits limits);
|
|
// Durable lookups for duplicates and unresolved actions; null keeps memory only.
|
|
void attach(ActionLedger* ledger) noexcept {
|
|
ledger_ = ledger;
|
|
}
|
|
// Session lifecycle, driven by session control (after Welcome, on any close).
|
|
[[nodiscard]] bool open(std::uint64_t session, const AccountId& account);
|
|
void close(std::uint64_t session);
|
|
// `session` is the connection's authenticated session; a message naming another is
|
|
// refused. Every attempt by a known session counts toward its rate.
|
|
[[nodiscard]] IntentionReceipt intention(std::uint64_t session, const SessionIntention& m,
|
|
const AdmissionFacts& facts);
|
|
[[nodiscard]] IntentionReceipt intention(std::uint64_t session, const CellularIntention& m,
|
|
const AdmissionFacts& facts);
|
|
// Read-only pending inputs up to this tick, in deterministic tick/account/sequence order.
|
|
// They remain available until simulated() advances the committed/simulated watermark.
|
|
[[nodiscard]] std::vector<ScheduledCellularIntention>
|
|
scheduled_cellular_intentions(std::uint64_t tick) const;
|
|
[[nodiscard]] ActionReceipt action(std::uint64_t session, const SessionAction& m,
|
|
const AdmissionFacts& facts);
|
|
// v7 path retains canonical biological bytes through scheduling and refuses a reused
|
|
// account/action id whose input differs, including a final action still in memory.
|
|
[[nodiscard]] ActionReceipt action(std::uint64_t session, const CellularAction& m,
|
|
const AdmissionFacts& facts);
|
|
// The same admission with the durable uniqueness check deferred (M10.9d): nothing when the
|
|
// action awaits `verify`, which confirms every waiting action with one ledger request and
|
|
// returns their receipts by session. Without a ledger, `admit` always answers at once.
|
|
[[nodiscard]] std::optional<ActionReceipt> admit(std::uint64_t session, const SessionAction& m,
|
|
const AdmissionFacts& facts);
|
|
[[nodiscard]] std::optional<ActionReceipt> admit(std::uint64_t session, const CellularAction& m,
|
|
const AdmissionFacts& facts);
|
|
[[nodiscard]] std::vector<std::pair<std::uint64_t, ActionReceipt>>
|
|
verify(const AdmissionFacts& facts);
|
|
// An action of the session's account: final, pending or unknown. With a ledger, an action
|
|
// whose batch outcome was unknown is decided from its durable record once this authority
|
|
// is ready, and an action no longer in memory is looked up.
|
|
[[nodiscard]] ActionOutcome query(std::uint64_t session, const ActionQuery& m,
|
|
const AdmissionFacts& facts);
|
|
// Watermarks to send after the host simulated through facts.server_tick: to every
|
|
// session (sequence 0 before its first simulated intention) at least every
|
|
// `watermark_every` ticks, and when its sequence advances (at most every
|
|
// `watermark_coalesce` ticks).
|
|
[[nodiscard]] std::vector<std::pair<std::uint64_t, SimulatedThrough>>
|
|
simulated(const AdmissionFacts& facts);
|
|
// Scheduled actions whose tick is <= `tick`: they ride that tick's batch from now on.
|
|
[[nodiscard]] std::vector<CarriedAction> carry(std::uint64_t tick);
|
|
// These carried actions are durable in `commit_sequence`; `tick` is the tick each rode.
|
|
// With a ledger, each outcome is taken from the action's durable record (one request).
|
|
[[nodiscard]] std::vector<AccountOutcome> committed(std::span<const CarriedAction> actions,
|
|
std::uint64_t commit_sequence);
|
|
// The host dropped these carried actions. Final: never committed. Otherwise their batch's
|
|
// outcome was unknown: they stay pending until their durable record decides them.
|
|
[[nodiscard]] std::vector<AccountOutcome> dropped(std::span<const CarriedAction> actions,
|
|
bool final);
|
|
// Authority lost or epoch advanced: actions never carried are final (not_committed);
|
|
// carried ones stay pending until committed, dropped or decided by their record.
|
|
[[nodiscard]] std::vector<AccountOutcome> abandon();
|
|
// The current session of an account, for delivering outcomes.
|
|
[[nodiscard]] std::optional<std::uint64_t> session_of(const AccountId& account) const;
|
|
[[nodiscard]] std::size_t unresolved(std::uint64_t session) const;
|
|
|
|
private:
|
|
struct Pending {
|
|
std::uint64_t sequence{}, tick{}, epoch{};
|
|
std::int16_t move_x{}, move_y{};
|
|
bool has_intake_target{};
|
|
std::uint32_t intake_x_um{}, intake_y_um{};
|
|
};
|
|
struct Session {
|
|
std::uint64_t id{};
|
|
AccountId account;
|
|
std::uint64_t last_sequence{}, window_start{};
|
|
std::uint32_t intent_attempts{}, action_attempts{};
|
|
std::deque<Pending> pending;
|
|
std::uint64_t watermark{}, sent_watermark{}, sent_at_tick{};
|
|
};
|
|
// verifying: admitted in memory, awaiting the durable uniqueness check (`verify`).
|
|
enum class Stage : std::uint8_t { verifying, scheduled, carried };
|
|
struct Action {
|
|
CarriedAction carried;
|
|
Stage stage{};
|
|
bool unknown{}; // Carried in a batch whose outcome was unknown when authority was lost.
|
|
// While verifying: the admitting session, and the epoch and tick of its admission.
|
|
std::uint64_t session{}, epoch{}, admitted_at{};
|
|
};
|
|
explicit IntentAdmission(IntentLimits limits) : limits_{limits} {}
|
|
// A ledger answer flattened: unavailable (or no ledger), absent, or committed.
|
|
enum class Record : std::uint8_t { unavailable, absent, committed };
|
|
struct Found {
|
|
Record state{Record::unavailable};
|
|
ActionOutcome outcome;
|
|
std::optional<std::array<std::uint8_t, cellular_action_input_bytes>> cellular_input;
|
|
};
|
|
[[nodiscard]] Found lookup(const AccountId& account, std::uint64_t action_id) const;
|
|
// The in-memory checks of an action; `check` is set when only the ledger can still
|
|
// refuse it.
|
|
[[nodiscard]] ActionReceipt
|
|
screen(Session& s, const SessionAction& m, const AdmissionFacts& facts, bool& check,
|
|
std::optional<std::array<std::uint8_t, cellular_action_input_bytes>> cellular_input =
|
|
std::nullopt);
|
|
// Applies a durable answer to a receipt that passed `screen`.
|
|
void decide(const AccountId& account, ActionReceipt& r, const Found& found,
|
|
std::optional<std::array<std::uint8_t, cellular_action_input_bytes>>
|
|
cellular_input = std::nullopt);
|
|
Session* find(std::uint64_t session);
|
|
const Session* find(std::uint64_t session) const;
|
|
void count_window(Session& s, std::uint64_t server_tick) const;
|
|
[[nodiscard]] std::size_t unresolved_of(const Session& s) const;
|
|
void remember(const AccountId& account, const ActionOutcome& outcome,
|
|
ActionKind kind = ActionKind::probe,
|
|
std::optional<std::array<std::uint8_t, cellular_action_input_bytes>>
|
|
cellular_input = std::nullopt);
|
|
IntentLimits limits_;
|
|
std::vector<Session> sessions_;
|
|
std::vector<Action> actions_;
|
|
std::deque<AccountOutcome> finals_;
|
|
ActionLedger* ledger_{};
|
|
};
|
|
} // namespace evo::network
|