M11.8 server half (ADR-0129): v10 diagnostics report the tick's engulf and bud results in two reserved bytes, and v10 type 27 tells the owner its life ended with the cause (starved or engulfed). The bridge fills both from the owner's tick feedback and corpses; v9 views are unchanged. Client presentation stays with the maintainer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
127 lines
7.9 KiB
C++
127 lines
7.9 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`
|
|
// and `bud` (ADR-0124/0125) are exclusive and need 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, bool bud = 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;
|
|
// The most recent end of the owned life (v10, ADR-0129): its tick and cause.
|
|
[[nodiscard]] const std::optional<network::CellularLifeEnded>& life_ended() 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
|