hoy-protocol

Wire-level protocol defining packets and codec of the hoy app.

Index

• Lib modules
• Frame format
• Packets
  • ClientPacket — client → server
  • ServerPacket — server → client
  • MessageRecord
  • JSON wire shapes
• Codec
  • encode_frame(value) -> Result, ProtocolError>
  • decode_frame(frame) -> Result
  • try_decode_frame(buffer) -> Result, ProtocolError>
• FrameBuffer
  • Methods
• Error types
• Streaming behaviour

Lib modules

• codec: encode_frame, decode_frame, try_decode_frame
• error: ProtocolError
• frame_buffer: FrameBuffer — streaming byte buffer with incremental decoding
• packet: ClientPacket, ServerPacket

Frame format

Every message is a length-prefixed frame:

┌──────────────────────┬─────────────────────────────────┐
│  header  (4 bytes)   │  payload  (header value bytes)  │
│  u32, big-endian     │  UTF-8 JSON                     │
└──────────────────────┴─────────────────────────────────┘

• Header — the payload length encoded as a u32 in big-endian byte order.
• Payload — the JSON-serialised packet (serde_json), length in bytes matching the header exactly.
• Total frame size — 4 + payload_len bytes.

There is no maximum payload size enforced beyond the u32 ceiling (~4 GB).

Packets

ClientPacket — client → server

ServerPacket — server → client

MessageRecord

A single message entry carried inside RoomJoined.messages:

JSON wire shapes

Serde serialises unit variants as plain JSON strings and struct variants as single-key objects:

// ClientPacket
{"Hello":       {"username": "alice"}}
{"SendMessage": {"text": "hello all"}}
{"JoinRoom":    {"room": "rust"}}
"ListRooms"
"Ping"

// ServerPacket
{"Welcome":       {"username": "alice", "room": "general"}}
{"ChatMessage":   {"from": "alice", "room": "general", "text": "hello all"}}
{"SystemMessage": {"text": "bob joined #general"}}
{"RoomJoined":    {"room": "rust", "messages": [{"from": "alice", "text": "hey"}]}}
{"RoomList":      {"rooms": ["general", "rust"]}}
{"Error":         {"message": "Username \"bob\" is already in use"}}
"Pong"

Codec

encode_frame(value) -> Result<Vec<u8>, ProtocolError>

Serialises value to JSON, prepends the 4-byte big-endian length header, and returns the complete frame as a Vec<u8>.

encode_frame(&ClientPacket::Ping)
  → serde_json::to_vec  →  b"\"Ping\""          (6 bytes)
  → header              →  [0, 0, 0, 6]
  → frame               →  [0, 0, 0, 6, '"', 'P', 'i', 'n', 'g', '"']

decode_frame<T>(frame) -> Result<T, ProtocolError>

Decodes a buffer that is known to contain at least one complete frame. Returns an error if the buffer is too short (TruncatedFrame). Trailing bytes after the frame are silently ignored.

try_decode_frame<T>(buffer) -> Result<Option<(T, usize)>, ProtocolError>

Non-blocking streaming decoder. Returns:

The consumed count lets the caller advance its read position without any internal mutation.

FrameBuffer

FrameBuffer wraps a Vec<u8> and provides incremental decoding over a TCP stream:

let mut buf = FrameBuffer::with_capacity(4096);

// inside a read loop:
buf.append(&tcp_chunk)?;

while let Some(packet) = buf.try_decode::<ServerPacket>()? {
    handle(packet);
}

Methods

try_decode mirrors try_decode_frame semantics — Ok(None) means more data is needed, not an error. Each call decodes at most one frame; loop until None to drain all available frames.

Error types

ProtocolError variants:

Streaming behaviour

TCP is a byte stream — a single read() call can return a partial frame, multiple frames, or anything in between. The protocol handles this in two layers:

1. try_decode_frame — stateless function. Given a slice, it returns Ok(None) if the slice is too short (incomplete header or payload), a decoded value plus consumed-byte count on success, or an error for malformed data.

2. FrameBuffer — stateful wrapper. It accumulates raw bytes across multiple reads and removes exactly the bytes belonging to a complete frame when one is decoded. Bytes from subsequent frames are retained for the next try_decode call.

read #1: [0, 0, 0, 10, '{']             → try_decode → None  (5 of 14 bytes)
read #2: ['"', 'H', 'e', 'l', 'l']      → try_decode → None  (10 of 14 bytes)
read #3: ['o', '"', '}', 0, 0, 0, 2]    → try_decode → Some(Hello { .. })
                                          buffer now holds [0, 0, 0, 2]