Module frame 

macula 12’s frames, as macula_frame and macula-go build and read them: the requests, replies, relay errors, publications and stream frames that carry signed objects, the control frames a pq_hybrid link neighbour-signs, the decoding rule’s payload bounds, and the length-prefixed wire codec.

A wire frame is <Length:4 bytes big-endian><Cbor>, the deterministic encoding of one map with version and frame_type. No frame carries a frame-level signature: what is signed is the signed object a frame holds, and, in pq_hybrid, a control frame’s neighbour signature.

Structs

NeighbourLink

Where a sender neighbour-signs a frame: the connection hash and the seq of this frame in the sender’s direction.

NeighbourPeer

What a receiver checks a frame against: the connection’s profile, the peer’s identity key as carried, the connection hash, and the seq it expects next from that peer.

PublicationSpec

A publication as its publisher gives it: a realm, a topic, the publisher’s own seq, when it was published in Unix milliseconds, a payload, and a ttl_ms, None for the 10 minutes a publication lives without one.

RelayErrorSpec

A station’s relay error as it gives it: for a pending verified request, a code from the closed set, the hop that failed, and a routing field outside the signature.

RequestSpec

A request as its caller gives it: sealed is the payload sealed end to end, carried in place of payload, which is then not sent, and None for a clear request; mode is a STREAM_OPEN’s and None for a CALL; token is None when the request carries none; proofs are the tokens of the delegation chain the token rests on, empty for none; source_route and retry_budget are routing fields outside the signature.

Sealed

A payload sealed end to end, as a frame carries it.

StreamState

What a verifier holds for one stream: the verified STREAM_OPEN and, for each side, the next seq and whether it has ended, and for the provider the key and signer its first frame carried. Each verification returns the next state, which replaces this one: a state has one owner.

VerifiedPublication

A publication that verified: its fields, the publisher’s key as carried, publication_hash, the SHA-384 of its tbs, which deduplication keys on, and expires_at, the last moment a verifier accepts it.

VerifiedRelayError

A relay error that verified for its request: the station that reported it, its code, and the hop that failed.

VerifiedReply

A provider’s RESULT or ERROR that verified for its request: the node that responded, a RESULT’s payload, and an ERROR’s code and detail; or, sealed end to end, sealed in their place.

VerifiedRequest

A CALL or STREAM_OPEN whose request verified: its fields, the caller’s key as carried, and request_hash, the SHA-384 of its tbs, which replies and stream frames name. A sealed request’s payload is in sealed, and its payload is null.

VerifiedStreamFrame

A stream frame that verified against its stream: its signer’s key id and its fields.

Enums

Decoded

What decoding the head of a buffer found.

FrameError

The refusals of a frame, named as macula_frame names them.

Liveness

Whether a liveness frame is the peer’s probe or its answer.

RelayErrorType

A relay error’s frame type.

ReplyType

A reply’s frame type.

RequestType

A request’s frame type.

StreamEncoding

How a STREAM_DATA’s body reads: raw bytes, or a structured value.

StreamFields

A stream frame’s own fields, each with its sender’s seq on the stream.

StreamMode

Who pushes data on a stream: the provider (ServerStream), the caller (ClientStream), or both (Bidi).

StreamRole

Which directions a STREAM_END closes: this side’s sending, or both.

Constants

FRAME_RESERVED_ELEMENTS

How many of the decoding rule’s items a payload leaves for the frame around it.

LIVENESS_NONCE_SIZE

The bytes of a liveness frame’s nonce.

MAX_FRAME_BYTES

The CBOR payload size cap: 16 MiB minus one byte, as macula’s.

MAX_PAYLOAD_ELEMENTS

How many CBOR items a payload may hold, itself included.

MAX_PAYLOAD_NESTING

How many lists and maps a payload may nest, the outermost counted: a payload travels inside a frame’s map, which takes one level.

MAX_PROOFS

The bound on a request’s proofs (D7, chain transport): eight tokens, 256 KiB in all, none repeated.

MAX_PROOFS_BYTES

PROTOCOL_VERSION

The version field every frame carries.

SEALED_SCHEME

The only scheme a sealed map may name.

Functions

advertise_frame

macula 12’s ADVERTISE: the signed procedure_advertisement record, as encoded bytes.

check_frame

Whether the whole frame is one the decoding rule accepts where it arrives, the check macula runs on every frame before it is sent.

check_payload

Whether payload is admissible as a frame payload. It also refuses a payload whose own encoding is over the frame cap.

claimed_reply_ids

The request_id and request_hash a received reply or relay error names, read without verifying it: a key for finding the pending request and nothing more. The frame’s fields and the signed object’s shape are checked as the verifiers check them, so ids of another length or shape never come back.

decode

Decodes one length-prefixed frame from the head of buf, under the decoding rule.

encode

Wraps frame as <Length:4 bytes big-endian><Cbor>, refusing one over the frame cap.

goodbye_frame

macula 12’s GOODBYE: a reason of at most 256 bytes, and a detail of at most 256 bytes of UTF-8, or none.

liveness_nonce

A liveness frame’s kind and nonce, or None for any other frame, or one whose nonce is not 16 bytes.

