Module data_stream 

Draft-19 data stream header encoding and decoding.

Byte-for-byte identical to draft-18; only Object Property scope and the object-status payload rule changed semantically, not the wire layout.

The payload rule is worth spelling out, because it is the one place where a draft-19 encoder can refuse an object a draft-18 encoder would have reinterpreted. Draft-18 said every Object with a status other than Normal has an empty payload; draft-19 Section 11.2.1.1 says instead that an Object has an empty payload unless its status is registered as permitting one, and Section 15.9 puts that permission in the Object Status registry. Both encodings here keep their draft-18 framing — a subgroup object carries a status exactly when its Object Payload Length is zero, and a datagram carries one exactly when its type sets the STATUS bit, both stated that way by the draft — so no frame these decoders can read is able to state a status and a payload at once. The registry rule therefore bites where a caller can hold both: SubgroupObjectReader::write_object consults the status’s payload permission and refuses an object whose status forbids the payload handed with it, rather than dropping the status and writing the bytes as a Normal object. On the way back out, SubgroupObject and DatagramHeader answer the same question from the registry, so a reader never has to recover it from a length.

Subgroup header type byte: form 0b0XX1XXXX, so bit 4 is set and bit 7 is clear; the ranges are 0x10..0x1F, 0x30..0x3F, 0x50..0x5F, 0x70..0x7F.

• bit 0 (0x01): PROPERTIES
• bits 1-2 (0x06): SUBGROUP_ID_MODE (0=zero, 1=first_obj, 2=explicit, 3=reserved)
• bit 3 (0x08): END_OF_GROUP
• bit 5 (0x20): DEFAULT_PRIORITY (no priority byte)
• bit 6 (0x40): FIRST_OBJECT

Datagram type byte: 0b00X0XXXX, so bits 4, 6 and 7 are clear; the ranges are 0x00..0x0F and 0x20..0x2F.

• bit 0 (0x01): PROPERTIES
• bit 1 (0x02): END_OF_GROUP
• bit 2 (0x04): ZERO_OBJECT_ID (object_id=0, field omitted)
• bit 3 (0x08): DEFAULT_PRIORITY (no priority byte)
• bit 5 (0x20): STATUS (status byte replaces payload)

Neither range is fully assigned, and draft-19 spells out which values in them an endpoint must refuse rather than decode, closing the session with a PROTOCOL_VIOLATION. Section 11.4.2 excludes the subgroup Types whose SUBGROUP_ID_MODE is the reserved 0b11 — 0x16, 0x17, 0x1E, 0x1F and the same four offsets in each higher range — because that mode does not say whether a Subgroup ID field follows the Group ID, so a decoder would have to guess and a wrong guess shifts every later field by the width of that varint. Section 11.3.1 excludes the datagram Types setting both STATUS (0x20) and END_OF_GROUP (0x02) — 0x22, 0x23, 0x26, 0x27, 0x2A, 0x2B, 0x2E and 0x2F — because an object status message cannot signal end of group. SubgroupHeader::decode and DatagramHeader::decode refuse both lists, and SubgroupHeader::encode_checked and DatagramHeader::encode_checked refuse to write them.

Fetch header: stream type 0x05 + request_id. Draft-19 Section 11.4.4 replaced the fixed per-object layout earlier drafts used with a leading Serialization Flags varint that says which of the object’s fields are on the wire at all; FetchObjectHeader decodes and encodes one such object header.

Structs

DatagramHeader

FetchHeader

FetchObject

One frame from a FETCH stream with its delta-encoded fields resolved.

FetchObjectHeader

One Object on a draft-19 fetch stream, up to but not including its payload.

FetchObjectLayout 🔒

Which optional fields a Serialization Flags value puts on the wire.

FetchObjectReader

Resolves the delta-encoded fields of the frames on one FETCH stream.

FetchObjectWriter

Re-encodes resolved fetch frames onto one FETCH stream.

SubgroupHeader

SubgroupObject

One object within a draft-19 subgroup stream. Object IDs are delta-encoded; whether a per-object “properties” block (the draft-19 equivalent of extension headers) is present depends on the PROPERTIES bit on the enclosing SubgroupHeader. Use SubgroupObjectReader to encode/decode.

SubgroupObjectMeta

The framing of one draft-19 subgroup object, without its payload.

SubgroupObjectReader

Enums

FetchEndOfRange

What an End of Range indicator on a fetch stream asserts about the Locations it covers, from draft-19 Section 11.4.4.2.

GroupOrder

The order a FETCH response’s Groups arrive in, which decides how a Group ID Delta is applied.

Constants

