Module data_stream 

Draft-16 data stream header encoding and decoding.

Draft-16 subgroup type-byte flag layout:

• & 0x01: extensions present on objects
• & 0x06: SUBGROUP_ID_MODE. Section 10.4.2: “The SUBGROUP_ID_MODE field (bits 1-2, mask 0x06) is a two-bit field that determines the encoding of the Subgroup ID. To extract this value, perform a bitwise AND with mask 0x06 and right-shift by 1 bit”. Mode 0 puts no Subgroup ID on the wire and it is zero, mode 1 takes it from the first object, mode 2 reads it as a field after the Group ID, and mode 3 is reserved
• & 0x08: end-of-group marker
• & 0x20: no publisher_priority (0x30+ types)

Because the mode is one field and not two independent bits, the three carriers are mutually exclusive: a Type setting both 0x02 and 0x04 names the reserved mode, not two carriers at once. This module described those bits separately and read them separately, which let a single Type answer to two carriers.

Draft-15 spells the same three carriers out of the same two bits, as a pair of table columns rather than a named field, and the two drafts end up admitting the same twenty-four Types — draft-16 by excluding the reserved mode from the ranges 0x10-0x1F and 0x30-0x3F, draft-15 by listing them.

Draft-16 datagram type-byte flag layout:

• 0x01: extensions present (byte-length-prefixed blob)
• 0x02: end-of-group
• 0x04: no object_id (object_id = 0 implied)
• 0x08: default priority (priority omitted, inherited)
• 0x20: status datagram (carries object_status instead of payload)

Draft-16 fetch objects are framed differently again: a per-object Serialization Flags varint decides which of Group ID, Subgroup ID, Object ID, Priority and Extensions are on the wire, and a field left off is taken from the object before it. See FetchObjectHeader for the flag layout and FetchObjectReader for the inheritance. A fetch object carries no Object Status at all — draft-16 Section 10.2.1.1 puts that field on subscription deliveries only.

Extension headers in draft-16 are byte-length-prefixed opaque blobs (not count-prefixed as in draft-14).

Structs

DatagramHeader

FetchHeader

FetchObjectHeader

One Object as it is framed on a draft-16 fetch stream, before any field is resolved against the Object before it.

FetchObjectLocation

One fetch object’s Location and priority, with every field the flags left off the wire filled in from the Object before it.

FetchObjectReader

Stateful resolver for the Objects on one draft-16 fetch stream.

FetchObjectWriter

Re-encodes resolved fetch Objects onto one FETCH stream.

SubgroupHeader

SubgroupObject

One object within a draft-16 subgroup stream with its Object ID already resolved from the delta encoding. See SubgroupObjectReader for stateful encode/decode.

SubgroupObjectMeta

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

SubgroupObjectReader

Stateful reader/writer for draft-16 subgroup objects. Mirrors the draft-15 semantics (delta-encoded object IDs and header-typed extension presence).

Enums

FetchEndOfRange

The two Serialization Flags values draft-16 gives a meaning of their own instead of reading as a bit field, from Section 10.4.4 Table 4.

FetchSubgroupMode

How an Object on a draft-16 fetch stream states its Subgroup ID.

PayloadPermission

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

Constants

DATAGRAM_END_OF_GROUP_BIT 🔒

The END_OF_GROUP bit of a datagram Type.

DATAGRAM_FORM_FORBIDDEN_BITS 🔒

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

DATAGRAM_STATUS_BIT 🔒

The STATUS bit of a datagram Type.

FETCH_STREAM_TYPE 🔒

The unidirectional stream Type draft-16 Section 10.4.4 gives a fetch stream.

SUBGROUP_BASE_BIT 🔒

Bit 4, which every subgroup header Type sets.

SUBGROUP_FORM_FORBIDDEN_BITS 🔒

Bits 6 and 7, which the subgroup header’s 0b00X1XXXX form leaves clear.

SUBGROUP_ID_MODE_MASK 🔒

Bits 1-2, the SUBGROUP_ID_MODE field.

SUBGROUP_ID_MODE_RESERVED 🔒

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

Functions

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 10.3.1’s two lists.

datagram_type_is_valid 🔒

Whether raw is a datagram Type draft-16 admits.

datagram_type_refusal 🔒

The refusal a datagram Type deserves, as a plain function so wide_type_refusal can take it.

decoded_status 🔒

Turn a wire Object Status code into the status draft-16 gives it, refusing any code the draft does not assign.

extensions_permitted_at 🔒

Whether an Object at status is allowed to carry extensions_len bytes of extension headers.

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 Section 10.4.2’s two lists.

subgroup_type_is_valid 🔒

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

validate_datagram_type 🔒

Refuse a datagram Type value draft-16 Section 10.3.1 lists as invalid.

validate_subgroup_type 🔒

Refuse a subgroup header Type value draft-16 Section 10.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.