Add protocol v1: versioned, bounded frames (Hello, Welcome, Intent, IntentResult, environment/organism views, Close) carrying session, epoch and commit watermark, with an explicit little-endian canonical codec, a header-first FrameReader, seeded mutation tests and a libFuzzer target. SessionAdmission enforces world/region scope, grant lifetime and skew, single-use grants, one session per subject, epoch, replay, tick window and per-session rate. Dev identity is a 108-byte HMAC-SHA256 grant (PSA) that cannot be created or verified outside the dev environment. Transport security is TLS 1.3 only via pinned Mbed TLS 4.1.1 LTS with TLS 1.2, DTLS, tickets and PSK compiled out, AEAD suites, ECDHE groups and a pinned dev CA. Opt-in EVO_BUILD_NETWORK, new network CI suite. Sockets and region integration follow in M9.7. ADR-0082 records the decision. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
529 lines
18 KiB
C++
529 lines
18 KiB
C++
#include "evo/network/protocol.hpp"
|
|
#include <algorithm>
|
|
#include <bit>
|
|
#include <utility>
|
|
|
|
namespace evo::network {
|
|
namespace {
|
|
constexpr std::uint8_t last_type = static_cast<std::uint8_t>(MessageType::close);
|
|
constexpr std::uint8_t last_status = static_cast<std::uint8_t>(IntentStatus::rate_limited);
|
|
constexpr std::uint8_t last_reason = static_cast<std::uint8_t>(CloseReason::server_shutdown);
|
|
constexpr std::uint8_t last_presence = static_cast<std::uint8_t>(client::FieldPresence::present);
|
|
constexpr std::uint8_t last_moisture = static_cast<std::uint8_t>(world::MoistureStatus::available);
|
|
constexpr std::uint8_t last_state = static_cast<std::uint8_t>(client::OrganismState::dead);
|
|
|
|
class Writer {
|
|
public:
|
|
void u8(std::uint8_t v) {
|
|
bytes_.push_back(v);
|
|
}
|
|
void u16(std::uint16_t v) {
|
|
put(v, 2);
|
|
}
|
|
void u32(std::uint32_t v) {
|
|
put(v, 4);
|
|
}
|
|
void u64(std::uint64_t v) {
|
|
put(v, 8);
|
|
}
|
|
void i16(std::int16_t v) {
|
|
u16(std::bit_cast<std::uint16_t>(v));
|
|
}
|
|
void i64(std::int64_t v) {
|
|
u64(std::bit_cast<std::uint64_t>(v));
|
|
}
|
|
void raw(std::span<const std::uint8_t> v) {
|
|
bytes_.insert(bytes_.end(), v.begin(), v.end());
|
|
}
|
|
[[nodiscard]] std::vector<std::uint8_t> take() {
|
|
return std::move(bytes_);
|
|
}
|
|
|
|
private:
|
|
void put(std::uint64_t v, int count) {
|
|
for (int i = 0; i < count; ++i)
|
|
bytes_.push_back(static_cast<std::uint8_t>(v >> (8 * i)));
|
|
}
|
|
std::vector<std::uint8_t> bytes_;
|
|
};
|
|
|
|
// Bounds-checked little-endian reader; the first failure is sticky.
|
|
class Reader {
|
|
public:
|
|
explicit Reader(std::span<const std::uint8_t> bytes) : bytes_{bytes} {}
|
|
std::uint8_t u8() {
|
|
return static_cast<std::uint8_t>(get(1));
|
|
}
|
|
std::uint16_t u16() {
|
|
return static_cast<std::uint16_t>(get(2));
|
|
}
|
|
std::uint32_t u32() {
|
|
return static_cast<std::uint32_t>(get(4));
|
|
}
|
|
std::uint64_t u64() {
|
|
return get(8);
|
|
}
|
|
std::int16_t i16() {
|
|
return std::bit_cast<std::int16_t>(u16());
|
|
}
|
|
std::int64_t i64() {
|
|
return std::bit_cast<std::int64_t>(u64());
|
|
}
|
|
std::span<const std::uint8_t> raw(std::size_t count) {
|
|
if (!ok_ || bytes_.size() - at_ < count) {
|
|
ok_ = false;
|
|
return {};
|
|
}
|
|
const auto out = bytes_.subspan(at_, count);
|
|
at_ += count;
|
|
return out;
|
|
}
|
|
// Rejects a value outside [0, last] without consuming further input.
|
|
std::uint8_t bounded(std::uint8_t last) {
|
|
const auto v = u8();
|
|
if (v > last)
|
|
invalid_ = true;
|
|
return v;
|
|
}
|
|
void invalid() {
|
|
invalid_ = true;
|
|
}
|
|
[[nodiscard]] std::expected<void, ProtocolError> finish() const {
|
|
if (!ok_)
|
|
return std::unexpected(ProtocolError::truncated);
|
|
if (invalid_)
|
|
return std::unexpected(ProtocolError::invalid_value);
|
|
if (at_ != bytes_.size())
|
|
return std::unexpected(ProtocolError::trailing_bytes);
|
|
return {};
|
|
}
|
|
[[nodiscard]] bool ok() const noexcept {
|
|
return ok_ && !invalid_;
|
|
}
|
|
|
|
private:
|
|
std::uint64_t get(std::size_t count) {
|
|
if (!ok_ || bytes_.size() - at_ < count) {
|
|
ok_ = false;
|
|
return 0;
|
|
}
|
|
std::uint64_t v = 0;
|
|
for (std::size_t i = 0; i < count; ++i)
|
|
v |= static_cast<std::uint64_t>(bytes_[at_ + i]) << (8 * i);
|
|
at_ += count;
|
|
return v;
|
|
}
|
|
std::span<const std::uint8_t> bytes_;
|
|
std::size_t at_{};
|
|
bool ok_{true}, invalid_{};
|
|
};
|
|
|
|
// Casts only on the validated path; an out-of-range byte flags the reader invalid
|
|
// and yields the enum's zero value, which the decoder then discards.
|
|
template <typename E> E enumerator(Reader& r, std::uint8_t last) {
|
|
const auto v = r.bounded(last);
|
|
return v <= last ? static_cast<E>(v) : E{};
|
|
}
|
|
struct Header {
|
|
MessageType type;
|
|
std::uint32_t length;
|
|
};
|
|
std::expected<Header, ProtocolError> parse_header(std::span<const std::uint8_t> bytes) {
|
|
Reader r{bytes.first(frame_header_bytes)};
|
|
const auto magic = r.u32();
|
|
const auto version = r.u16();
|
|
const auto type = r.u8();
|
|
const auto flags = r.u8();
|
|
const auto length = r.u32();
|
|
if (magic != frame_magic)
|
|
return std::unexpected(ProtocolError::bad_magic);
|
|
if (version != protocol_version)
|
|
return std::unexpected(ProtocolError::unsupported_version);
|
|
if (type == 0 || type > last_type)
|
|
return std::unexpected(ProtocolError::unknown_type);
|
|
if (flags != 0)
|
|
return std::unexpected(ProtocolError::reserved_flags);
|
|
if (length > max_frame_payload)
|
|
return std::unexpected(ProtocolError::oversized);
|
|
return Header{static_cast<MessageType>(type), length};
|
|
}
|
|
std::vector<std::uint8_t> framed(MessageType type, Writer& payload) {
|
|
const auto bytes = payload.take();
|
|
return encode_frame(type, bytes);
|
|
}
|
|
std::expected<Reader, ProtocolError> open(FrameView frame, MessageType type) {
|
|
if (frame.type != type)
|
|
return std::unexpected(ProtocolError::wrong_type);
|
|
return Reader{frame.payload};
|
|
}
|
|
void write(Writer& w, const ViewHeader& h) {
|
|
w.u64(h.session);
|
|
w.u64(h.epoch);
|
|
w.u64(h.server_tick);
|
|
w.u64(h.commit_watermark);
|
|
w.u64(h.baseline);
|
|
}
|
|
ViewHeader read_view_header(Reader& r) {
|
|
ViewHeader h;
|
|
h.session = r.u64();
|
|
h.epoch = r.u64();
|
|
h.server_tick = r.u64();
|
|
h.commit_watermark = r.u64();
|
|
h.baseline = r.u64();
|
|
return h;
|
|
}
|
|
} // namespace
|
|
|
|
std::vector<std::uint8_t> encode_frame(MessageType type, std::span<const std::uint8_t> payload) {
|
|
Writer w;
|
|
w.u32(frame_magic);
|
|
w.u16(protocol_version);
|
|
w.u8(static_cast<std::uint8_t>(type));
|
|
w.u8(0);
|
|
w.u32(static_cast<std::uint32_t>(payload.size()));
|
|
w.raw(payload);
|
|
return w.take();
|
|
}
|
|
|
|
std::expected<FrameView, ProtocolError> decode_frame(std::span<const std::uint8_t> bytes) {
|
|
if (bytes.size() < frame_header_bytes)
|
|
return std::unexpected(ProtocolError::truncated);
|
|
const auto header = parse_header(bytes);
|
|
if (!header)
|
|
return std::unexpected(header.error());
|
|
const auto total = frame_header_bytes + header->length;
|
|
if (bytes.size() < total)
|
|
return std::unexpected(ProtocolError::truncated);
|
|
if (bytes.size() > total)
|
|
return std::unexpected(ProtocolError::trailing_bytes);
|
|
return FrameView{header->type, bytes.subspan(frame_header_bytes)};
|
|
}
|
|
|
|
std::expected<std::size_t, ProtocolError> FrameReader::feed(std::span<const std::uint8_t> bytes) {
|
|
if (error_)
|
|
return std::unexpected(*error_);
|
|
std::size_t taken = 0;
|
|
while (taken < bytes.size() && buffer_.size() < expected_) {
|
|
const auto count = std::min(expected_ - buffer_.size(), bytes.size() - taken);
|
|
buffer_.insert(buffer_.end(), bytes.begin() + static_cast<std::ptrdiff_t>(taken),
|
|
bytes.begin() + static_cast<std::ptrdiff_t>(taken + count));
|
|
taken += count;
|
|
if (buffer_.size() == frame_header_bytes && expected_ == frame_header_bytes) {
|
|
const auto header = parse_header(buffer_);
|
|
if (!header) {
|
|
error_ = header.error();
|
|
buffer_.clear();
|
|
return std::unexpected(*error_);
|
|
}
|
|
expected_ = frame_header_bytes + header->length;
|
|
if (header->length == 0)
|
|
break;
|
|
}
|
|
}
|
|
return taken;
|
|
}
|
|
|
|
std::optional<OwnedFrame> FrameReader::take() {
|
|
if (error_ || buffer_.size() < frame_header_bytes || buffer_.size() != expected_)
|
|
return std::nullopt;
|
|
OwnedFrame frame{static_cast<MessageType>(buffer_[6]),
|
|
{buffer_.begin() + frame_header_bytes, buffer_.end()}};
|
|
buffer_.clear();
|
|
expected_ = frame_header_bytes;
|
|
return frame;
|
|
}
|
|
|
|
std::expected<std::vector<std::uint8_t>, ProtocolError> encode(const Hello& m) {
|
|
if (m.grant.empty() || m.grant.size() > max_grant_bytes)
|
|
return std::unexpected(ProtocolError::invalid_value);
|
|
Writer w;
|
|
w.u32(m.required_features);
|
|
w.u16(static_cast<std::uint16_t>(m.grant.size()));
|
|
w.raw(m.grant);
|
|
return framed(MessageType::hello, w);
|
|
}
|
|
|
|
std::vector<std::uint8_t> encode(const Welcome& m) {
|
|
Writer w;
|
|
for (const auto v : {m.session, m.world, m.frame, m.region, m.epoch, m.server_tick,
|
|
m.commit_watermark, m.grant_expires_at})
|
|
w.u64(v);
|
|
w.u32(m.intent_window);
|
|
w.u32(m.window_ticks);
|
|
w.u32(m.max_intents_per_window);
|
|
return framed(MessageType::welcome, w);
|
|
}
|
|
|
|
std::vector<std::uint8_t> encode(const IntentMessage& m) {
|
|
Writer w;
|
|
w.u64(m.session);
|
|
w.u64(m.epoch);
|
|
w.u64(m.sequence);
|
|
w.u64(m.tick);
|
|
w.i16(m.move_x);
|
|
w.i16(m.move_y);
|
|
return framed(MessageType::intent, w);
|
|
}
|
|
|
|
std::vector<std::uint8_t> encode(const IntentResult& m) {
|
|
Writer w;
|
|
w.u64(m.sequence);
|
|
w.u8(static_cast<std::uint8_t>(m.status));
|
|
w.u64(m.server_tick);
|
|
return framed(MessageType::intent_result, w);
|
|
}
|
|
|
|
std::vector<std::uint8_t> encode(CloseReason reason) {
|
|
Writer w;
|
|
w.u8(static_cast<std::uint8_t>(reason));
|
|
return framed(MessageType::close, w);
|
|
}
|
|
|
|
std::vector<std::uint8_t> encode(const ViewHeader& header,
|
|
const client::EnvironmentPresentation& view) {
|
|
Writer w;
|
|
write(w, header);
|
|
const auto revision = view.revision();
|
|
w.u64(revision.identity.world);
|
|
w.u64(revision.identity.frame);
|
|
w.u64(revision.tick);
|
|
w.u64(revision.field_revision);
|
|
w.u32(view.requested_mask());
|
|
w.i64(view.slice_z());
|
|
w.u16(static_cast<std::uint16_t>(view.cells().size()));
|
|
for (const auto& c : view.cells()) {
|
|
w.i64(c.voxel.x);
|
|
w.i64(c.voxel.y);
|
|
w.u64(c.chunk_revision);
|
|
for (const auto v : {c.habitat.x, c.habitat.y, c.habitat.z, c.habitat.width,
|
|
c.habitat.height, c.habitat.depth})
|
|
w.u32(static_cast<std::uint32_t>(v.value)); // Validated <= 1e6 um.
|
|
w.u64(c.volume.value);
|
|
w.u16(c.substrate.value);
|
|
w.u16(c.terrain_material.value);
|
|
w.u16(c.terrain_fill);
|
|
for (std::size_t k = 0; k < world::field_count; ++k) {
|
|
w.u8(static_cast<std::uint8_t>(c.presence.at(k)));
|
|
if (c.presence.at(k) == client::FieldPresence::present)
|
|
w.u64(c.quantity.at(k));
|
|
}
|
|
w.u8(static_cast<std::uint8_t>(c.moisture_status));
|
|
if (c.moisture_status == world::MoistureStatus::available) {
|
|
w.u64(c.moisture.numerator);
|
|
w.u64(c.moisture.denominator);
|
|
}
|
|
}
|
|
return framed(MessageType::environment_view, w);
|
|
}
|
|
|
|
std::vector<std::uint8_t> encode(const ViewHeader& header,
|
|
const client::OrganismPresentation& view) {
|
|
Writer w;
|
|
write(w, header);
|
|
const auto revision = view.revision();
|
|
w.u64(revision.identity.world);
|
|
w.u64(revision.identity.frame);
|
|
w.u64(revision.tick);
|
|
w.u64(revision.revision);
|
|
w.i64(view.slice_z());
|
|
w.u16(static_cast<std::uint16_t>(view.cells().size()));
|
|
for (const auto& c : view.cells()) {
|
|
const auto& p = c.phenotype;
|
|
w.u64(c.id);
|
|
w.i64(c.voxel.x);
|
|
w.i64(c.voxel.y);
|
|
w.u32(static_cast<std::uint32_t>(c.x.value)); // Validated < 1e6 um.
|
|
w.u32(static_cast<std::uint32_t>(c.y.value));
|
|
w.u64(p.structural_mass);
|
|
w.u64(p.membrane_mass);
|
|
w.u64(p.total_mass);
|
|
w.u32(p.extent);
|
|
w.u64(p.surface);
|
|
w.u64(p.maintenance);
|
|
w.u32(p.movement_speed);
|
|
w.u64(p.ingestion_rate);
|
|
w.u32(p.conversion_per_thousand);
|
|
w.u32(p.thermal_shortfall);
|
|
w.u32(c.growth.realized_per_thousand);
|
|
w.u32(c.growth.damage_per_thousand);
|
|
w.u8(static_cast<std::uint8_t>(c.state));
|
|
}
|
|
return framed(MessageType::organism_view, w);
|
|
}
|
|
|
|
std::expected<Hello, ProtocolError> decode_hello(FrameView frame) {
|
|
auto r = open(frame, MessageType::hello);
|
|
if (!r)
|
|
return std::unexpected(r.error());
|
|
Hello m;
|
|
m.required_features = r->u32();
|
|
const auto length = r->u16();
|
|
if (length == 0 || length > max_grant_bytes)
|
|
r->invalid();
|
|
const auto grant = r->raw(r->ok() ? length : 0);
|
|
if (auto done = r->finish(); !done)
|
|
return std::unexpected(done.error());
|
|
if (m.required_features != 0)
|
|
return std::unexpected(ProtocolError::unsupported_feature);
|
|
m.grant.assign(grant.begin(), grant.end());
|
|
return m;
|
|
}
|
|
|
|
std::expected<Welcome, ProtocolError> decode_welcome(FrameView frame) {
|
|
auto r = open(frame, MessageType::welcome);
|
|
if (!r)
|
|
return std::unexpected(r.error());
|
|
Welcome m;
|
|
m.session = r->u64();
|
|
m.world = r->u64();
|
|
m.frame = r->u64();
|
|
m.region = r->u64();
|
|
m.epoch = r->u64();
|
|
m.server_tick = r->u64();
|
|
m.commit_watermark = r->u64();
|
|
m.grant_expires_at = r->u64();
|
|
m.intent_window = r->u32();
|
|
m.window_ticks = r->u32();
|
|
m.max_intents_per_window = r->u32();
|
|
if (auto done = r->finish(); !done)
|
|
return std::unexpected(done.error());
|
|
if (m.session == 0 || m.window_ticks == 0 || m.max_intents_per_window == 0)
|
|
return std::unexpected(ProtocolError::invalid_value);
|
|
return m;
|
|
}
|
|
|
|
std::expected<IntentMessage, ProtocolError> decode_intent(FrameView frame) {
|
|
auto r = open(frame, MessageType::intent);
|
|
if (!r)
|
|
return std::unexpected(r.error());
|
|
IntentMessage m;
|
|
m.session = r->u64();
|
|
m.epoch = r->u64();
|
|
m.sequence = r->u64();
|
|
m.tick = r->u64();
|
|
m.move_x = r->i16();
|
|
m.move_y = r->i16();
|
|
if (auto done = r->finish(); !done)
|
|
return std::unexpected(done.error());
|
|
return m; // Range/semantics belong to admission, which reports a status.
|
|
}
|
|
|
|
std::expected<IntentResult, ProtocolError> decode_intent_result(FrameView frame) {
|
|
auto r = open(frame, MessageType::intent_result);
|
|
if (!r)
|
|
return std::unexpected(r.error());
|
|
IntentResult m;
|
|
m.sequence = r->u64();
|
|
m.status = enumerator<IntentStatus>(*r, last_status);
|
|
m.server_tick = r->u64();
|
|
if (auto done = r->finish(); !done)
|
|
return std::unexpected(done.error());
|
|
return m;
|
|
}
|
|
|
|
std::expected<CloseReason, ProtocolError> decode_close(FrameView frame) {
|
|
auto r = open(frame, MessageType::close);
|
|
if (!r)
|
|
return std::unexpected(r.error());
|
|
const auto reason = enumerator<CloseReason>(*r, last_reason);
|
|
if (auto done = r->finish(); !done)
|
|
return std::unexpected(done.error());
|
|
return reason;
|
|
}
|
|
|
|
std::expected<std::pair<ViewHeader, client::EnvironmentPresentation>, ProtocolError>
|
|
decode_environment_view(FrameView frame) {
|
|
auto r = open(frame, MessageType::environment_view);
|
|
if (!r)
|
|
return std::unexpected(r.error());
|
|
const auto header = read_view_header(*r);
|
|
client::EnvironmentRevision revision;
|
|
revision.identity.world = r->u64();
|
|
revision.identity.frame = r->u64();
|
|
revision.tick = r->u64();
|
|
revision.field_revision = r->u64();
|
|
const auto mask = r->u32();
|
|
const auto slice = r->i64();
|
|
const auto count = r->u16();
|
|
if (count > client::max_environment_cells)
|
|
r->invalid();
|
|
std::vector<client::EnvironmentCell> cells;
|
|
for (std::uint16_t i = 0; r->ok() && i < count; ++i) {
|
|
client::EnvironmentCell c;
|
|
c.voxel = {r->i64(), r->i64(), slice};
|
|
c.chunk_revision = r->u64();
|
|
c.habitat = {{r->u32()}, {r->u32()}, {r->u32()}, {r->u32()}, {r->u32()}, {r->u32()}};
|
|
c.volume = {r->u64()};
|
|
c.substrate = {r->u16()};
|
|
c.terrain_material = {r->u16()};
|
|
c.terrain_fill = r->u16();
|
|
for (std::size_t k = 0; k < world::field_count; ++k) {
|
|
c.presence.at(k) = enumerator<client::FieldPresence>(*r, last_presence);
|
|
if (c.presence.at(k) == client::FieldPresence::present)
|
|
c.quantity.at(k) = r->u64();
|
|
}
|
|
c.moisture_status = enumerator<world::MoistureStatus>(*r, last_moisture);
|
|
if (c.moisture_status == world::MoistureStatus::available)
|
|
c.moisture = {r->u64(), r->u64()};
|
|
cells.push_back(c);
|
|
}
|
|
if (auto done = r->finish(); !done)
|
|
return std::unexpected(done.error());
|
|
auto view = client::EnvironmentPresentation::create(revision, mask, slice, cells);
|
|
if (!view)
|
|
return std::unexpected(ProtocolError::invalid_value);
|
|
return std::pair{header, std::move(*view)};
|
|
}
|
|
|
|
std::expected<std::pair<ViewHeader, client::OrganismPresentation>, ProtocolError>
|
|
decode_organism_view(FrameView frame) {
|
|
auto r = open(frame, MessageType::organism_view);
|
|
if (!r)
|
|
return std::unexpected(r.error());
|
|
const auto header = read_view_header(*r);
|
|
client::OrganismRevision revision;
|
|
revision.identity.world = r->u64();
|
|
revision.identity.frame = r->u64();
|
|
revision.tick = r->u64();
|
|
revision.revision = r->u64();
|
|
const auto slice = r->i64();
|
|
const auto count = r->u16();
|
|
if (count > client::max_organism_cells)
|
|
r->invalid();
|
|
std::vector<client::OrganismCell> cells;
|
|
for (std::uint16_t i = 0; r->ok() && i < count; ++i) {
|
|
client::OrganismCell c;
|
|
c.id = r->u64();
|
|
c.voxel = {r->i64(), r->i64(), slice};
|
|
c.x = {r->u32()};
|
|
c.y = {r->u32()};
|
|
auto& p = c.phenotype;
|
|
p.structural_mass = r->u64();
|
|
p.membrane_mass = r->u64();
|
|
p.total_mass = r->u64();
|
|
p.extent = r->u32();
|
|
p.surface = r->u64();
|
|
p.maintenance = r->u64();
|
|
p.movement_speed = r->u32();
|
|
p.ingestion_rate = r->u64();
|
|
p.conversion_per_thousand = r->u32();
|
|
p.thermal_shortfall = r->u32();
|
|
c.growth.realized_per_thousand = r->u32();
|
|
c.growth.damage_per_thousand = r->u32();
|
|
c.state = enumerator<client::OrganismState>(*r, last_state);
|
|
cells.push_back(c);
|
|
}
|
|
if (auto done = r->finish(); !done)
|
|
return std::unexpected(done.error());
|
|
auto view = client::OrganismPresentation::create(revision, slice, cells);
|
|
if (!view)
|
|
return std::unexpected(ProtocolError::invalid_value);
|
|
return std::pair{header, std::move(*view)};
|
|
}
|
|
|
|
IntentMessage make_intent(std::uint64_t session, std::uint64_t epoch,
|
|
const client::Intention& intention) noexcept {
|
|
return {session, epoch, intention.sequence, intention.tick, intention.move_x, intention.move_y};
|
|
}
|
|
} // namespace evo::network
|