liveness_ping_frame

macula 13.2’s liveness_ping with a 16-byte nonce.

liveness_pong_frame

macula 13.2’s liveness_pong, answering the liveness_ping of the same nonce.

neighbour_signed

Whether profile neighbour-signs frames of frame_type: every control frame in pq_hybrid, none in pq_pure.

open_stream

The state a verifier starts a stream with: nothing seen from either side yet. open must be a verified STREAM_OPEN.

request_fields_accepted

Whether fields read as a CALL’s under the request table, where a delegation chain’s proofs are bounded: the reading the shared decoding rule vectors name request_fields.

sign_call

Signs a CALL with the caller’s identity key: caller is the key’s key id. Refused, in this order: a key that is not an identity key, a procedure over 512 bytes, a sealed payload of another shape than a request’s or a clear payload the wire cannot carry, a deadline or retry budget of 2^53 or more, or a stream mode, which a CALL does not carry; then proofs outside their bound.

sign_caller_stream

Signs a caller’s stream frame for a verified STREAM_OPEN with the caller’s identity key, whose key id must be the STREAM_OPEN’s caller. A caller sends no STREAM_REPLY, and no STREAM_DATA in a server_stream.

sign_neighbour

Neighbour-signs frame with the sender’s identity key, for one connection and one seq, when the key’s profile signs its type; otherwise frame goes as it is. A frame that already carries a neighbour signature is refused.

sign_provider_error

Signs a provider’s ERROR for a verified request, with sign_result’s key check: a code of at most 64 bytes and a detail of at most 256.

sign_provider_stream

Signs a provider’s stream frame for a verified STREAM_OPEN with the provider’s identity key, whose key id must be the STREAM_OPEN’s target. The first frame, seq 0, carries the key; the later ones leave it out.

sign_publish

Signs a publication as a PUBLISH with the publisher’s identity key. Refused, in macula’s order: a key that is not an identity key; a seq or published_at of 2^53 or more; a topic over 512 bytes; a payload the wire cannot carry; a ttl_ms over one hour.

sign_relay_error

Signs a station’s relay error with its identity key: reported_by is the key’s key id. Refused, in this order: a key that is not an identity key, a code outside the closed set.

sign_result

Signs a provider’s RESULT for a verified request: responded_by is the key’s key id, which must be the request’s target, and the payload one the wire carries. source_route_reverse rides outside the signature.

sign_sealed_provider_error

Signs a provider’s ERROR whose code and detail are sealed end to end, as cbor([code, detail]), carried in their place.

sign_sealed_result

Signs a provider’s RESULT whose payload is sealed end to end, carried in place of the payload, with sign_result’s key check.

sign_stream_open

Signs a STREAM_OPEN, which carries spec.mode, with sign_call’s checks, the last of them refusing no mode.

subscribe_frame

macula 12’s SUBSCRIBE of subscriber to topic in realm, with no options. A topic over 512 bytes or not UTF-8 is refused.

unadvertise_frame

macula 12’s UNADVERTISE: the signed withdrawal record, as encoded bytes.

unsubscribe_frame

macula 12’s UNSUBSCRIBE of subscriber from topic in realm, with subscribe_frame’s bound on the topic.

verify_caller_stream

Verifies a caller’s received stream frame against its stream’s state, with the STREAM_OPEN’s key, and returns the frame and the next state. A caller sends no STREAM_DATA in a server_stream.

verify_neighbour

Reads a received frame under the connection’s profile. A frame type the profile signs must be exactly {version, frame_type, neighbour}, signed by the peer’s identity key for this connection and this seq, and comes back as the frame its tbs holds. Any other frame must not carry neighbour and comes back as it is.

verify_provider_stream

Verifies a provider’s received stream frame against its stream’s state, and returns the frame and the stream’s next state. Before the provider’s first frame the state holds no provider key, so a frame without one is out of order. The first frame’s signer is the key id of the key it carries and the STREAM_OPEN’s target, with seq 0; later frames verify with that key, name that signer and carry no key.

verify_publication

Verifies the publication a received PUBLISH, EVENT or GOSSIP carries, under the connection’s profile and the verifier’s clock now_ms: the frame is exactly version, frame_type and publication, with an EVENT’s delivered_via or a GOSSIP’s round; then the publication’s signature and fields, a ttl_ms of at most an hour, publisher as the key id of its key, and its time.

verify_relay_error

Verifies a received relay error for the pending request it names, from the station the connection authenticated, expected_reporter.

verify_reply

Verifies a received RESULT or provider ERROR for the request it answers: the frame’s shape, the reply’s signature and fields, responded_by as the key id of its key, the request’s request_id and request_hash, and responded_by as the request’s target.

verify_request

Verifies a received CALL or STREAM_OPEN under the connection’s profile: the frame’s shape, the request’s signature and fields, and caller as the key id of its key. A station checks this before it routes, and a provider before its own checks, which stay with the caller: its node_id as target, the deadline window, replays and tokens.

verify_session_frame

A received frame on a v5 connection: one that carries a neighbour signature is FrameError::Malformed, and any other comes back as it is.