Module data_stream 

Draft-17 data stream header encoding and decoding.

Subgroup header type byte: 0b00X1XXXX (bit 4 always set)

• 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)

Datagram type byte: 0b00X0XXXX (bit 4 always 0)

• 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 populated. Draft-17 Sections 10.4.2 and 10.3.1 each close with a list of type values an endpoint “MUST close the session with a PROTOCOL_VIOLATION” on receiving, and the two figures spell the surviving values out: 0x10..0x15 / 0x18..0x1D / 0x30..0x35 / 0x38..0x3D for a subgroup header, 0x00..0x0F / 0x20..0x21 / 0x24..0x25 / 0x28..0x29 / 0x2C..0x2D for a datagram. Both decoders refuse everything else, so a header this module hands back always describes a framing the draft defines.

Fetch header: stream type 0x05 + request_id, followed by objects whose fields are named by a Serialization Flags varint rather than all being present — see FetchObjectHeader.

Structs

DatagramHeader

FetchHeader

FetchObject

One frame from a FETCH stream with the fields its Serialization Flags left off the wire filled in from the frames before it.

FetchObjectHeader

One object on a draft-17 fetch stream, without its payload.

FetchObjectReader

Resolves the elided 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-17 subgroup stream. Object IDs are delta-encoded and the presence of a “properties” block (the draft-17 equivalent of extension headers) is determined by the PROPERTIES bit on the enclosing SubgroupHeader. Use SubgroupObjectReader to encode/decode.

SubgroupObjectMeta

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

SubgroupObjectReader

Enums

EndOfRange

The two Serialization Flags values that mark a range of Objects rather than carrying one, from draft-17 Section 10.4.4 Table 6 and Section 10.4.4.2.

PayloadPermission

Whether an object carrying a given status is allowed a non-empty payload.

Constants

DATAGRAM_DEFAULT_PRIORITY_BIT 🔒

DATAGRAM_END_OF_GROUP_BIT 🔒

DATAGRAM_FORM_MASK 🔒

The bits a datagram type must fix: 7, 6 and 4 all clear. That is the form 0b00X0XXXX written as a mask, leaving bit 5 and the low nibble free.

DATAGRAM_PROPERTIES_BIT 🔒

DATAGRAM_STATUS_BIT 🔒

DATAGRAM_ZERO_OBJECT_ID_BIT 🔒

FETCH_DATAGRAM_BIT 🔒

The object was forwarded as a datagram and has no Subgroup ID; the two least significant bits are to be ignored.

FETCH_END_OF_NON_EXISTENT_RANGE 🔒

Serialization Flags 0x8C, End of Non-Existent Range.

FETCH_END_OF_UNKNOWN_RANGE 🔒

Serialization Flags 0x10C, End of Unknown Range.

FETCH_FLAGS_BIT_FORM_MAX 🔒

The largest Serialization Flags value read as a set of bits. Draft-17 Section 10.4.4: “When less than 128, the bits represent flags described below.”

FETCH_GROUP_ID_BIT 🔒

Group ID field present; clear means the prior object’s Group ID.

FETCH_OBJECT_ID_BIT 🔒

Object ID field present; clear means the prior object’s ID plus one.

FETCH_PRIORITY_BIT 🔒

Priority field present; clear means the prior object’s priority.

FETCH_PROPERTIES_BIT 🔒

Properties field present.

FETCH_STREAM_TYPE 🔒

FETCH_SUBGROUP_MODE_EXPLICIT 🔒

SUBGROUP mode 0x03: an explicit Subgroup ID field is present.

FETCH_SUBGROUP_MODE_MASK 🔒

SUBGROUP mode, the two least significant Serialization Flags bits (draft-17 Section 10.4.4.1, Table 7).

FETCH_SUBGROUP_MODE_PRIOR 🔒

SUBGROUP mode 0x01: the Subgroup ID is the prior object’s. Mode 0x00, the remaining value, fixes the Subgroup ID at zero and needs no constant — nothing tests for it.

FETCH_SUBGROUP_MODE_PRIOR_PLUS_ONE 🔒

SUBGROUP mode 0x02: the Subgroup ID is the prior object’s plus one.

SETUP_STREAM_TYPE 🔒

The unidirectional stream Type draft-17 Section 9.4 gives the control stream.

SUBGROUP_BASE_BIT 🔒

SUBGROUP_DEFAULT_PRIORITY_BIT 🔒

SUBGROUP_END_OF_GROUP_BIT 🔒

SUBGROUP_FORM_MASK 🔒

The bits a subgroup header type must fix: 7 and 6 clear, 4 set. That is the form 0b00X1XXXX written as a mask, leaving bit 5 and the low nibble free.

SUBGROUP_ID_MODE_MASK 🔒

SUBGROUP_ID_MODE_RESERVED 🔒

SUBGROUP_ID_MODE 0b11, the value draft-17 reserves.

SUBGROUP_PROPERTIES_BIT 🔒

Functions

datagram_type_error 🔒

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

datagram_type_is_valid 🔒

Whether datagram_type is one of the datagram types draft-17 defines.

decoded_status 🔒

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

fetch_flags_are_defined 🔒

Whether draft-17 defines this Serialization Flags value.

fetch_has_group_id 🔒

fetch_has_object_id 🔒

fetch_has_priority 🔒

fetch_has_properties 🔒

fetch_has_subgroup_id 🔒

Whether an explicit Subgroup ID field follows the Group ID.

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 first of the two lists quoted above.

subgroup_type_is_valid 🔒

Whether header_type is one of the subgroup header types draft-17 defines.

wide_type_refusal 🔒

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