Framing
The fixed 256-byte header every binary-transport message rides in, and the request, reply and eviction shapes it carries.
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, connection rejection with no body.
The header shape is identified by the command byte at offset 60. Values a client sends or receives:
command | Value | Direction | Meaning |
|---|---|---|---|
Request | 5 | client to server | A command request |
Reply | 8 | server to client | Answer to one request |
Eviction | 13 | server to client | Connection rejected, no per-request correlation |
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.
| Offset | Size | Field | Type | Description |
|---|---|---|---|---|
| 0 | 16 | checksum | u128 | Frame seal. Not used on client-facing frames. Send zero. |
| 16 | 16 | checksum_body | u128 | Body seal. Not used on client-facing frames. Send zero. |
| 32 | 16 | cluster | u128 | Cluster id. Send zero. |
| 48 | 4 | size | u32 | Total frame length: 256 + body length. |
| 52 | 4 | view | u32 | Consensus view. Send zero. |
| 56 | 4 | release | u32 | Must be zero. |
| 60 | 1 | command | u8 | 5 (Request). |
| 61 | 1 | replica | u8 | Send zero. |
| 62 | 66 | reserved | bytes | Zero. |
| 128 | 16 | client | u128 | Client-chosen identity, non-zero. Mint a fresh id for a new logical client. Retain it when resuming that client. |
| 144 | 16 | request_checksum | u128 | Random identity for a logical metadata or session request, retained across retries. Partition and non-replicated requests leave it zero. |
| 160 | 8 | timestamp | u64 | May be zero. Direct replies can echo it, but committed prepares use a server-assigned timestamp. |
| 168 | 8 | request | u64 | Request number, per client. See request numbering. |
| 176 | 1 | operation | u8 | The Operation discriminant. |
| 177 | 7 | padding | bytes | Zero. |
| 184 | 8 | session | u64 | Session fence epoch from the login reply. Zero on the login-register request itself and on non-replicated operations sent before login (only PING is accepted unauthenticated). |
| 192 | 4 | user_id | u32 | Ignored on the wire. The server stamps the authenticated user itself. Send zero. |
| 196 | 4 | command code | u32 | Concrete code for NonReplicated, zero otherwise. |
| 200 | 8 | partition_incarnation | u64 | History identity captured with the request. |
| 208 | 8 | owner_generation | u64 | Consumer group ownership generation, zero without a group. |
| 216 | 8 | minimum_metadata_op | u64 | Minimum metadata progress needed to interpret the request. |
| 224 | 32 | reserved | bytes | Zero on client requests. |
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 | Operation | Plane |
|---|---|---|
| 1 | Register | session (login handshake, codes 40 and 45) |
| 2 | NonReplicated | reads and ping. The u32 code rides bytes 196..200 |
| 3 | Logout | session (code 39) |
| 128 | CreateStream | metadata |
| 130 | DeleteStream | metadata |
| 132 | CreateTopic | metadata |
| 134 | DeleteTopic | metadata |
| 136 | CreatePartitions | metadata |
| 137 | DeletePartitions | metadata |
| 138 | DeleteSegments | metadata (resolved to an internal partition truncation) |
| 139 | CreateConsumerGroup | metadata |
| 140 | DeleteConsumerGroup | metadata |
| 141 | CreateUser | metadata |
| 143 | DeleteUser | metadata |
| 144 | ChangePassword | metadata |
| 145 | UpdatePermissions | metadata |
| 146 | CreatePersonalAccessToken | metadata |
| 147 | DeletePersonalAccessToken | metadata |
| 148 | JoinConsumerGroup | metadata |
| 149 | LeaveConsumerGroup | metadata |
| 150 | UpdateResource | metadata |
| 160 | SendMessages | partition |
| 161 | StoreConsumerOffset | partition |
| 162 | DeleteConsumerOffset | partition |
Value 0 is reserved and rejected. The 64..127 range is reserved for server-internal operations and every value in it is refused from clients.
The metadata plane orders resource and session changes. Each partition plane orders messages and offset changes independently. Partition requests retain their incarnation, ownership generation and metadata requirement across retries. Refreshing a route does not authorize a request against a replacement history.
Request numbering
A retry keeps the original client, session, request number, logical request stamp and arguments. New mutations use new request numbers. Registration uses request zero. Do not infer that a low-numbered request succeeded because a later request committed.
Session-qualified retry protection is retained by the metadata and partition state machines. A full partition table rejects new writers instead of evicting live protection. Ordered retirement releases ended sessions. Receipt recovery is bounded by the session lifetime and retained state. It is not an unlimited exactly-once guarantee.
A reconnect uses BindSession. Ending the session loses access to unresolved receipts. A fresh operation can duplicate an earlier uncertain write. SDKs retain uncertain operations and block conflicting work until resolution or abandonment.
ReplyHeader
Server to client. 256 bytes, followed by size - 256 bytes of body.
| Offset | Size | Field | Type | Description |
|---|---|---|---|---|
| 0 | 16 | checksum | u128 | Zero on client-facing frames. |
| 16 | 16 | checksum_body | u128 | Zero on client-facing frames. |
| 32 | 16 | cluster | u128 | Cluster id. |
| 48 | 4 | size | u32 | Total frame length: 256 + body length. |
| 52 | 4 | view | u32 | View associated with the reply. A cached committed reply retains its original view. Direct replies can echo the request value. |
| 56 | 4 | release | u32 | Zero. |
| 60 | 1 | command | u8 | 8 (Reply). |
| 61 | 1 | replica | u8 | Replica index stamped by the reply builder. Cached committed replies retain the original primary index. |
| 62 | 66 | reserved | bytes | Zero. |
| 128 | 16 | request_checksum | u128 | Echoed from the request. |
| 144 | 16 | context | u128 | Server context. |
| 160 | 16 | client | u128 | Echoed client id. |
| 176 | 8 | op | u64 | Committed log position on consensus replies. Direct replies can instead carry the session epoch or zero. This field alone does not prove a commit. |
| 184 | 8 | commit | u64 | Commit position associated with the reply. A cached committed reply retains its original position. |
| 192 | 8 | timestamp | u64 | Server-assigned prepare timestamp on committed replies, or the request timestamp on direct replies. |
| 200 | 8 | request | u64 | Echoed request number. Non-replicated requests can reuse a number, so it is not a unique correlation id for concurrent reads. |
| 208 | 1 | operation | u8 | Reply operation. Server rewrites can return 64 for CreateTopic, 65 for CreatePartitions, or 68 for DeleteSegments instead of the original client operation. |
| 209 | 7 | padding | bytes | Zero. |
| 216 | 4 | status | u32 | 0 = no header-level failure. Nonzero = an IggyError code for a failure decided before commit (authorization denial, admission reject). A nonzero status always comes with an empty body. |
| 220 | 1 | committed result | u8 | Exactly 1 marks a final committed result. Zero and unknown values provide no proof. |
| 221 | 3 | reserved | bytes | Zero. |
| 224 | 8 | partition_incarnation | u64 | Request or served partition incarnation. Poll body context carries the full served context. |
| 232 | 24 | reserved | bytes | Zero. |
Decode order for a client:
- Read 256 bytes, check
command.13(Eviction) rejects the connection: map the reason and close that link.8(Reply) continues. - Read the remaining
size - 256body bytes. - If
statusis nonzero, this reply reports a pre-commit rejection. It does not settle an earlier uncertain attempt. The body is empty. - Decode the body and any result section. To settle an uncertain mutation, also require the committed-result marker and matching original request identity.
Result section
Replies for all metadata operations, including their server-internal rewrites, and for the partition-plane consumer-offset writes (StoreConsumerOffset, DeleteConsumerOffset) are result-framed. Non-empty Register replies use the same framing. The body starts with a 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. - Business or transient rejection: one entry
{ index: 0, result: error_code }and no payload.
A nonzero header status has an empty body. With status = 0, decode the result section for the operations above: it can report either a committed outcome or a pre-commit transient rejection. Its presence alone does not prove commitment. A matching final result also needs the committed-result marker at byte 220. Replayed PAT creation cannot return the original secret and can report PersonalAccessTokenAlreadyExists with that proof. A successful login-register reply starts with count = 0, followed by the login response payload. An empty Register body is a terminal failure, not a successful login.
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 has no per-request correlation. Close the affected link. A stale-client eviction can occur while the logical session is still live, so try binding the retained session before replacing it. A terminal bind refusal requires a new registration.
| Offset | Size | Field | Type | Description |
|---|---|---|---|---|
| 0 | 16 | checksum | u128 | Zero on client-facing frames. |
| 16 | 16 | checksum_body | u128 | Zero on client-facing frames. |
| 32 | 16 | cluster | u128 | Cluster id. |
| 48 | 4 | size | u32 | Always 256: an eviction has no body. |
| 52 | 4 | view | u32 | |
| 56 | 4 | release | u32 | Zero. |
| 60 | 1 | command | u8 | 13 (Eviction). |
| 61 | 1 | replica | u8 | |
| 62 | 66 | reserved | bytes | Zero. |
| 128 | 16 | client | u128 | The evicted client id. |
| 144 | 4 | server_protocol_version | u32 | Accepted protocol window (max), packed semver. Set only for reason 14, zero otherwise. |
| 148 | 4 | server_protocol_version_min | u32 | Accepted protocol window (min). Set only for reason 14, zero otherwise. |
| 152 | 103 | reserved | bytes | Zero. |
| 255 | 1 | reason | u8 | Eviction reason, see below. |
Eviction reasons:
| Value | Reason | Meaning |
|---|---|---|
| 1 | NoSession | No session exists for this client id |
| 2 | ClientReleaseTooLow | Client release below cluster minimum |
| 3 | ClientReleaseTooHigh | Client release above cluster maximum |
| 4 | InvalidRequestOperation | Unknown operation discriminant |
| 5 | InvalidRequestBody | Body failed validation |
| 6 | InvalidRequestBodySize | Body size mismatch |
| 7 | SessionTooLow | Session epoch below the cluster's retained minimum |
| 8 | SessionReleaseMismatch | Session bound to a different release |
| 9 | InvalidCredentials | Login refused: bad username or password |
| 10 | InvalidToken | Login refused: bad personal access token |
| 11 | UserInactive | Login refused: user inactive |
| 12 | SessionError | Session-level failure |
| 13 | StaleClient | Missed heartbeats. Server evicted the session |
| 14 | IncompatibleProtocol | Client protocol version outside the accepted window (see bytes 144..152) |
| 15 | MalformedLogin | Login body without a decodable version prefix, or a legacy login code |
Value 0 is reserved and never sent.
