Files
aevolution/include/evo/network/protocol.hpp
T
dingoandClaude Opus 5.5 8e319322f4 Implement M9.7 dev region sessions with durable no-effect intentions
Run a non-blocking TLS 1.3 session server inside evo-server's loop:
environment views come from the region's own field/terrain stores with an
explicitly empty organism presentation; admitted intentions ride the next
synthetic input (content unchanged) and return a durable no-effect outcome
from the host's final acknowledgement, or not_committed when dropped.
Sessions are bound to their connection, epochs close stale sessions, and
connections have bounded output, input rate and deadlines.

SessionClient and evo-client --connect consume one single-use grant per
Hello (refusals before admission keep it), reset to a fresh baseline on
every session, keep stale views visible and report in-flight intentions as
unknown after loss. evo-dev-session generates dev credentials, grant
bundles and runs a restart probe. The dev deployment gains a drill-time,
loopback-only listener with an optional Secret, enforced by the policy
check, and tools/ops/session-drill.sh. Protocol v1 gains IntentOutcome and
the capacity close reason before any deployment. ADR-0083 records the
maintainer-confirmed decisions; M8-dev/stage remains not passed and no
cluster change was made.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 20:12:18 -04:00

162 lines
6.2 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
};
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
};
// 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(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<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