From 3277b8f3cd4bcc5434aa1c9d4a909b24d0185259 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 20:52:32 -0400 Subject: [PATCH] Add primitive life calls to the session client --- apps/evo-session-probe/main.cpp | 84 +++++++++++++++++++++++-- docs/engineering/M11_2_DELIVERY_PLAN.md | 8 ++- docs/engineering/VALIDATION.md | 14 +++++ include/evo/client/region_session.hpp | 7 +++ src/client/session/region_session.cpp | 55 ++++++++++++++-- src/server/session/region_sessions.cpp | 16 ++++- tests/quic_sessions.cpp | 65 ++++++++----------- 7 files changed, 193 insertions(+), 56 deletions(-) diff --git a/apps/evo-session-probe/main.cpp b/apps/evo-session-probe/main.cpp index 5fe8f81..1feb967 100644 --- a/apps/evo-session-probe/main.cpp +++ b/apps/evo-session-probe/main.cpp @@ -20,7 +20,8 @@ // endian). This is the load bundle `evo-load --grants FILE --grants-per-bot COUNT` uses. // evo-session-probe run --connect HOST:PORT --server-name NAME --ca FILE --issuer-key FILE // --world N --frame N --region N --account HEX32 --serial N [--lifetime S] -// [--intents N] [--actions N --action-base ID] [--query ID]... [--timeout-ms N] +// [--protocol v4|v5] [--intents N] [--actions N --action-base ID] [--query ID]... +// [--new-life ID]... [--life-query ID]... [--timeout-ms N] // [--interest X,Y,Z,R] [--snapshots N] // Signs a dev grant for the account and serial, logs in over QUIC, sends N intentions // (one per tick, two ticks ahead) and N probe actions (three ticks ahead), queries the @@ -35,8 +36,8 @@ // handoff REGION ENDPOINT | redirect REGION ENDPOINT (v4, ADR-0096; then closed) // closed REASON TRANSPORT (TRANSPORT names why QUIC ended: untrusted means the server // answered but failed the pinned CA/name check; idle means nothing answered) -// Statuses, results and reasons are the session-v1 wire values. Exits 0 once every -// action is final and every query answered, 1 on timeout, 3 when the server closes. +// Statuses/results follow the selected protocol version. Exits 0 once every requested +// operation is answered, 1 on timeout, 3 when the server closes. // evo-session-probe run --connect HOST:PORT --server-name NAME --ca FILE --grants FILE // [--grant N] [options as above] // M10.9 (ADR-0097): logs in with grant N (from 0) of an existing bundle instead of @@ -173,10 +174,12 @@ struct RunOptions { std::string host, server_name, ca, issuer_key, grants_file; std::uint64_t grant_index{}; std::uint16_t port{}; + std::uint16_t protocol_version{session_protocol_version}; std::uint64_t world{}, frame{}, region{}, serial{}, lifetime{60}, intents{}, actions{}, action_base{1}, timeout_ms{20000}; std::optional account; std::vector queries; + std::vector life_requests, life_queries; std::vector more_regions; // grants: further --region values. std::optional interest; std::uint64_t snapshots{}; @@ -316,6 +319,7 @@ int run(const RunOptions& o) { config.transport.authority_pem = read(o.ca); config.transport.authority_pem_file = o.ca; config.grant = *grant; + config.protocol_version = o.protocol_version; auto made = client::RegionSessionClient::connect(std::move(config), Clock::now()); if (!made) { std::puts("error connect"); @@ -324,9 +328,15 @@ int run(const RunOptions& o) { auto& c = **made; const auto deadline = Clock::now() + std::chrono::milliseconds{o.timeout_ms}; bool welcomed = false, queried = false; + auto life_retry_at = Clock::time_point{}; std::uint64_t sent_intents = 0, sent_actions = 0, last_tick = 0, simulated = 0; std::uint64_t seen_snapshot = 0, snapshots = 0; std::set pending_actions, pending_queries(o.queries.begin(), o.queries.end()); + std::set pending_life_requests(o.life_requests.begin(), o.life_requests.end()); + std::set pending_life_queries(o.life_queries.begin(), o.life_queries.end()); + const auto life_request_count = pending_life_requests.size(); + const auto life_query_count = pending_life_queries.size(); + std::set sent_life_requests, sent_life_queries; for (std::uint64_t i = 0; i < o.actions; ++i) pending_actions.insert(o.action_base + i); while (Clock::now() < deadline) { @@ -372,6 +382,22 @@ int run(const RunOptions& o) { for (const auto query : o.queries) (void)c.query_action(query); } + const auto life_now = Clock::now(); + if (life_now >= life_retry_at) { + bool sent_life = false; + for (const auto request : o.life_requests) + if (!sent_life_requests.contains(request) && c.request_primitive_life(request)) { + sent_life_requests.insert(request); + sent_life = true; + } + for (const auto query : o.life_queries) + if (!sent_life_queries.contains(query) && c.query_primitive_life(query)) { + sent_life_queries.insert(query); + sent_life = true; + } + if (sent_life) + life_retry_at = life_now + std::chrono::milliseconds{250}; + } for (const auto& r : c.take_intention_receipts()) std::printf("intention %llu %u\n", static_cast(r.sequence), static_cast(r.status)); @@ -416,10 +442,42 @@ int run(const RunOptions& o) { out.result == ActionResult::not_committed) pending_actions.erase(out.action_id); } + for (const auto& receipt : c.take_primitive_life_receipts()) + std::printf("life-receipt %llu %u %llu\n", + static_cast(receipt.request_id), + static_cast(receipt.status), + static_cast(receipt.server_tick)); + for (const auto& out : c.take_primitive_life_outcomes()) { + std::printf("life-outcome %llu %u %llu %llu\n", + static_cast(out.request_id), + static_cast(out.result), + static_cast(out.life_identity), + static_cast(out.commit_sequence)); + const bool unresolved = out.result == PrimitiveLifeResult::pending || + (out.result == PrimitiveLifeResult::unknown && + pending_life_requests.contains(out.request_id)); + if (pending_life_requests.contains(out.request_id)) { + if (unresolved) + sent_life_requests.erase(out.request_id); // Exact request retry is idempotent. + else + pending_life_requests.erase(out.request_id); + } + if (pending_life_queries.contains(out.request_id)) { + if (out.result == PrimitiveLifeResult::pending) + sent_life_queries.erase(out.request_id); + else + pending_life_queries.erase(out.request_id); // Unknown is a query answer. + } + if (unresolved) + life_retry_at = + std::max(life_retry_at, Clock::now() + std::chrono::milliseconds{250}); + } std::fflush(stdout); if (sent_actions == o.actions && pending_actions.empty() && pending_queries.empty() && - sent_intents == o.intents && simulated >= std::min(o.intents, 1) && - snapshots >= o.snapshots) { + pending_life_requests.empty() && pending_life_queries.empty() && + sent_life_requests.size() == life_request_count && + sent_life_queries.size() == life_query_count && sent_intents == o.intents && + simulated >= std::min(o.intents, 1) && snapshots >= o.snapshots) { std::printf("snapshot-bytes %llu chunks %llu\n", static_cast(c.snapshot_bytes()), static_cast(c.snapshot_chunks())); @@ -470,8 +528,16 @@ int main(int argc, char** argv) { o.grant_index = *n; else if (flag == "--account") ok = (o.account = account_of(value)).has_value(); + else if (flag == "--protocol" && value == "v4") + o.protocol_version = session_protocol_version; + else if (flag == "--protocol" && value == "v5") + o.protocol_version = session_protocol_v5; else if (flag == "--query" && n) o.queries.push_back(*n); + else if (flag == "--new-life" && n && *n != 0) + o.life_requests.push_back(*n); + else if (flag == "--life-query" && n && *n != 0) + o.life_queries.push_back(*n); else if (n && flag == "--world") o.world = *n; else if (n && flag == "--frame") @@ -525,5 +591,13 @@ int main(int argc, char** argv) { stderr); return 2; } + if ((o.protocol_version == session_protocol_v5 && + (o.intents != 0 || o.actions != 0 || !o.queries.empty() || o.interest || + o.snapshots != 0)) || + (o.protocol_version == session_protocol_version && + (!o.life_requests.empty() || !o.life_queries.empty()))) { + std::fputs("error incompatible session protocol options\n", stderr); + return 2; + } return run(o); } diff --git a/docs/engineering/M11_2_DELIVERY_PLAN.md b/docs/engineering/M11_2_DELIVERY_PLAN.md index e0fee59..05c1b2a 100644 --- a/docs/engineering/M11_2_DELIVERY_PLAN.md +++ b/docs/engineering/M11_2_DELIVERY_PLAN.md @@ -124,9 +124,11 @@ Local checks do not close ADR-0097's reference-worker qualification. requires durable account control and accepts v5 only, while other region listeners remain v4-only. Life requests are tied to the admitted session, current epoch and authenticated account-control generation, then call the - primitive host; query calls its read-only path. The QUIC contract test covers - v5 Hello, Welcome, durable-generation binding, receipt and outcome. Runtime - process/PostgreSQL qualification remains pending CI. + primitive host; query calls its read-only path. The session client and headless + probe have opt-in v5 request/query calls; v4 remains the default, and primitive + v5 refuses the M10 action/movement/interest path. QUIC contract tests cover v5 + Hello, Welcome, durable-generation binding, receipt, outcome and read-only query. + Runtime process/PostgreSQL qualification remains pending CI. - Cross-region owner routing and reconnect-to-existing-life are not complete. The accepted v5 outcome has no owner-region/address field, while the delivery row requires routing. The host can identify a different reservation owner but diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 91d660d..608a4af 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -5799,3 +5799,17 @@ full `evo-server` compilation and real PostgreSQL process results await CI. Cross-region routing remains incomplete because the accepted v5 outcome does not carry an owner region/address; see the delivery plan. No deployed world was provisioned or changed. + +## 2026-10-10 — M11.2d-6 client and probe callers (CI pending) + +`RegionSessionClientConfig` now selects v4 or v5 explicitly (v4 default). The client +encodes Hello and stream calls in its selected version, collects primitive-life +receipts/outcomes, and exposes create/query methods only for v5. M10 movement, action, +and interest methods are unavailable in v5. `evo-session-probe` accepts `--protocol v5`, +`--new-life ID` and `--life-query ID`, prints replies, retries unresolved exact requests, +and rejects combinations with M10 actions or movement options. The QUIC session test +now exercises these client APIs end to end with a durable-control fake. + +Targeted MSVC Release/NDEBUG compilation of the modified session client, QUIC test and +probe, manual relink of the test/probe, and `ctest --preset quic` passed (5/5). Formatting +and `git diff --check` passed. Full server/process/PostgreSQL qualification remains in CI. diff --git a/include/evo/client/region_session.hpp b/include/evo/client/region_session.hpp index 5d79617..737e7b3 100644 --- a/include/evo/client/region_session.hpp +++ b/include/evo/client/region_session.hpp @@ -23,6 +23,7 @@ namespace evo::client { struct RegionSessionClientConfig { network::quic::ClientConfig transport; network::WireGrant grant{}; + std::uint16_t protocol_version{network::session_protocol_version}; std::chrono::milliseconds welcome_deadline{5000}; // Connect to Welcome. }; enum class RegionSessionState : std::uint8_t { connecting, awaiting_welcome, established, closed }; @@ -53,6 +54,12 @@ class RegionSessionClient { [[nodiscard]] bool send_action(std::uint64_t action_id, network::ActionKind kind, std::uint64_t tick); [[nodiscard]] bool query_action(std::uint64_t action_id); + // Primitive profile v5 only. The account and generation are always supplied by the + // authenticated session; callers choose only a stable request id. + [[nodiscard]] bool request_primitive_life(std::uint64_t request_id); + [[nodiscard]] bool query_primitive_life(std::uint64_t request_id); + [[nodiscard]] std::vector take_primitive_life_receipts(); + [[nodiscard]] std::vector take_primitive_life_outcomes(); [[nodiscard]] std::vector take_intention_receipts(); [[nodiscard]] std::vector take_action_receipts(); [[nodiscard]] std::vector take_action_outcomes(); diff --git a/src/client/session/region_session.cpp b/src/client/session/region_session.cpp index a76d1e3..c990789 100644 --- a/src/client/session/region_session.cpp +++ b/src/client/session/region_session.cpp @@ -11,6 +11,7 @@ using Clock = std::chrono::steady_clock; struct RegionSessionClient::Impl { std::unique_ptr endpoint; network::WireGrant grant{}; + std::uint16_t protocol_version{network::session_protocol_version}; Clock::time_point deadline; RegionSessionState state{RegionSessionState::connecting}; network::quic::ConnectionId connection{}; @@ -23,6 +24,8 @@ struct RegionSessionClient::Impl { std::vector intention_receipts; std::vector action_receipts; std::vector action_outcomes; + std::vector primitive_life_receipts; + std::vector primitive_life_outcomes; std::optional snapshots; std::uint64_t snapshot_chunks{}, snapshot_bytes{}; std::optional handoff; // v4: continue at another region. @@ -76,7 +79,8 @@ struct RegionSessionClient::Impl { bool send(const network::SessionMessage& m) { return connection != 0 && - endpoint->send_message(connection, network::encode_session(m)).has_value(); + endpoint->send_message(connection, network::encode_session(m, protocol_version)) + .has_value(); } // Ends the session locally; `tell` sends a Close first (best effort). void end(SessionCloseReason why, bool tell) { @@ -91,9 +95,12 @@ struct RegionSessionClient::Impl { endpoint->close(connection); } void message(std::span bytes) { - const auto decoded = network::decode_session(bytes); + std::uint16_t wire_version{}; + const auto decoded = network::decode_session(bytes, &wire_version); if (!decoded) return end(SessionCloseReason::protocol, true); + if (wire_version != protocol_version) + return end(SessionCloseReason::unsupported_version, true); if (const auto* m = std::get_if(&*decoded)) return end(m->reason, false); if (state == RegionSessionState::awaiting_welcome) { @@ -121,6 +128,12 @@ struct RegionSessionClient::Impl { } if (const auto* m = std::get_if(&*decoded)) return keep(action_outcomes, *m); + if (const auto* m = std::get_if(&*decoded)) { + seen_tick(m->server_tick); + return keep(primitive_life_receipts, *m); + } + if (const auto* m = std::get_if(&*decoded)) + return keep(primitive_life_outcomes, *m); if (const auto* m = std::get_if(&*decoded)) { handoff = *m; // A Close (handed_off) follows. return; @@ -135,11 +148,15 @@ RegionSessionClient::~RegionSessionClient() = default; std::expected, network::quic::EndpointError> RegionSessionClient::connect(RegionSessionClientConfig config, Clock::time_point now) { + if (config.protocol_version != network::session_protocol_version && + config.protocol_version != network::session_protocol_v5) + return std::unexpected(network::quic::EndpointError::configuration); auto endpoint = network::quic::Endpoint::connect(config.transport); if (!endpoint) return std::unexpected(endpoint.error()); auto impl = std::make_unique(); impl->endpoint = std::move(*endpoint); + impl->protocol_version = config.protocol_version; impl->grant = config.grant; config.grant.fill(0); impl->deadline = now + config.welcome_deadline; @@ -192,7 +209,8 @@ void RegionSessionClient::close() { std::optional RegionSessionClient::send_intention(std::uint64_t tick, std::int16_t move_x, std::int16_t move_y) { auto& m = *impl_; - if (m.state != RegionSessionState::established || m.connection == 0 || !m.welcome) + if (m.protocol_version != network::session_protocol_version || + m.state != RegionSessionState::established || m.connection == 0 || !m.welcome) return std::nullopt; const network::SessionIntention intention{ m.welcome->session, m.welcome->epoch, m.next_sequence, tick, move_x, move_y}; @@ -204,14 +222,38 @@ RegionSessionClient::send_intention(std::uint64_t tick, std::int16_t move_x, std bool RegionSessionClient::send_action(std::uint64_t action_id, network::ActionKind kind, std::uint64_t tick) { auto& m = *impl_; - return m.state == RegionSessionState::established && m.welcome && + return m.protocol_version == network::session_protocol_version && + m.state == RegionSessionState::established && m.welcome && m.send(network::SessionAction{m.welcome->session, m.welcome->epoch, action_id, static_cast(kind), tick}); } bool RegionSessionClient::query_action(std::uint64_t action_id) { auto& m = *impl_; - return m.state == RegionSessionState::established && m.send(network::ActionQuery{action_id}); + return m.protocol_version == network::session_protocol_version && + m.state == RegionSessionState::established && m.send(network::ActionQuery{action_id}); +} + +bool RegionSessionClient::request_primitive_life(std::uint64_t request_id) { + auto& m = *impl_; + return m.protocol_version == network::session_protocol_v5 && + m.state == RegionSessionState::established && m.welcome && request_id != 0 && + m.send(network::PrimitiveLifeRequest{m.welcome->session, m.welcome->epoch, request_id}); +} + +bool RegionSessionClient::query_primitive_life(std::uint64_t request_id) { + auto& m = *impl_; + return m.protocol_version == network::session_protocol_v5 && + m.state == RegionSessionState::established && request_id != 0 && + m.send(network::PrimitiveLifeQuery{request_id}); +} + +std::vector RegionSessionClient::take_primitive_life_receipts() { + return std::exchange(impl_->primitive_life_receipts, {}); +} + +std::vector RegionSessionClient::take_primitive_life_outcomes() { + return std::exchange(impl_->primitive_life_outcomes, {}); } std::vector RegionSessionClient::take_intention_receipts() { @@ -236,7 +278,8 @@ std::uint64_t RegionSessionClient::server_tick() const noexcept { bool RegionSessionClient::set_interest(const network::SessionInterest& interest) { auto& m = *impl_; - return m.state == RegionSessionState::established && m.send(interest); + return m.protocol_version == network::session_protocol_version && + m.state == RegionSessionState::established && m.send(interest); } const network::ReplicatedView* RegionSessionClient::view() const noexcept { diff --git a/src/server/session/region_sessions.cpp b/src/server/session/region_sessions.cpp index 26087db..cf5be68 100644 --- a/src/server/session/region_sessions.cpp +++ b/src/server/session/region_sessions.cpp @@ -391,7 +391,8 @@ struct RegionSessions::Impl { std::uint16_t wire_version{}; const auto decoded = network::decode_session(bytes, &wire_version); if (c.state != State::established || !decoded || - wire_version != network::session_protocol_version) + wire_version != network::session_protocol_version || + c.protocol_version != network::session_protocol_version) return close(c, SessionCloseReason::protocol, now); if (const auto* ack = std::get_if(&*decoded)) return replication.acknowledge(c.session, *ack); @@ -556,14 +557,21 @@ struct RegionSessions::Impl { if (const auto* m = std::get_if(&*decoded)) return refresh(c, *m, now_seconds, now); if (const auto* m = std::get_if(&*decoded)) { + if (c.protocol_version == network::session_protocol_v5) + return close(c, SessionCloseReason::protocol, now); // A durable uniqueness check waits for this poll's single `verify` (M10.9d). if (const auto receipt = intents.admit(c.session, *m, admission())) answer(c, *receipt); return; } - if (const auto* m = std::get_if(&*decoded)) + if (const auto* m = std::get_if(&*decoded)) { + if (c.protocol_version == network::session_protocol_v5) + return close(c, SessionCloseReason::protocol, now); return send(c, intents.query(c.session, *m, admission())); + } if (const auto* m = std::get_if(&*decoded)) { + if (c.protocol_version == network::session_protocol_v5) + return close(c, SessionCloseReason::protocol, now); (void)replication.set_interest(c.session, *m).has_value(); // Clamped by the server. return; } @@ -719,7 +727,9 @@ void RegionSessions::poll(const HostFacts& facts, std::uint64_t now_seconds, if (auto* c = m.by_session(session); c && c->state == Impl::State::established) m.answer(*c, receipt); for (const auto& [session, watermark] : m.intents.simulated(m.admission())) - if (auto* c = m.by_session(session); c && c->state == Impl::State::established) + if (auto* c = m.by_session(session); + c && c->state == Impl::State::established && + c->protocol_version == network::session_protocol_version) m.send_datagram(*c, watermark); for (const auto session : m.control.expire(now_seconds)) if (auto* c = m.by_session(session)) diff --git a/tests/quic_sessions.cpp b/tests/quic_sessions.cpp index dc8eedd..92838c9 100644 --- a/tests/quic_sessions.cpp +++ b/tests/quic_sessions.cpp @@ -135,13 +135,15 @@ struct Harness { CHECK(made.has_value()); server = std::move(*made); } - std::unique_ptr connect(const WireGrant& grant) { + std::unique_ptr + connect(const WireGrant& grant, std::uint16_t session_version = session_protocol_version) { client::RegionSessionClientConfig c; c.transport.port = server->port(); c.transport.server_name = std::string{name}; c.transport.authority_pem = files.ca_pem; c.transport.authority_pem_file = files.ca.string(); c.grant = grant; + c.protocol_version = session_version; auto made = RegionSessionClient::connect(std::move(c), Clock::now()); CHECK(made.has_value()); clients.push_back(made->get()); @@ -401,44 +403,29 @@ void primitive_v5_session(const Files& f) { return PrimitiveLifeOutcome{request, PrimitiveLifeResult::unknown, 0, 0}; }; }}; - auto peer = h.raw(); - quic::ConnectionId id = 0; - std::uint64_t session = 0, epoch = 0; - bool sent_request = false; - std::optional receipt; - std::optional outcome; - const auto end = Clock::now() + std::chrono::seconds{10}; - while (Clock::now() < end && !outcome) { - h.pump(); - for (auto& e : peer->poll()) { - if (e.kind == quic::EventKind::connected) { - id = e.connection; - CHECK(peer->send_message( - id, encode_session(SessionHello{0, h.issuer.grant(account(0xA5), 1)}, - session_protocol_v5))); - } else if (e.kind == quic::EventKind::message) { - const auto decoded = decode_session(e.bytes); - CHECK(decoded.has_value()); - if (const auto* welcome = std::get_if(&*decoded)) { - session = welcome->session; - epoch = welcome->epoch; - if (!sent_request) { - sent_request = true; - CHECK(peer->send_message( - id, encode_session(PrimitiveLifeRequest{session, epoch, 42}, - session_protocol_v5))); - } - } else if (const auto* got = std::get_if(&*decoded)) { - receipt = *got; - } else if (const auto* life = std::get_if(&*decoded)) { - outcome = *life; - } - } - } - std::this_thread::sleep_for(std::chrono::milliseconds{1}); - } - CHECK(receipt == PrimitiveLifeReceipt{42, AdmitStatus::admitted, 100}); - CHECK(outcome == PrimitiveLifeOutcome{42, PrimitiveLifeResult::born, 77, 88}); + auto client = h.connect(h.issuer.grant(account(0xA5), 1), session_protocol_v5); + CHECK(h.settled(*client) && client->state() == RegionSessionState::established); + CHECK(client->request_primitive_life(42)); + std::vector receipts; + std::vector outcomes; + CHECK(h.until([&] { + auto more_receipts = client->take_primitive_life_receipts(); + auto more_outcomes = client->take_primitive_life_outcomes(); + receipts.insert(receipts.end(), more_receipts.begin(), more_receipts.end()); + outcomes.insert(outcomes.end(), more_outcomes.begin(), more_outcomes.end()); + return !receipts.empty() && !outcomes.empty(); + })); + CHECK(receipts.front() == PrimitiveLifeReceipt{42, AdmitStatus::admitted, 100}); + CHECK(outcomes.front() == PrimitiveLifeOutcome{42, PrimitiveLifeResult::born, 77, 88}); + CHECK(client->query_primitive_life(42)); + CHECK(h.until([&] { + outcomes = client->take_primitive_life_outcomes(); + return !outcomes.empty(); + })); + CHECK(outcomes.front() == PrimitiveLifeOutcome{42, PrimitiveLifeResult::unknown, 0, 0}); + CHECK(!client->send_action(99, ActionKind::probe, 101)); + CHECK(!client->query_action(99)); + CHECK(!client->send_intention(101, 1, 0)); CHECK(!ledger.claims.empty() && ledger.claims.back().account == account(0xA5)); }