Files
aevolution/apps/evo-client/remote_session.hpp
T
dingoandClaude Opus 5.5 61d899de3c
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m54s
Foundation / checks (postgres) (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 12m33s
Foundation / checks (network) (push) Canceled after 10m23s
Foundation / checks (client) (push) Canceled after 12m33s
Add M10.6c probe-marker prediction traces and close M10.6
evo-motion-trace drives the engineering client's own session code through
the owned impairment relay against a real-time 50 ms loopback region:
exact without loss, 94-99 % exact at 60-200 ms RTT with 2-5 % loss, every
profile converging after stopping, restart resync about 2-3 s
(docs/networking/M10_PREDICTION_TRACES.md). The CTest motion-trace-smoke
checks convergence, bounds and a majority of exact predictions.

The relay lets a new sender take over after the current client has been
silent for 1 s (reconnects); the client counts refusal receipts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 17:03:45 -04:00

528 lines
24 KiB
C++

#pragma once
// M10.5c remote dev session for the engineering client (ADR-0093, over ADR-0091/0092
// sessions). Without EVO_CLIENT_NETWORK (a build without EVO_BUILD_QUIC) remote mode is
// unavailable. The client only presents copies of replicated snapshots and sends bounded
// intentions; it never predicts. Grant bytes stay inside the session: each is handed to
// one connection and wiped here; never printed, shown or persisted.
//
// One connection per grant (ADR-0089): a lost or closed session reconnects with the next
// grant of the bundle after a growing pause (2 s .. 30 s, reset by a Welcome), which keeps
// a reconnect loop inside the region's per-account attempt limit. Views come from the
// newest applied snapshot. The camera follows the server's default view until the user
// moves it; from then on it drives the interest (radius 7), at most every 250 ms.
//
// M10.6b (ADR-0094, EXPERIMENT): the session's probe marker is predicted. Each input is
// recorded with the predictor and scheduled `lead` ticks ahead (adapted to refusals); each
// snapshot's own marker rebases the prediction; corrections are smoothed for display. An
// intention that was lost or refused is sent again once nothing is in flight and the
// authority holds another vector. While following, the camera and the interest follow the
// predicted marker (or, before a marker exists, the server's default view).
#include "evo/client/camera.hpp"
#include "evo/client/environment_view.hpp"
#include "evo/client/input.hpp"
#include "evo/client/launcher.hpp"
#include "evo/client/organism_view.hpp"
#include "evo/client/outcome_log.hpp"
#include "evo/client/ui_state.hpp"
#include <chrono>
#include <cstdint>
#include <cstdio>
#include <memory>
#include <optional>
#include <string>
#include <vector>
#ifdef EVO_CLIENT_NETWORK
#include "evo/client/motion_prediction.hpp"
#include "evo/client/region_session.hpp"
#include "evo/network/quic_transport.hpp"
#include "evo/world/coordinates.hpp"
#include <algorithm>
#include <cmath>
#include <deque>
#include <type_traits>
#include <utility>
#include <vector>
#endif
namespace evo::client_app {
struct RemoteStatus {
std::string phase; // connecting / connected / reconnecting / out of grants
std::uint64_t session{}, epoch{}, server_tick{}, simulated_tick{};
std::size_t grants_left{};
bool welcomed{};
// Newest applied snapshot and the interest last asked for (ADR-0093).
std::uint64_t snapshot_tick{}, snapshot_bytes{};
std::size_t cells{}, organisms{};
std::int64_t focus_x{}, focus_y{}, focus_z{};
bool focused{};
// The predicted probe marker (ADR-0094).
bool marker{};
double marker_x_mm{}, marker_y_mm{};
std::size_t inputs_pending{}, other_markers{};
std::uint64_t lead{}, corrections{}, max_error_um{}, snaps{};
// Refusal receipts (each, whether or not the input was still pending), inputs the
// predictor removed as refused or dropped as never applied, and repeated vectors.
std::uint64_t refused_inputs{}, rejected_inputs{}, dropped_inputs{}, resends{}, max_pending{};
};
// A probe marker to draw: the own one predicted and smoothed, others as replicated.
struct MarkerView {
double x_mm{}, y_mm{};
bool own{};
};
#ifdef EVO_CLIENT_NETWORK
inline constexpr bool remote_available = true;
static_assert(std::is_same_v<client::GrantRecord, network::WireGrant>,
"the launcher's grant record is the session's grant");
class RemoteSession {
public:
static constexpr std::uint16_t interest_radius = 7;
// Looks the endpoint up once (blocking); nothing connects until the first step().
static std::optional<RemoteSession> open(const client::ConnectMaterial& m) {
const auto address = network::quic::resolve_ipv4(m.endpoint.host);
if (!address || m.grants.empty())
return std::nullopt;
RemoteSession session;
session.transport_.server_address = *address;
session.transport_.port = m.endpoint.port;
session.transport_.server_name = m.server_name;
session.transport_.authority_pem = m.authority_pem;
session.transport_.authority_pem_file = m.authority_path;
session.grants_ = m.grants;
return session;
}
RemoteSession(RemoteSession&&) noexcept = default;
RemoteSession& operator=(RemoteSession&&) noexcept = default;
RemoteSession(const RemoteSession&) = delete;
RemoteSession& operator=(const RemoteSession&) = delete;
~RemoteSession() {
if (client_)
client_->close(); // Close{client_closed}; unresolved intentions stay unknown.
for (auto& g : grants_)
g.fill(0);
}
[[nodiscard]] const client::EnvironmentLayer& environment() const noexcept {
return environment_;
}
[[nodiscard]] const client::OrganismLayer& organisms() const noexcept {
return organisms_;
}
[[nodiscard]] const client::OutcomeLog& outcomes() const noexcept {
return log_;
}
[[nodiscard]] RemoteStatus status() const {
RemoteStatus s;
const bool live = client_ && client_->state() == client::RegionSessionState::established;
s.phase = live ? "connected"
: exhausted_ ? "out of grants"
: welcomed_ ? "reconnecting"
: "connecting";
s.session = session_;
s.epoch = epoch_;
s.server_tick = server_tick_;
s.simulated_tick = simulated_tick_;
s.grants_left = grants_.size() - next_;
s.welcomed = welcomed_;
s.snapshot_tick = seen_snapshot_;
s.snapshot_bytes = snapshot_bytes_ + (client_ ? client_->snapshot_bytes() : 0);
if (const auto* e = environment_.current())
s.cells = e->cells().size();
if (const auto* o = organisms_.current())
s.organisms = o->cells().size();
if (sent_interest_) {
s.focused = true;
s.focus_x = sent_interest_->x;
s.focus_y = sent_interest_->y;
s.focus_z = sent_interest_->z;
}
for (const auto& m : markers_)
if (m.own) {
s.marker = true;
s.marker_x_mm = m.x_mm;
s.marker_y_mm = m.y_mm;
} else {
++s.other_markers;
}
s.inputs_pending = predictor_.pending();
s.lead = lead_.lead();
s.corrections = predictor_.stats().corrections;
s.max_error_um = predictor_.stats().max_error_um;
s.snaps = smoother_.snaps();
s.rejected_inputs = predictor_.stats().rejected_inputs;
s.dropped_inputs = predictor_.stats().dropped_inputs;
s.max_pending = predictor_.stats().max_pending;
s.resends = resends_;
s.refused_inputs = refused_;
return s;
}
// Prediction error samples since the last call (micrometres; for measurements).
[[nodiscard]] std::vector<std::uint64_t> take_prediction_errors() {
return predictor_.take_errors();
}
// Markers to draw this frame (empty without a session or snapshot).
[[nodiscard]] const std::vector<MarkerView>& markers() const noexcept {
return markers_;
}
// Where the camera should be while it follows the server's view: the middle of the
// newest snapshot's square, offered whenever it changes (the first snapshots may still
// be filling in, nearest cells first).
[[nodiscard]] std::optional<client::WorldPoint> take_recentre() {
return std::exchange(recentre_, std::nullopt);
}
// Called every frame with the camera centre. While following, a centre other than the
// one offered means the user moved the camera: from then on the camera's voxel is the
// interest of the next sends.
void focus(client::WorldPoint centre) {
if (!std::isfinite(centre.x_mm) || !std::isfinite(centre.y_mm))
return;
if (following_) {
if (!offered_ || (centre.x_mm == offered_->x_mm && centre.y_mm == offered_->y_mm))
return; // Nothing shown yet, or still where the view put it.
following_ = false;
recentre_.reset();
}
constexpr auto pitch = static_cast<double>(world::cell_pitch_mm);
constexpr double limit = 9.0e15; // Well inside int64 and the camera's own range.
const double x = std::floor(centre.x_mm / pitch), y = std::floor(centre.y_mm / pitch);
if (std::abs(x) > limit || std::abs(y) > limit)
return;
wanted_ = network::SessionInterest{static_cast<std::int64_t>(x),
static_cast<std::int64_t>(y), slice_z_, interest_radius};
}
// Services the connection; sends the intention when its vector changed, at most once
// per server tick. Session events update the outcome log (the record), short
// notifications and the launcher.
void step(std::chrono::steady_clock::time_point now, const client::Intention& intention,
client::UiState& ui, client::Launcher& launcher) {
if (!client_ && !start(now, launcher))
return;
auto& c = *client_;
c.poll(now);
if (c.state() == client::RegionSessionState::closed) {
end(now, ui, launcher);
return;
}
if (c.state() != client::RegionSessionState::established)
return;
if (!established_)
welcome(ui, launcher);
server_tick_ = c.server_tick();
send(intention);
receipts();
snapshot();
present(now);
if (wanted_ && (!sent_interest_ || *wanted_ != *sent_interest_) &&
now - interest_at_ >= std::chrono::milliseconds{250} && c.set_interest(*wanted_)) {
sent_interest_ = wanted_;
interest_at_ = now;
}
std::fflush(stdout);
}
private:
using Clock = std::chrono::steady_clock;
// Session sequences restart with each session; the log numbers intentions itself.
struct Pending {
std::uint64_t sequence{}, entry{}, tick{};
bool admitted{};
};
static constexpr std::size_t max_pending = client::OutcomeLog::capacity;
RemoteSession() = default;
static void notify(client::UiState& ui, const char* text, client::NoticeLevel level) {
static_cast<void>(ui.notify(text, level).has_value()); // Bounded; overflow evicts.
}
// Opens the next connection with the next grant; false while pausing or out of grants.
bool start(Clock::time_point now, client::Launcher& launcher) {
if (now < retry_at_)
return false;
if (next_ >= grants_.size()) {
if (!exhausted_) {
exhausted_ = true;
launcher.observe(client::ConnectSignal::exhausted);
std::puts("session grants exhausted; issue a new bundle to reconnect");
}
return false;
}
client::RegionSessionClientConfig config;
config.transport = transport_;
config.grant = grants_[next_];
grants_[next_].fill(0);
++next_;
auto made = client::RegionSessionClient::connect(std::move(config), now);
if (!made) {
launcher.observe(client::ConnectSignal::lost);
pause(now);
return false;
}
client_ = std::move(*made);
established_ = false;
return true;
}
void pause(Clock::time_point now) {
retry_at_ = now + backoff_;
backoff_ = std::min(backoff_ * 2, std::chrono::seconds{30});
}
void welcome(client::UiState& ui, client::Launcher& launcher) {
const auto& w = *client_->welcome();
established_ = true;
welcomed_ = true;
backoff_ = std::chrono::seconds{2};
if (w.epoch != epoch_) { // Another authority lineage: start the views afresh.
environment_.reset();
organisms_.reset();
seen_snapshot_ = 0;
}
session_ = w.session;
epoch_ = w.epoch;
sent_tick_.reset(); // New session: resend the current intention.
sent_ = {};
sent_interest_.reset(); // The server starts from its default interest.
predictor_.reset(); // A new session has a new marker.
smoother_.reset();
lead_.reset();
launcher.observe(client::ConnectSignal::welcome);
notify(ui, "Connected to the dev region (fresh baseline).", client::NoticeLevel::info);
std::printf("session welcome session=%llu epoch=%llu tick=%llu\n",
static_cast<unsigned long long>(w.session),
static_cast<unsigned long long>(w.epoch),
static_cast<unsigned long long>(w.server_tick));
}
void send(const client::Intention& intention) {
const network::motion::Vector want{intention.move_x, intention.move_y};
if (server_tick_ == 0 || (sent_tick_ && server_tick_ <= *sent_tick_) || predictor_.full())
return;
// Resend when the authority holds another vector and nothing in flight will change
// it (the last intention was lost or refused).
const auto& authority = predictor_.authority();
const bool stale =
authority && authority->state.vector != want && predictor_.pending() == 0;
if (want == sent_ && !stale)
return;
const auto tick = server_tick_ + lead_.lead();
// Refused until the datagram extension is negotiated: retried next frame.
const auto sequence = client_->send_intention(tick, want.x, want.y);
if (!sequence)
return;
static_cast<void>(predictor_.input({*sequence, tick, want}));
resends_ += want == sent_ ? 1 : 0;
sent_ = want;
sent_tick_ = server_tick_;
const auto entry = next_entry_++;
log_.record({entry, client::OutcomeState::sent, 0, tick});
if (pending_.size() == max_pending)
pending_.pop_front(); // Its log entry was evicted with it.
pending_.push_back({*sequence, entry, tick, false});
}
void receipts() {
for (const auto& r : client_->take_intention_receipts()) {
const auto it = std::find_if(pending_.begin(), pending_.end(), [&](const Pending& p) {
return p.sequence == r.sequence;
});
if (it == pending_.end())
continue; // Evicted from the bounded record already.
std::printf("intent %llu status=%u\n", static_cast<unsigned long long>(it->entry),
static_cast<unsigned>(r.status));
if (r.status == network::AdmitStatus::admitted) {
log_.record({it->entry, client::OutcomeState::admitted, 0, it->tick});
it->admitted = true;
lead_.admitted(it->tick, r.server_tick);
} else {
predictor_.rejected(r.sequence); // It never takes effect.
++refused_;
if (r.status == network::AdmitStatus::outside_window)
lead_.too_late(); // Arrived after its tick: schedule further ahead.
log_.record({it->entry, client::OutcomeState::rejected,
static_cast<std::uint8_t>(r.status), it->tick});
pending_.erase(it);
}
}
const auto s = client_->simulated();
if (!s)
return;
simulated_tick_ = s->tick;
// Cumulative: every admitted intention up to the sequence, at or before the tick.
std::erase_if(pending_, [&](const Pending& p) {
if (!p.admitted || p.sequence > s->sequence || p.tick > s->tick)
return false;
log_.record({p.entry, client::OutcomeState::simulated, 0, p.tick});
return true;
});
}
void snapshot() {
const auto* v = client_->view();
if (v == nullptr || v->tick == seen_snapshot_)
return;
seen_snapshot_ = v->tick;
slice_z_ = v->slice_z;
if (auto e = client_->environment()) {
if (!environment_.accept(*e)) { // E.g. regressed after a restore: start afresh.
environment_.reset();
static_cast<void>(environment_.accept(std::move(*e)).has_value());
}
}
if (auto o = client_->organisms()) {
if (!organisms_.accept(*o)) {
organisms_.reset();
static_cast<void>(organisms_.accept(std::move(*o)).has_value());
}
}
others_.clear();
for (const auto& m : v->markers) {
if (m.own)
predictor_.authoritative({v->tick, m.applied_sequence, m.state, m.area});
else
others_.push_back(m);
}
if (!following_ || v->environment.empty() || predictor_.authority())
return; // With a marker, present() follows it instead.
const auto [lx, hx] =
std::minmax_element(v->environment.begin(), v->environment.end(),
[](const auto& a, const auto& b) { return a.voxel.x < b.voxel.x; });
const auto [ly, hy] =
std::minmax_element(v->environment.begin(), v->environment.end(),
[](const auto& a, const auto& b) { return a.voxel.y < b.voxel.y; });
constexpr auto pitch = static_cast<double>(world::cell_pitch_mm);
const client::WorldPoint middle{
(static_cast<double>(lx->voxel.x) + static_cast<double>(hx->voxel.x) + 1) * pitch / 2,
(static_cast<double>(ly->voxel.y) + static_cast<double>(hy->voxel.y) + 1) * pitch / 2};
if (!offered_ || middle.x_mm != offered_->x_mm || middle.y_mm != offered_->y_mm)
recentre_ = offered_ = middle;
}
// The predicted own marker (smoothed) and the others; while following, the camera and
// the interest follow the own marker.
void present(Clock::time_point now) {
const double elapsed =
last_present_ ? std::chrono::duration<double, std::milli>(now - *last_present_).count()
: 0;
last_present_ = now;
markers_.clear();
const auto predicted = predictor_.predict(server_tick_ + lead_.lead());
const auto& authority = predictor_.authority();
if (predicted && authority) {
smoother_.add(predictor_.take_correction());
const auto offset = smoother_.advance(elapsed);
const MarkerView own{static_cast<double>(predicted->x + offset.x) / 1000,
static_cast<double>(predicted->y + offset.y) / 1000, true};
markers_.push_back(own);
if (following_) {
recentre_ = offered_ = client::WorldPoint{own.x_mm, own.y_mm};
wanted_ = network::SessionInterest{cell(predicted->x), cell(predicted->y),
authority->area.z, interest_radius};
}
}
for (const auto& m : others_)
markers_.push_back({static_cast<double>(m.state.x) / 1000,
static_cast<double>(m.state.y) / 1000, false});
}
static std::int64_t cell(std::int64_t um) {
constexpr auto size = network::motion::micrometres_per_cell;
return um >= 0 || um % size == 0 ? um / size : (um / size) - 1;
}
// The connection ended: decide what the launcher hears and pause before the next grant.
void end(Clock::time_point now, client::UiState& ui, client::Launcher& launcher) {
using network::SessionCloseReason;
const auto reason = client_->close_reason().value_or(SessionCloseReason::connection_lost);
const bool was_established = established_;
snapshot_bytes_ += client_->snapshot_bytes();
for (const auto& p : pending_)
log_.record({p.entry, client::OutcomeState::unknown, 0, p.tick});
pending_.clear();
environment_.mark_stale();
organisms_.mark_stale();
predictor_.reset(); // The marker ended with its session.
others_.clear();
markers_.clear();
client_.reset();
established_ = false;
const bool not_ready =
reason == SessionCloseReason::shutdown || reason == SessionCloseReason::capacity;
const bool lost = reason == SessionCloseReason::connection_lost ||
reason == SessionCloseReason::timeout ||
reason == SessionCloseReason::rate_limited ||
reason == SessionCloseReason::stale_epoch ||
(was_established && reason == SessionCloseReason::expired);
if (reason == SessionCloseReason::superseded) {
// Another client holds this account's newer grant: never fight it.
launcher.fail(client::LaunchError::grant_refused);
notify(ui, "Another client opened a session with this account.",
client::NoticeLevel::warning);
} else {
launcher.observe(not_ready ? client::ConnectSignal::not_ready
: lost ? client::ConnectSignal::lost
: client::ConnectSignal::refused);
notify(ui,
not_ready ? "Server not ready; retrying."
: was_established ? "Session ended; reconnecting with the next grant."
: "Connection attempt failed.",
not_ready ? client::NoticeLevel::info : client::NoticeLevel::warning);
}
std::printf("session closed reason=%u\n", static_cast<unsigned>(reason));
pause(now);
}
network::quic::ClientConfig transport_;
std::vector<network::WireGrant> grants_;
std::size_t next_{};
std::unique_ptr<client::RegionSessionClient> client_;
client::EnvironmentLayer environment_;
client::OrganismLayer organisms_;
client::OutcomeLog log_;
std::deque<Pending> pending_;
std::uint64_t next_entry_{1};
Clock::time_point retry_at_{}, interest_at_{};
std::chrono::seconds backoff_{2};
std::uint64_t session_{}, epoch_{}, server_tick_{}, simulated_tick_{}, seen_snapshot_{},
snapshot_bytes_{};
std::optional<std::uint64_t> sent_tick_;
std::optional<network::SessionInterest> wanted_, sent_interest_;
std::optional<client::WorldPoint> recentre_, offered_;
std::int64_t slice_z_{};
network::motion::Vector sent_;
client::MotionPredictor predictor_;
client::CorrectionSmoother smoother_;
client::InputLead lead_;
std::optional<Clock::time_point> last_present_;
std::uint64_t resends_{}, refused_{};
std::vector<network::ReplicatedMarker> others_;
std::vector<MarkerView> markers_;
bool established_{}, welcomed_{}, exhausted_{};
bool following_{true}; // The camera follows the server's (default) view.
};
#else
inline constexpr bool remote_available = false;
class RemoteSession {
public:
static std::optional<RemoteSession> open(const client::ConnectMaterial&) {
return std::nullopt;
}
[[nodiscard]] const client::EnvironmentLayer& environment() const noexcept {
return environment_;
}
[[nodiscard]] const client::OrganismLayer& organisms() const noexcept {
return organisms_;
}
[[nodiscard]] const client::OutcomeLog& outcomes() const noexcept {
return log_;
}
[[nodiscard]] RemoteStatus status() const {
return {"unavailable in this build"};
}
[[nodiscard]] std::optional<client::WorldPoint> take_recentre() {
return std::nullopt;
}
[[nodiscard]] const std::vector<MarkerView>& markers() const noexcept {
return markers_;
}
void focus(client::WorldPoint) {}
void step(std::chrono::steady_clock::time_point, const client::Intention&, client::UiState&,
client::Launcher&) {}
private:
client::EnvironmentLayer environment_;
client::OrganismLayer organisms_;
client::OutcomeLog log_;
std::vector<MarkerView> markers_;
};
#endif
} // namespace evo::client_app