- TLS: replace send() with a bounded queue/flush; an interrupted record is retried with identical arguments and later frames wait behind it, so no queued frame is lost or reordered; close() flushes first. - Carriers: server-issued 'I','N' | 48-bit epoch | 64-bit ordinal ids replace the aliasing low-32-bit packing; client sequences are kept separately for replies; out-of-range epochs are refused, never truncated. - Grants: a durable, fsynced, fail-closed consumed-grant ledger (--session-grant-ledger, /objects/dev-session-grants.v1 in dev) keeps single-use grants consumed across process and pod restarts. - Liveness: protocol v1 (undeployed) gains Heartbeat and the timeout close reason; both sides heartbeat when idle and treat 5 s of silence as dead. - Client sends are bounded and unresolved tracking starts at send time. - ci-client configures with an explicit C compiler. Each finding has a regression test; ADR-0083, the schema, operations doc and VALIDATION record the corrections. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
166 lines
6.5 KiB
C++
166 lines
6.5 KiB
C++
#pragma once
|
|
#include "evo/client/environment_view.hpp"
|
|
#include "evo/client/input.hpp"
|
|
#include "evo/client/organism_view.hpp"
|
|
#include <array>
|
|
#include <cstddef>
|
|
#include <cstdint>
|
|
#include <expected>
|
|
#include <optional>
|
|
#include <span>
|
|
#include <utility>
|
|
#include <vector>
|
|
|
|
// M9.6 dev session protocol v1 (schemas/view/dev-session-v1.md, ADR-0082).
|
|
// Explicit little-endian fields only: no native struct is ever copied to or from
|
|
// the wire. Transport-neutral; the M9 channel carries frames inside TLS 1.3.
|
|
namespace evo::network {
|
|
inline constexpr std::uint32_t frame_magic = 0x53445645; // Bytes "EVDS".
|
|
inline constexpr std::uint16_t protocol_version = 1;
|
|
inline constexpr std::size_t frame_header_bytes = 12;
|
|
inline constexpr std::size_t max_frame_payload = std::size_t{256} * 1024;
|
|
inline constexpr std::size_t max_grant_bytes = 512;
|
|
enum class MessageType : std::uint8_t {
|
|
hello = 1,
|
|
welcome,
|
|
intent,
|
|
intent_result,
|
|
environment_view,
|
|
organism_view,
|
|
close,
|
|
intent_outcome,
|
|
heartbeat // Empty payload; proves liveness when no other frame flows (ADR-0083).
|
|
};
|
|
enum class ProtocolError : std::uint8_t {
|
|
truncated,
|
|
bad_magic,
|
|
unsupported_version,
|
|
unknown_type,
|
|
reserved_flags,
|
|
oversized,
|
|
malformed,
|
|
invalid_value,
|
|
trailing_bytes,
|
|
unsupported_feature,
|
|
wrong_type
|
|
};
|
|
// A decoded frame borrows its payload from the input bytes.
|
|
struct FrameView {
|
|
MessageType type;
|
|
std::span<const std::uint8_t> payload;
|
|
};
|
|
struct OwnedFrame {
|
|
MessageType type;
|
|
std::vector<std::uint8_t> payload;
|
|
};
|
|
// Exactly one complete frame; trailing bytes reject.
|
|
[[nodiscard]] std::expected<FrameView, ProtocolError>
|
|
decode_frame(std::span<const std::uint8_t> bytes);
|
|
[[nodiscard]] std::vector<std::uint8_t> encode_frame(MessageType type,
|
|
std::span<const std::uint8_t> payload);
|
|
|
|
// Accumulates a byte stream into frames. The header is validated as soon as it is
|
|
// buffered, so an oversized or foreign frame is rejected before its payload is read.
|
|
// Holds at most one frame (header + max payload). Errors latch.
|
|
class FrameReader {
|
|
public:
|
|
// Consumes bytes up to the end of the current frame; returns how many were taken.
|
|
[[nodiscard]] std::expected<std::size_t, ProtocolError>
|
|
feed(std::span<const std::uint8_t> bytes);
|
|
// The completed frame, if any; reading it resets the reader for the next frame.
|
|
[[nodiscard]] std::optional<OwnedFrame> take();
|
|
|
|
private:
|
|
std::vector<std::uint8_t> buffer_;
|
|
std::size_t expected_{frame_header_bytes};
|
|
std::optional<ProtocolError> error_;
|
|
};
|
|
|
|
// Client -> server. `required_features` must be zero in v1; the grant is opaque here.
|
|
struct Hello {
|
|
std::uint32_t required_features{};
|
|
std::vector<std::uint8_t> grant;
|
|
};
|
|
// Server -> client. Session ids identify, they do not authenticate (the channel does).
|
|
struct Welcome {
|
|
std::uint64_t session{}, world{}, frame{}, region{}, epoch{};
|
|
std::uint64_t server_tick{}, commit_watermark{}, grant_expires_at{};
|
|
std::uint32_t intent_window{}, window_ticks{}, max_intents_per_window{};
|
|
};
|
|
// Client -> server: one bounded movement intention (client::Intention on the wire).
|
|
struct IntentMessage {
|
|
std::uint64_t session{}, epoch{}, sequence{}, tick{};
|
|
std::int16_t move_x{}, move_y{};
|
|
};
|
|
enum class IntentStatus : std::uint8_t {
|
|
admitted,
|
|
unknown_session,
|
|
stale_epoch,
|
|
expired,
|
|
invalid_vector,
|
|
replayed,
|
|
outside_window,
|
|
rate_limited
|
|
};
|
|
// "admitted" means accepted for scheduling at `tick`, not simulated or durable.
|
|
struct IntentResult {
|
|
std::uint64_t sequence{};
|
|
IntentStatus status{};
|
|
std::uint64_t server_tick{};
|
|
};
|
|
// Every view names the session/epoch it belongs to and the durable commit watermark.
|
|
struct ViewHeader {
|
|
std::uint64_t session{}, epoch{}, server_tick{}, commit_watermark{}, baseline{};
|
|
};
|
|
enum class CloseReason : std::uint8_t {
|
|
normal,
|
|
unsupported_version,
|
|
malformed,
|
|
unauthenticated,
|
|
expired,
|
|
duplicate_session,
|
|
stale_epoch,
|
|
rate_limited,
|
|
server_shutdown,
|
|
capacity,
|
|
timeout
|
|
};
|
|
// Final, after the host's durable commit (or loss): the M9.7 dev region has no
|
|
// movable organism, so a committed intention has no biological effect.
|
|
enum class IntentFinality : std::uint8_t { committed_no_effect, not_committed };
|
|
struct IntentOutcome {
|
|
std::uint64_t sequence{};
|
|
IntentFinality finality{};
|
|
std::uint64_t tick{}, commit_sequence{}; // Zero when not committed.
|
|
};
|
|
|
|
[[nodiscard]] std::expected<std::vector<std::uint8_t>, ProtocolError> encode(const Hello& m);
|
|
[[nodiscard]] std::vector<std::uint8_t> encode(const Welcome& m);
|
|
[[nodiscard]] std::vector<std::uint8_t> encode(const IntentMessage& m);
|
|
[[nodiscard]] std::vector<std::uint8_t> encode(const IntentResult& m);
|
|
[[nodiscard]] std::vector<std::uint8_t> encode(CloseReason reason);
|
|
[[nodiscard]] std::vector<std::uint8_t> encode(const IntentOutcome& m);
|
|
[[nodiscard]] std::vector<std::uint8_t> encode_heartbeat();
|
|
[[nodiscard]] std::vector<std::uint8_t> encode(const ViewHeader& header,
|
|
const client::EnvironmentPresentation& view);
|
|
[[nodiscard]] std::vector<std::uint8_t> encode(const ViewHeader& header,
|
|
const client::OrganismPresentation& view);
|
|
|
|
// Decoders take a complete frame and check its type. Views are rebuilt through the
|
|
// validated presentation constructors, never trusted as decoded.
|
|
[[nodiscard]] std::expected<Hello, ProtocolError> decode_hello(FrameView frame);
|
|
[[nodiscard]] std::expected<Welcome, ProtocolError> decode_welcome(FrameView frame);
|
|
[[nodiscard]] std::expected<IntentMessage, ProtocolError> decode_intent(FrameView frame);
|
|
[[nodiscard]] std::expected<IntentResult, ProtocolError> decode_intent_result(FrameView frame);
|
|
[[nodiscard]] std::expected<CloseReason, ProtocolError> decode_close(FrameView frame);
|
|
[[nodiscard]] std::expected<IntentOutcome, ProtocolError> decode_intent_outcome(FrameView frame);
|
|
[[nodiscard]] std::expected<void, ProtocolError> decode_heartbeat(FrameView frame);
|
|
[[nodiscard]] std::expected<std::pair<ViewHeader, client::EnvironmentPresentation>, ProtocolError>
|
|
decode_environment_view(FrameView frame);
|
|
[[nodiscard]] std::expected<std::pair<ViewHeader, client::OrganismPresentation>, ProtocolError>
|
|
decode_organism_view(FrameView frame);
|
|
|
|
[[nodiscard]] IntentMessage make_intent(std::uint64_t session, std::uint64_t epoch,
|
|
const client::Intention& intention) noexcept;
|
|
} // namespace evo::network
|