If Apache Iggy is useful to you, give it a star on GitHubStar apache/iggy
Skip to Content
Apache Iggy
Binary Protocol
These are the docs for Apache Iggy 0.10, kept for reference and no longer updated. Read the current docs.

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:

commandValueDirectionMeaning
Request5client to serverA command request
Reply8server to clientAnswer to one request
Eviction13server to clientConnection 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.

OffsetSizeFieldTypeDescription
016checksumu128Frame seal. Not used on client-facing frames. Send zero.
1616checksum_bodyu128Body seal. Not used on client-facing frames. Send zero.
3216clusteru128Cluster id. Send zero.
484sizeu32Total frame length: 256 + body length.
524viewu32Consensus view. Send zero.
564releaseu32Must be zero.
601commandu85 (Request).
611replicau8Send zero.
6266reservedbytesZero.
12816clientu128Client-chosen identity, non-zero. Mint a fresh id for a new logical client. Retain it when resuming that client.
14416request_checksumu128Random identity for a logical metadata or session request, retained across retries. Partition and non-replicated requests leave it zero.
1608timestampu64May be zero. Direct replies can echo it, but committed prepares use a server-assigned timestamp.
1688requestu64Request number, per client. See request numbering.
1761operationu8The Operation discriminant.
1777paddingbytesZero.
1848sessionu64Session 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).
1924user_idu32Ignored on the wire. The server stamps the authenticated user itself. Send zero.
1964command codeu32Concrete code for NonReplicated, zero otherwise.
2008partition_incarnationu64History identity captured with the request.
2088owner_generationu64Consumer group ownership generation, zero without a group.
2168minimum_metadata_opu64Minimum metadata progress needed to interpret the request.
22432reservedbytesZero 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:

ValueOperationPlane
1Registersession (login handshake, codes 40 and 45)
2NonReplicatedreads and ping. The u32 code rides bytes 196..200
3Logoutsession (code 39)
128CreateStreammetadata
130DeleteStreammetadata
132CreateTopicmetadata
134DeleteTopicmetadata
136CreatePartitionsmetadata
137DeletePartitionsmetadata
138DeleteSegmentsmetadata (resolved to an internal partition truncation)
139CreateConsumerGroupmetadata
140DeleteConsumerGroupmetadata
141CreateUsermetadata
143DeleteUsermetadata
144ChangePasswordmetadata
145UpdatePermissionsmetadata
146CreatePersonalAccessTokenmetadata
147DeletePersonalAccessTokenmetadata
148JoinConsumerGroupmetadata
149LeaveConsumerGroupmetadata
150UpdateResourcemetadata
160SendMessagespartition
161StoreConsumerOffsetpartition
162DeleteConsumerOffsetpartition

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.

OffsetSizeFieldTypeDescription
016checksumu128Zero on client-facing frames.
1616checksum_bodyu128Zero on client-facing frames.
3216clusteru128Cluster id.
484sizeu32Total frame length: 256 + body length.
524viewu32View associated with the reply. A cached committed reply retains its original view. Direct replies can echo the request value.
564releaseu32Zero.
601commandu88 (Reply).
611replicau8Replica index stamped by the reply builder. Cached committed replies retain the original primary index.
6266reservedbytesZero.
12816request_checksumu128Echoed from the request.
14416contextu128Server context.
16016clientu128Echoed client id.
1768opu64Committed log position on consensus replies. Direct replies can instead carry the session epoch or zero. This field alone does not prove a commit.
1848commitu64Commit position associated with the reply. A cached committed reply retains its original position.
1928timestampu64Server-assigned prepare timestamp on committed replies, or the request timestamp on direct replies.
2008requestu64Echoed request number. Non-replicated requests can reuse a number, so it is not a unique correlation id for concurrent reads.
2081operationu8Reply operation. Server rewrites can return 64 for CreateTopic, 65 for CreatePartitions, or 68 for DeleteSegments instead of the original client operation.
2097paddingbytesZero.
2164statusu320 = 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.
2201committed resultu8Exactly 1 marks a final committed result. Zero and unknown values provide no proof.
2213reservedbytesZero.
2248partition_incarnationu64Request or served partition incarnation. Poll body context carries the full served context.
23224reservedbytesZero.

Decode order for a client:

  1. Read 256 bytes, check command. 13 (Eviction) rejects the connection: map the reason and close that link. 8 (Reply) continues.
  2. Read the remaining size - 256 body bytes.
  3. If status is nonzero, this reply reports a pre-commit rejection. It does not settle an earlier uncertain attempt. The body is empty.
  4. 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.

OffsetSizeFieldTypeDescription
016checksumu128Zero on client-facing frames.
1616checksum_bodyu128Zero on client-facing frames.
3216clusteru128Cluster id.
484sizeu32Always 256: an eviction has no body.
524viewu32
564releaseu32Zero.
601commandu813 (Eviction).
611replicau8
6266reservedbytesZero.
12816clientu128The evicted client id.
1444server_protocol_versionu32Accepted protocol window (max), packed semver. Set only for reason 14, zero otherwise.
1484server_protocol_version_minu32Accepted protocol window (min). Set only for reason 14, zero otherwise.
152103reservedbytesZero.
2551reasonu8Eviction reason, see below.

Eviction reasons:

ValueReasonMeaning
1NoSessionNo session exists for this client id
2ClientReleaseTooLowClient release below cluster minimum
3ClientReleaseTooHighClient release above cluster maximum
4InvalidRequestOperationUnknown operation discriminant
5InvalidRequestBodyBody failed validation
6InvalidRequestBodySizeBody size mismatch
7SessionTooLowSession epoch below the cluster's retained minimum
8SessionReleaseMismatchSession bound to a different release
9InvalidCredentialsLogin refused: bad username or password
10InvalidTokenLogin refused: bad personal access token
11UserInactiveLogin refused: user inactive
12SessionErrorSession-level failure
13StaleClientMissed heartbeats. Server evicted the session
14IncompatibleProtocolClient protocol version outside the accepted window (see bytes 144..152)
15MalformedLoginLogin body without a decodable version prefix, or a legacy login code

Value 0 is reserved and never sent.

On this page