Files
aevolution/include/evo/network/protocol.hpp
T
dingoandClaude Opus 5.5 c588be237c Fix M9.4-M9.7 review findings in the dev session stack
- 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>
2026-10-02 05:44:44 -04:00

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