Framing

Every message on a binary transport is a fixed 256-byte header followed by an optional body. The header is a #[repr(C)] struct decoded by pointer cast (zero-copy), so field offsets are fixed and enforced at compile time in the server. Three header shapes cross the client boundary:

• RequestHeader: client to server.
• ReplyHeader: server to client, answers one request.
• EvictionHeader: server to client, session-terminal rejection with no body.

The header shape is identified by the command byte at offset 60. Values a client sends or receives:

Other command values (Prepare, PrepareOk, view-change traffic, and so on) are replica-to-replica consensus messages and never appear on a client connection. They are documented on the Server-to-server page.

The size field at offset 48 is the total frame length in bytes, header included. A body, when present, immediately follows the 256 header bytes and has length size - 256. Readers can decode size before typing the header. That offset is a protocol constant.

RequestHeader

Client to server. 256 bytes.

Operation discriminants

The operation byte tells the server which state-machine operation the request carries. Replicated operations are identified by operation alone. Non-replicated operations (reads, ping) all use operation = 2 and carry their concrete u32 command code in header bytes 196..200.

Values a client may send:

Value 0 is reserved and rejected. The 64..127 range is reserved for server-internal operations (currently 64 through 68 are assigned) and every value in it is refused from clients.

The planes matter for delivery semantics:

• Metadata operations replicate through the metadata consensus group. The server deduplicates them by (client, request) and caches replies, so a retried request gets the cached answer instead of a double apply (exactly-once).
• Partition operations replicate through their partition's consensus group. They are at-least-once: no reply cache, a replay may apply again.
• Non-replicated operations are reads. They bypass consensus and deduplication entirely.

Request numbering

request is a per-client counter the server's client table tracks for metadata-plane operations:

• Metadata operations must send a strictly increasing request (the SDK advances the counter per metadata request).
• Partition operations and non-replicated operations send the current counter value without advancing it. The server doesn't track theirs.
• The counter is a watermark, not a contiguous sequence: any value above the last accepted one is admissible.

session is the fence epoch: the value handed back by the login reply. Every request after login must echo it. When the same client id registers again, the new registration mints a higher epoch and requests carrying the old one are fenced (rejected as zombies).

ReplyHeader

Server to client. 256 bytes, followed by size - 256 bytes of body.

Decode order for a client:

1. Read 256 bytes, check command. 13 (Eviction) means the session is dead: map the eviction reason to an error and stop. 8 (Reply) continues.
2. Read the remaining size - 256 body bytes.
3. If status is nonzero, the request failed pre-commit. The status value is the IggyError code and the body is empty.
4. Otherwise decode the body. For result-framed operations, strip the result section first.

Result section

Replies for all metadata operations and for the partition-plane consumer-offset writes (StoreConsumerOffset, DeleteConsumerOffset) are result-framed: the body starts with a committed-result section ahead of the typed payload.

[count: u32]
count x { index: u32, result: u32 }

• Success: count = 0, and the typed response payload (if any) follows the 4 count bytes.
• Committed business rejection: one entry { index: 0, result: error_code } and no payload.

The header status channel and the result section are mutually exclusive by construction: a reply either failed pre-commit (status nonzero, empty body) or committed (status zero, result section present). A login-register reply carries the result section only when non-empty. On success its body starts directly with the login response payload.

Replies to non-replicated commands aren't result-framed: after status = 0 the body is the response payload directly.

EvictionHeader

Server to client. 256 bytes, never a body. An eviction is session-terminal: it says "this session is dead", carries no per-request correlation, and a client should deinitialize and re-login.

Eviction reasons:

Value 0 is reserved and never sent.