Files
aevolution/include/evo/network/session_control.hpp
T
dingoandClaude Opus 5.5 0ce51077b1
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m55s
Foundation / checks (client) (push) Successful in 12m40s
Foundation / checks (postgres) (push) Canceled after 4s
Foundation / checks (network) (push) Successful in 12m53s
Foundation / checks (tsan) (push) Successful in 7m55s
Foundation / checks (checks) (push) Successful in 31m47s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
Add M10.8b signed handoff tickets and ticket admission
ADR-0096. A source region's handoff key signs a 160-byte ticket for one probe
transfer, account and destination; it rides the Hello grant slot and is
verified against neighbour keys bound to their regions. SessionControl
admits a ticket once per region, superseding like a grant, with the session
ending at the client's original grant expiry. RegionSessions makes the
destination's durable step first: PostgresHandoffLedger stages and commits
the transfer and moves the account's control, idempotently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 18:32:14 -04:00

198 lines
9.5 KiB
C++

#pragma once
#include "evo/network/admission.hpp"
#include "evo/world/chunks.hpp"
#include <array>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <optional>
#include <string>
#include <vector>
// M10.3 account-bound session control for one region (ADR-0091). Transport-neutral and
// single-owner. It decides which session, if any, controls each account in this region
// and leaves intentions to 10.4. A grant authorizes opening (or refreshing) a session;
// per-account grant serials order grants so the newest wins: a grant is usable once and
// never after a newer one for the same account (replay and stolen stale grants fail).
// The M9 dev path (SessionAdmission, protocol v1) is unchanged.
namespace evo::network {
// Provider-independent account identity: 128 random bits assigned by the account
// directory, never derived from a provider id (Steam, dev test or otherwise).
struct AccountId {
std::array<std::uint8_t, 16> bytes{};
[[nodiscard]] bool valid() const noexcept;
auto operator<=>(const AccountId&) const = default;
};
// Short non-secret label for logs and events: the first 4 bytes in hex ("acct-1a2b3c4d").
// Grants, signatures and keys have no log form at all.
[[nodiscard]] std::string log_label(const AccountId& account);
// Claims of a production session grant (schemas/network/session-grant-v1.md).
struct GrantClaims {
std::uint64_t grant_id{};
AccountId account;
std::uint64_t serial{}; // Strictly increasing per account; issued by the directory.
world::WorldIdentity world;
std::uint64_t region{}, issued_at{}, expires_at{}; // Server clock, seconds.
};
class GrantVerifier;
class VerifiedHandoffTicket; // M10.8b, handoff_ticket.hpp.
// Only GrantVerifier::verify constructs this, after the signature and environment checked.
class VerifiedSessionGrant {
public:
[[nodiscard]] const GrantClaims& claims() const noexcept {
return claims_;
}
[[nodiscard]] DeploymentEnvironment environment() const noexcept {
return environment_;
}
private:
friend class GrantVerifier;
VerifiedSessionGrant(DeploymentEnvironment environment, const GrantClaims& claims)
: claims_{claims}, environment_{environment} {}
GrantClaims claims_;
DeploymentEnvironment environment_;
};
struct ControlConfig {
DeploymentEnvironment environment{DeploymentEnvironment::dev};
world::WorldIdentity world;
std::uint64_t region{}, epoch{};
std::size_t max_sessions{32};
std::size_t max_accounts{4096}; // Tracked accounts (sessions, serials, rates).
std::uint64_t max_grant_lifetime{300}; // Seconds; grants are short-lived.
std::uint64_t clock_skew{30}; // Seconds tolerated before issued_at.
// Every verified open or refresh by an account counts, accepted or not.
std::uint32_t max_account_attempts{4};
// Every attempt before signature verification counts, region-wide.
std::uint32_t max_region_attempts{64};
std::uint64_t attempt_window{60}; // Seconds, for both limits.
};
enum class ControlError : std::uint8_t {
invalid_config,
wrong_environment,
wrong_world,
wrong_region,
invalid_lifetime,
not_yet_valid,
expired,
stale_grant, // Serial not newer than one already presented for this account.
rate_limited,
sessions_full,
accounts_full, // Fail closed: never forget a serial early.
unknown_session,
wrong_account
};
struct OpenedSession {
std::uint64_t session{};
std::uint64_t superseded{}; // The account's previous session, now closed (0 if none).
std::uint64_t epoch{}, expires_at{};
};
class SessionControl {
public:
[[nodiscard]] static std::expected<SessionControl, ControlError> create(ControlConfig config);
// Region-wide attempt limit, checked before any signature work. Counts the attempt.
[[nodiscard]] std::expected<void, ControlError> attempt(std::uint64_t now_seconds);
// Whether open() would accept the grant now, without changing anything (no attempt is
// counted). Lets the host take durable control before admitting the session locally.
[[nodiscard]] std::expected<void, ControlError> check(const VerifiedSessionGrant& grant,
std::uint64_t now_seconds) const;
// The id the next successful open() assigns.
[[nodiscard]] std::uint64_t next_session() const noexcept {
return next_session_;
}
// A newer grant for an account that already holds a session takes control: the old
// session is closed first and reported as superseded. Control is never shared.
[[nodiscard]] std::expected<OpenedSession, ControlError> open(const VerifiedSessionGrant& grant,
std::uint64_t now_seconds);
// M10.8b (ADR-0096): a verified handoff ticket opens a session here, the destination,
// for its account. A ticket is single-use per region (its transfer is remembered until
// the ticket expires), counts as an attempt like a grant, supersedes like a grant, and
// the session ends at the ticket's session expiry, capped at the maximum grant lifetime
// from now: a crossing never extends a session. Serials are unchanged.
[[nodiscard]] std::expected<void, ControlError>
check_handoff(const VerifiedHandoffTicket& ticket, std::uint64_t now_seconds) const;
[[nodiscard]] std::expected<OpenedSession, ControlError>
open_handoff(const VerifiedHandoffTicket& ticket, std::uint64_t now_seconds);
// In-session renewal with a newer grant for the same account: extends the expiry
// without a reconnect or new baseline.
[[nodiscard]] std::expected<std::uint64_t, ControlError>
refresh(std::uint64_t session, const VerifiedSessionGrant& grant, std::uint64_t now_seconds);
[[nodiscard]] std::expected<void, ControlError> close(std::uint64_t session);
// Sessions whose grant expired at `now_seconds`; they are closed by this call.
[[nodiscard]] std::vector<std::uint64_t> expire(std::uint64_t now_seconds);
// New ownership epoch: every session closes (ADR-0089: none survives an epoch change).
[[nodiscard]] std::expected<std::vector<std::uint64_t>, ControlError>
advance_epoch(std::uint64_t epoch);
[[nodiscard]] std::optional<std::uint64_t> holder(const AccountId& account) const;
[[nodiscard]] std::optional<AccountId> account_of(std::uint64_t session) const;
[[nodiscard]] std::size_t sessions() const noexcept;
[[nodiscard]] std::uint64_t epoch() const noexcept {
return config_.epoch;
}
private:
struct Account {
AccountId id;
std::uint64_t serial{}; // Newest grant serial presented and accepted.
std::uint64_t remember_until{}; // Every grant up to `serial` has expired by then.
std::uint64_t session{}, session_expires_at{};
std::uint64_t window_start{};
std::uint32_t attempts{};
};
explicit SessionControl(ControlConfig config) : config_{config} {}
[[nodiscard]] std::optional<ControlError> claims_error(const VerifiedSessionGrant& grant,
std::uint64_t now_seconds) const;
[[nodiscard]] bool forgettable(const Account& account, std::uint64_t now_seconds) const;
[[nodiscard]] std::expected<Account*, ControlError> admit(const VerifiedSessionGrant& grant,
std::uint64_t now_seconds);
[[nodiscard]] std::optional<ControlError> ticket_error(const VerifiedHandoffTicket& ticket,
std::uint64_t now_seconds) const;
struct UsedTicket {
std::array<std::uint8_t, 16> transfer{};
std::uint64_t until{};
};
void accept(Account& account, const GrantClaims& claims);
void forget_idle(std::uint64_t now_seconds);
ControlConfig config_;
std::uint64_t next_session_{1};
std::uint64_t region_window_start_{};
std::uint32_t region_attempts_{};
std::vector<Account> accounts_;
std::vector<UsedTicket> used_tickets_; // At most max_accounts, pruned at expiry.
};
// Durable per-world account control (10.3c, schema v10). The region host implements it
// over its database lease; tests use fakes. Calls block for one statement each.
enum class ControlLedgerError : std::uint8_t {
stale_grant, // The world already accepted this or a newer serial for the account.
fenced, // This region's lease or this control generation is no longer current.
unavailable // Not decided (database unreachable, timeout, or an unknown outcome).
};
struct ControlLease {
std::uint64_t generation{};
// Another region still held control: do not act for the account before this passes.
std::chrono::milliseconds wait{};
std::chrono::milliseconds granted{}; // From the request send, after the wait.
};
class ControlLedger {
public:
ControlLedger() = default;
ControlLedger(const ControlLedger&) = delete;
ControlLedger& operator=(const ControlLedger&) = delete;
virtual ~ControlLedger() = default;
[[nodiscard]] virtual std::expected<ControlLease, ControlLedgerError>
claim(const AccountId& account, std::uint64_t serial, std::uint64_t session) = 0;
[[nodiscard]] virtual std::expected<std::chrono::milliseconds, ControlLedgerError>
renew(const AccountId& account, std::uint64_t generation) = 0;
virtual void release(const AccountId& account, std::uint64_t generation) = 0;
protected:
ControlLedger(ControlLedger&&) = default;
ControlLedger& operator=(ControlLedger&&) = default;
};
} // namespace evo::network