Add M10.8b signed handoff tickets and ticket admission
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

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>
This commit is contained in:
dingo
2026-10-06 18:32:14 -04:00
co-authored by Claude Opus 5.5
parent 6a645ef7e4
commit 0ce51077b1
18 changed files with 1039 additions and 19 deletions
@@ -0,0 +1,70 @@
#include "evo/server/postgres_handoff_ledger.hpp"
#include "evo/persistence/account_control_store.hpp"
#include <string_view>
namespace evo::server {
namespace {
using network::HandoffLedgerError;
using persistence::ProbeStoreError;
// The region lease itself fenced (EVL02/EVL06) versus this transfer not being ours (EVL13).
bool lease_fenced(const persistence::PgFailure& f) {
const std::string_view state(f.sqlstate.data(), 5);
return state == "EVL02" || state == "EVL06";
}
HandoffLedgerError ledger_error(const persistence::ProbeStoreFailure& f) {
switch (f.kind) {
case ProbeStoreError::fenced:
return lease_fenced(f.cause) ? HandoffLedgerError::fenced : HandoffLedgerError::refused;
case ProbeStoreError::unknown_transfer:
case ProbeStoreError::not_staged:
case ProbeStoreError::invalid:
case ProbeStoreError::exhausted:
return HandoffLedgerError::refused;
default:
return HandoffLedgerError::unavailable;
}
}
} // namespace
std::expected<network::ControlLease, HandoffLedgerError>
PostgresHandoffLedger::admit(const network::TicketClaims& ticket, std::uint64_t session) {
const auto lease = lease_();
if (!lease)
return std::unexpected(HandoffLedgerError::fenced);
auto* db = db_->get();
if (!db)
return std::unexpected(HandoffLedgerError::unavailable);
const auto fail = [&](const persistence::ProbeStoreFailure& f) {
if (f.kind == ProbeStoreError::store || f.kind == ProbeStoreError::unknown)
db_->broken(); // Unknown connection state: reconnect next time.
return std::unexpected(ledger_error(f));
};
const auto staged =
persistence::stage_probe_transfer(*db, key_, *lease, ticket.transfer, timeout_);
if (!staged)
return fail(staged.error());
if (staged->account != ticket.account.bytes || staged->source != ticket.source ||
staged->destination != key_.region || staged->state == persistence::TransferState::aborted)
return std::unexpected(HandoffLedgerError::refused);
const auto committed =
persistence::commit_probe_transfer(*db, key_, *lease, ticket.transfer, timeout_);
if (!committed)
return fail(committed.error());
if (committed->state != persistence::TransferState::committed)
return std::unexpected(HandoffLedgerError::refused); // Aborted meanwhile.
const auto control = persistence::handoff_account_control(
*db, key_, *lease, ticket.account.bytes, ticket.transfer, session, duration_, timeout_);
if (!control) {
const auto kind = control.error().kind;
if (kind == persistence::ControlStoreError::store ||
kind == persistence::ControlStoreError::unknown) {
db_->broken();
return std::unexpected(HandoffLedgerError::unavailable);
}
return std::unexpected(lease_fenced(control.error().cause) ? HandoffLedgerError::fenced
: HandoffLedgerError::refused);
}
return network::ControlLease{control->generation, control->wait, control->granted};
}
} // namespace evo::server
+81 -11
View File
@@ -38,6 +38,27 @@ SessionCloseReason reason_for(network::ControlLedgerError e) {
return SessionCloseReason::capacity; // Not decided: the client may retry later.
}
}
SessionCloseReason reason_for(network::HandoffTicketError e) {
switch (e) {
case network::HandoffTicketError::wrong_environment:
case network::HandoffTicketError::wrong_scope:
return SessionCloseReason::wrong_scope;
case network::HandoffTicketError::expired:
return SessionCloseReason::expired;
default:
return SessionCloseReason::unauthenticated;
}
}
SessionCloseReason reason_for(network::HandoffLedgerError e) {
switch (e) {
case network::HandoffLedgerError::refused:
return SessionCloseReason::unauthenticated;
case network::HandoffLedgerError::fenced:
return SessionCloseReason::shutdown;
default:
return SessionCloseReason::capacity;
}
}
SessionCloseReason reason_for(SessionGrantError e) {
return e == SessionGrantError::wrong_environment ? SessionCloseReason::wrong_scope
: SessionCloseReason::unauthenticated;
@@ -62,15 +83,16 @@ struct RegionSessions::Impl {
};
Impl(RegionSessionsConfig c, std::unique_ptr<network::quic::Endpoint> e,
network::GrantVerifier v, network::SessionControl s, network::IntentAdmission i,
network::ReplicationServer r)
network::GrantVerifier v, std::optional<network::HandoffVerifier> h,
network::SessionControl s, network::IntentAdmission i, network::ReplicationServer r)
: config{std::move(c)}, endpoint{std::move(e)}, verifier{std::move(v)},
control{std::move(s)}, intents{std::move(i)}, replication{std::move(r)},
markers{config.control.max_sessions} {}
tickets{std::move(h)}, control{std::move(s)}, intents{std::move(i)},
replication{std::move(r)}, markers{config.control.max_sessions} {}
RegionSessionsConfig config;
std::unique_ptr<network::quic::Endpoint> endpoint;
network::GrantVerifier verifier;
std::optional<network::HandoffVerifier> tickets; // Handoff keys configured.
network::SessionControl control;
network::IntentAdmission intents;
network::ReplicationServer replication;
@@ -137,6 +159,8 @@ struct RegionSessions::Impl {
return close(c, SessionCloseReason::protocol, now);
if (!control.attempt(now_seconds)) // Region-wide, before signature work.
return close(c, SessionCloseReason::rate_limited, now);
if (network::looks_like_handoff_ticket(m.grant))
return ticket_hello(c, m, now_seconds, now);
const auto grant = verifier.verify(m.grant);
if (!grant)
return close(c, reason_for(grant.error()), now);
@@ -154,12 +178,47 @@ struct RegionSessions::Impl {
return close(c, reason_for(claimed.error()), now);
lease = *claimed;
}
const auto opened = control.open(*grant, now_seconds);
admitted(c, control.open(*grant, now_seconds), lease, promised, claims.account, now_seconds,
now);
}
// M10.8b: a Hello carrying a handoff ticket (ADR-0096). Verified, checked locally, then
// made durable (stage, commit, control) before the local admission.
void ticket_hello(Connection& c, const network::SessionHello& m, std::uint64_t now_seconds,
Clock::time_point now) {
if (!tickets)
return close(c, SessionCloseReason::unauthenticated, now);
const auto ticket = tickets->verify(m.grant, now_seconds);
if (!ticket)
return close(c, reason_for(ticket.error()), now);
const auto& claims = ticket->claims();
c.account = network::log_label(claims.account);
if (const auto checked = control.check_handoff(*ticket, now_seconds); !checked)
return close(c, reason_for(checked.error()), now);
std::optional<network::ControlLease> lease;
const auto promised = control.next_session();
if (config.handoff) {
auto moved = config.handoff->admit(claims, promised);
if (!moved)
return close(c, reason_for(moved.error()), now);
lease = *moved;
} else if (config.ledger) {
return close(c, SessionCloseReason::capacity, now); // Misconfigured: fail closed.
}
admitted(c, control.open_handoff(*ticket, now_seconds), lease, promised, claims.account,
now_seconds, now);
}
// Common to grants and tickets: the local admission's result after any durable claim.
void admitted(Connection& c, const std::expected<network::OpenedSession, ControlError>& opened,
const std::optional<network::ControlLease>& lease, std::uint64_t promised,
const network::AccountId& account, std::uint64_t now_seconds,
Clock::time_point now) {
if (!opened || opened->session != promised) {
if (opened)
(void)control.close(opened->session).has_value();
if (lease)
config.ledger->release(claims.account, lease->generation);
config.ledger->release(account, lease->generation);
return close(c, opened ? SessionCloseReason::capacity : reason_for(opened.error()),
now);
}
@@ -167,7 +226,7 @@ struct RegionSessions::Impl {
if (auto* old = by_session(opened->superseded))
close(*old, SessionCloseReason::superseded, now);
c.session = opened->session;
c.account_id = claims.account;
c.account_id = account;
c.welcome.session = opened->session;
c.welcome.epoch = opened->epoch;
c.welcome.world = config.control.world.world;
@@ -334,7 +393,7 @@ RegionSessions::~RegionSessions() = default;
std::expected<std::unique_ptr<RegionSessions>, RegionSessionsError>
RegionSessions::create(RegionSessionsConfig config) {
// Connections beyond sessions are headroom for logins and closes still flushing.
if (config.issuer_keys.empty() ||
if (config.issuer_keys.empty() || (config.handoff != nullptr && config.ledger == nullptr) ||
config.transport.limits.max_connections < config.control.max_sessions ||
config.hello_deadline.count() <= 0 || config.close_flush.count() <= 0 ||
config.renew_interval.count() <= 0 || config.safety_margin.count() <= 0)
@@ -348,6 +407,17 @@ RegionSessions::create(RegionSessionsConfig config) {
for (const auto& k : config.issuer_keys)
if (!verifier->add_key(k.key_id, k.public_key))
return std::unexpected(RegionSessionsError::keys);
std::optional<network::HandoffVerifier> tickets;
if (!config.handoff_keys.empty()) {
auto made = network::HandoffVerifier::create(config.control.environment,
config.control.world, config.control.region);
if (!made)
return std::unexpected(RegionSessionsError::keys);
for (const auto& k : config.handoff_keys)
if (!made->add_key(k.source_region, k.key_id, k.public_key))
return std::unexpected(RegionSessionsError::keys);
tickets.emplace(std::move(*made));
}
config.intents.max_sessions = config.control.max_sessions;
auto intents = network::IntentAdmission::create(config.intents);
if (!intents)
@@ -360,9 +430,9 @@ RegionSessions::create(RegionSessionsConfig config) {
auto endpoint = network::quic::Endpoint::serve(config.transport);
if (!endpoint)
return std::unexpected(RegionSessionsError::transport);
return std::unique_ptr<RegionSessions>{new RegionSessions{
std::make_unique<Impl>(std::move(config), std::move(*endpoint), std::move(*verifier),
std::move(*control), std::move(*intents), std::move(*replication))}};
return std::unique_ptr<RegionSessions>{new RegionSessions{std::make_unique<Impl>(
std::move(config), std::move(*endpoint), std::move(*verifier), std::move(tickets),
std::move(*control), std::move(*intents), std::move(*replication))}};
}
void RegionSessions::poll(const HostFacts& facts, std::uint64_t now_seconds,