DATAGRAM_DEFAULT_PRIORITY_BIT 🔒

DATAGRAM_END_OF_GROUP_BIT 🔒

DATAGRAM_FORM_FORBIDDEN_BITS 🔒

Bits 4, 6 and 7, which the datagram’s 0b00X0XXXX form leaves clear.

DATAGRAM_PROPERTIES_BIT 🔒

DATAGRAM_STATUS_BIT 🔒

DATAGRAM_ZERO_OBJECT_ID_BIT 🔒

FETCH_DATAGRAM_BIT 🔒

Table 9 flag: the Object’s Forwarding Preference is Datagram, so it has no Subgroup ID and the two low bits are to be ignored.

FETCH_END_OF_NON_EXISTENT_RANGE 🔒

Table 7: End of Non-Existent Range.

FETCH_END_OF_UNKNOWN_RANGE 🔒

Table 7: End of Unknown Range.

FETCH_FLAGS_MAX 🔒

The largest Serialization Flags value whose bits are flags. Draft-19 Section 11.4.4: “When less than 128, the bits represent flags”.

FETCH_GROUP_ID_DELTA_BIT 🔒

Table 9 flag: a Group ID Delta field is present.

FETCH_OBJECT_ID_DELTA_BIT 🔒

Table 9 flag: an Object ID Delta field is present.

FETCH_PRIORITY_BIT 🔒

Table 9 flag: a Publisher Priority field is present.

FETCH_PROPERTIES_BIT 🔒

Table 9 flag: a Properties field is present.

FETCH_STREAM_TYPE 🔒

FETCH_SUBGROUP_ID_EXPLICIT 🔒

Subgroup ID mode 0b11: an explicit Subgroup ID field is on the wire.

FETCH_SUBGROUP_ID_MODE_MASK 🔒

Serialization Flags bits 0-1, the Subgroup ID encoding (draft-19 Section 11.4.4.1, Table 8).

PADDING_DATAGRAM_TYPE

Datagram type for padding, draft-19 Section 11.5.2: “An endpoint MAY send a datagram with a type of 0x132B3E29 to send padding data. The datagram contains the type followed by zero or more bytes that MUST all be set to zero.”

PADDING_STREAM_TYPE

Unidirectional stream type for padding, draft-19 Section 11.5.1: “An endpoint MAY open a unidirectional stream with a stream type of 0x132B3E28 to send padding data. The stream begins with the stream type, followed by zero or more bytes that MUST all be set to zero.”

SETUP_STREAM_TYPE 🔒

The unidirectional stream Type draft-19 Section 10.3 gives the control stream.

SUBGROUP_BASE_BIT 🔒

SUBGROUP_DEFAULT_PRIORITY_BIT 🔒

SUBGROUP_END_OF_GROUP_BIT 🔒

SUBGROUP_FIRST_OBJECT_BIT 🔒

SUBGROUP_FORM_FORBIDDEN_BITS 🔒

Bit 7, which the subgroup header’s 0b0XX1XXXX form leaves clear.

SUBGROUP_ID_MODE_MASK 🔒

SUBGROUP_ID_MODE_RESERVED 🔒

The SUBGROUP_ID_MODE value draft-19 reserves, once the mask is applied and the field shifted down.

SUBGROUP_PROPERTIES_BIT 🔒

Functions

datagram_type_error 🔒

Which failure a leading datagram Type that is not one a reader wants is.

datagram_type_is_status_end_of_group 🔒

Whether raw sits inside the datagram form but sets STATUS and END_OF_GROUP together — the first of Section 11.3.1’s two lists.

datagram_type_is_valid 🔒

Whether raw is a datagram Type draft-19 admits.

decoded_status 🔒

Turn a wire Object Status code into an ObjectStatus, refusing one draft-19 does not assign.

skip 🔒

Advance buf past len bytes without copying them.

stream_type_error 🔒

Which failure a leading unidirectional stream Type that is not the one a reader wants is.

subgroup_type_is_reserved_mode 🔒

Whether raw sits inside the subgroup form but names the reserved SUBGROUP_ID_MODE — the second of Section 11.4.2’s two lists.

subgroup_type_is_valid 🔒

Whether raw is a subgroup Type draft-19 admits: inside the form, and not the reserved SUBGROUP_ID_MODE.

validate_datagram_type 🔒

Refuse a datagram Type value draft-19 Section 11.3.1 lists as invalid.

validate_subgroup_type 🔒

Refuse a subgroup header Type value draft-19 Section 11.4.2 lists as invalid.

wide_type_refusal 🔒

Refuse a Type field spelled in more than one byte, before anything narrows it to a byte.