Module control_codec 

Codec for transport-level control frames.

Encodes/decodes TransportResponse and ChallengeResponse. Tag constants are public so every program that reads or writes frames — the node, the client library, a gateway on its own I/O loop — shares one source of truth for the wire values.

Every frame, in either direction, is [length: u32 LE][tag: u8][body]. The tag is the protocol’s alone: TAG_APP marks a frame whose body belongs to the application, and every other tag is one of the protocol’s own frames. The protocol never reads an application body, and an application never sees the tag, so an application body may start with any byte.

A request (TAG_REQUEST) and every frame that ends a request’s reply (the batch terminators, ServerBusy, Refused) carry the request’s RequestId straight after the tag, as eight little-endian bytes: the client chose it, and the node echoes it on the one final frame it sends for that request.

Structs

Refused

A Refused frame’s fields: the request’s ID, the kind, and the reason, borrowed from the payload. See decode_refused.

Enums

BadChallenge

Why a node’s first frame is not a challenge this build can answer.

BadRefusal

Why a payload under TAG_REFUSED is not a Refused frame.

Constants

BATCH_END_FRAME_LEN

The frame of a batch terminator (TAG_BATCH_END or TAG_BATCH_END_DEGRADED), length prefix included: what a response stage pre-encodes and writes a request’s ID into (write_terminal_id) before it appends the terminator.

CHALLENGE_LEN

A challenge’s payload (after the length prefix): [tag][version: u16 LE][nonce: 32].

CHALLENGE_NONCE_LEN

Bytes of the challenge’s nonce.

CHALLENGE_RESPONSE_LEN

Wire size of a challenge-response frame payload: tag(1) + signature(64) + public_key(32).

CHALLENGE_V0_LEN

A protocol-0 challenge’s payload, from a node of a release before client protocol versions: [tag][nonce: 32], no version.

CLIENT_PROTOCOL_VERSION

The client protocol this build speaks, carried in the node’s auth challenge. Protocol 0 is every release before request IDs (a challenge with no version in it). It changes once per release that changes the client wire, not once per commit. A client refuses any version other than its own, before it signs anything.

MAX_CONTROL_FRAME_LEN

The widest frame encode_transport_response writes, length prefix included: a Refused with the longest reason.

REQUEST_ID_LEN

Length of a request ID on the wire: a u64, little-endian, straight after the tag of a request and of every frame that ends its reply.

RETIRED_TAGS

Tags that frames used to carry and no frame carries any more. Never reused, so a peer still speaking an older protocol cannot have one of its frames read as a different one. 0x03 was EngineError, a frame no node ever sent.

TAG_APP

An application frame: the body is the application’s response, opaque to the protocol. A request travels under TAG_REQUEST instead.

TAG_AUTH_FAILED

TAG_BATCH_END

The end of a request’s reply, backed as the ack policy in force requires: [tag][id: u64 LE].

TAG_BATCH_END_DEGRADED

The end of a request’s reply that only the primary’s own disk backs: sent by a node halted for want of a replica, for a request it had already sequenced, once its own journal holds it. Weaker than the ack policy in force, and marked so; see TransportResponse::BatchEndDegraded. [tag][id: u64 LE].

TAG_CHALLENGE

TAG_CHALLENGE_RESPONSE

TAG_LEN

Length of the tag that follows every frame’s length prefix, in either direction.

TAG_REFUSED

The application’s decoder refused request id: [tag][id: u64 LE][kind: u8][len: u8][reason: len bytes, UTF-8].

TAG_REQUEST

A client’s request: [tag][id: u64 LE][body], the body the application’s.

TAG_RESPONSE_HEARTBEAT

TAG_SERVER_BUSY

Request id was shed at ingress, not applied: [tag][id: u64 LE].

TAG_SERVER_READY

Functions

decode_challenge

The nonce of a node’s challenge payload (after the length prefix), if the node speaks CLIENT_PROTOCOL_VERSION. The one parser of the challenge’s layout, for a client’s handshake and for tests that read a node’s challenge by hand.

decode_challenge_response

Decode a client’s auth challenge-response from a wire frame.

decode_refused

Decode a Refused frame’s payload (after the length prefix, tag included), checking its length exactly: the reason’s declared length must be what follows it, and it must be UTF-8. The inverse of encode_transport_response for that frame, kept beside it so its layout has one home. A payload whose tag is not TAG_REFUSED is the caller’s to rule out; this reads past the tag without looking at it.

encode_challenge_response

Encode a client’s auth challenge-response into buf, as the frame payload without the 4-byte length prefix: [tag:u8][signature:64][pubkey:32].

encode_transport_response

Encode a transport-level response into buf.

terminal_request_id

The ID a reply frame’s payload (after the length prefix) names, if it is a frame that ends a request’s reply: BatchEnd, BatchEndDegraded, ServerBusy or Refused. None for any other tag, and for a payload too short to hold the ID. Reads only the tag and the ID, so the head of a frame is enough.

write_terminal_id

Write id into a terminator frame pre-encoded by encode_transport_response (BatchEnd or BatchEndDegraded, any ID): the one place the ID’s offset in such a frame is written, so a response stage’s template and the encoder cannot drift apart.