Files
aevolution/include/evo/client/region_session.hpp
T
dingoandClaude Opus 5.5 f77956e579 Send the owner its outstanding mutation offer over v10
Session protocol v10 adds type 26: the life's earned offer with its unranked
candidates in operator order and each successor's capability value,
maintenance and total mass. The cellular bridge sends it when the offer or the
owner's session changes and clears a consumed offer; the client keeps the
latest one for the maintainer's choice UI (ADR-0121, 11.4d server half).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 23:07:50 -04:00

125 lines
7.7 KiB
C++

#pragma once
#include "evo/network/quic_transport.hpp"
#include "evo/network/replication.hpp"
#include "evo/network/session_protocol.hpp"
#include <chrono>
#include <cstdint>
#include <expected>
#include <memory>
#include <optional>
#include <utility>
#include <vector>
// M10.3b client-side session login over QUIC (ADR-0091, schemas/network/session-v1.md).
// Owned by one thread, which calls poll(). Sends Hello with the grant once the pinned
// connection is up (then forgets the grant), waits for Welcome or Close, and can renew
// the session in place with a newer grant. A Close from the server, a malformed message,
// the Welcome deadline or a lost transport ends the session; reconnecting needs a new
// client and a fresh grant (ADR-0089). M10.4 (ADR-0092): intentions as datagrams with
// receipts and a simulated watermark; actions with stable ids, receipts and final outcomes.
// The client never treats a receipt or the watermark as a final outcome.
// M10.5 (ADR-0093): snapshot chunks are assembled and acknowledged here; the newest complete
// snapshot is available as a view and as validated presentations.
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 };
class RegionSessionClient {
public:
[[nodiscard]] static std::expected<std::unique_ptr<RegionSessionClient>,
network::quic::EndpointError>
connect(RegionSessionClientConfig config, std::chrono::steady_clock::time_point now);
RegionSessionClient(const RegionSessionClient&) = delete;
RegionSessionClient& operator=(const RegionSessionClient&) = delete;
~RegionSessionClient();
void poll(std::chrono::steady_clock::time_point now);
// Sends a newer grant for the open session; false unless established and sent.
[[nodiscard]] bool refresh(const network::WireGrant& grant);
// The latest refresh answer, once (an accepted one also updates welcome().expires_at).
[[nodiscard]] std::optional<network::SessionRefreshResult> take_refresh_result();
// Sends Close{client_closed} and closes the connection.
void close();
// Realtime intention for `tick` (server_tick + 1 ..= + 8); returns its sequence, or
// nothing unless established and sent (also while the QUIC datagram extension is not yet
// negotiated, just after Welcome: retry). Datagrams may be lost: no receipt is not a
// refusal.
[[nodiscard]] std::optional<std::uint64_t>
send_intention(std::uint64_t tick, std::int16_t move_x, std::int16_t move_y);
// Protocol v6 only. Optional target fields name a visible food patch; they never claim
// position, speed, inventory or acquired stock.
[[nodiscard]] std::optional<std::uint64_t> send_cellular_intention(
std::uint64_t tick, std::int16_t move_x, std::int16_t move_y,
std::optional<std::pair<std::uint32_t, std::uint32_t>> intake_target = {});
// A discrete action with a caller-chosen id, unique for the account (stable across
// retries and reconnects). False unless established and sent.
[[nodiscard]] bool send_action(std::uint64_t action_id, network::ActionKind kind,
std::uint64_t tick);
// Protocol v7-v10. Reuse the exact same fields and action id after reconnect. `engulf`
// (ADR-0124) needs a v10 session and no intake target.
[[nodiscard]] bool
send_cellular_action(std::uint64_t action_id, std::uint64_t tick, std::int16_t move_x,
std::int16_t move_y,
std::optional<std::pair<std::uint32_t, std::uint32_t>> intake_target = {},
bool engulf = false);
// Protocol v10 (ADR-0121): choose one candidate of the life's outstanding offer. The
// receipt names the tick it publishes with; the outcome follows that commit. `tick` is
// the client's latest simulated tick (after the offer); the server schedules the next.
[[nodiscard]] bool send_cellular_mutation(std::uint64_t action_id, std::uint64_t tick,
std::uint64_t life_identity,
std::uint64_t event_index, std::uint64_t offer_tick,
std::uint16_t operator_id);
[[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<network::PrimitiveLifeReceipt> take_primitive_life_receipts();
[[nodiscard]] std::vector<network::PrimitiveLifeOutcome> take_primitive_life_outcomes();
[[nodiscard]] std::vector<network::IntentionReceipt> take_intention_receipts();
[[nodiscard]] std::vector<network::ActionReceipt> take_action_receipts();
[[nodiscard]] std::vector<network::ActionOutcome> take_action_outcomes();
// Newest simulated watermark of this session's epoch.
[[nodiscard]] std::optional<network::SimulatedThrough> simulated() const noexcept;
// Latest server tick seen (Welcome, receipts, watermarks); 0 before Welcome.
[[nodiscard]] std::uint64_t server_tick() const noexcept;
// Asks for another spatial focus (the server clamps it and restarts from a fresh
// baseline). False unless established and sent.
[[nodiscard]] bool set_interest(const network::SessionInterest& interest);
// The newest complete snapshot, or null before the first.
[[nodiscard]] const network::ReplicatedView* view() const noexcept;
// Newest owner-filtered cellular sensor view (v8), cleared when no owned life exists.
[[nodiscard]] const std::optional<network::CellularPerception>&
cellular_perception() const noexcept;
// The owned life's outstanding mutation offer (v10), cleared when consumed or absent.
[[nodiscard]] const std::optional<network::CellularMutationOffer>&
mutation_offer() const noexcept;
[[nodiscard]] std::expected<client::EnvironmentPresentation, client::ViewError>
environment() const;
[[nodiscard]] std::expected<client::OrganismPresentation, client::ViewError> organisms() const;
// Snapshot datagrams and bytes received (whole messages), for reporting.
[[nodiscard]] std::uint64_t snapshot_chunks() const noexcept;
[[nodiscard]] std::uint64_t snapshot_bytes() const noexcept;
[[nodiscard]] RegionSessionState state() const noexcept;
[[nodiscard]] const std::optional<network::SessionWelcome>& welcome() const noexcept;
[[nodiscard]] std::optional<network::SessionCloseReason> close_reason() const noexcept;
// v4 (ADR-0096): the offer to continue at another region (kept until taken; the session
// then closes with handed_off), and where the account's probe is when a login was closed
// with moved.
[[nodiscard]] std::optional<network::HandoffOffer> take_handoff();
[[nodiscard]] const std::optional<network::RegionAddress>& redirect() const noexcept;
// Why the QUIC connection itself ended (e.g. `untrusted`: the server answered but its
// certificate failed the pinned check), when it ended without a session Close.
[[nodiscard]] std::optional<network::quic::CloseCause> transport_cause() const noexcept;
private:
struct Impl;
explicit RegionSessionClient(std::unique_ptr<Impl> impl);
std::unique_ptr<Impl> impl_;
};
} // namespace evo::client