Module data_stream 

Draft-18 data stream header encoding and decoding.

Subgroup header type byte, draft-18 Section 11.4.2: the form is 0b0XX1XXXX, so bit 7 is clear and bit 4 is set, giving the ranges 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 (new in draft-18)

Datagram type byte, draft-18 Section 11.3.1: the form is 0b00X0XXXX, so bits 7, 6 and 4 are clear, giving the ranges 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)

Both sections then list the Type values inside those ranges that are nonetheless invalid, and answer each with “MUST close the session with a PROTOCOL_VIOLATION”: SUBGROUP_ID_MODE 0b11 on a stream header, and STATUS together with END_OF_GROUP on a datagram. Both decoders refuse them, and so do SubgroupHeader::encode_checked and DatagramHeader::encode_checked, which write only what those decoders accept.

Fetch header: stream type 0x05 + request_id, then objects whose fields are selected by a Serialization Flags varint and resolved against the object before them (Section 11.4.4). FetchObjectHeader is the wire frame and FetchObjectReader resolves it.

Padding, Section 11.5, is a stream type and a datagram type of its own — PADDING_STREAM_TYPE and PADDING_DATAGRAM_TYPE — carrying no Objects. Neither is a subgroup header or a datagram header, and this module’s decoders refuse both rather than reading a padding frame’s leading bytes as header fields.

Structs

DatagramHeader

FetchHeader

FetchObject

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

FetchObjectHeader

One frame on a draft-18 FETCH stream, exactly as it sits 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-18 subgroup stream. Object IDs are delta-encoded; whether a per-object “properties” block (the draft-18 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-18 subgroup object, without its payload.

SubgroupObjectReader

Enums

EndOfRange

Which End of Range a fetch frame marks, draft-18 Section 11.4.4.2.

GroupOrder

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

PayloadPermission

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

Constants

DATAGRAM_DEFAULT_PRIORITY_BIT 🔒

DATAGRAM_END_OF_GROUP_BIT 🔒

DATAGRAM_FORM_MASK 🔒

The bits the datagram form 0b00X0XXXX fixes to zero: bits 7, 6 and 4.

DATAGRAM_PROPERTIES_BIT 🔒

DATAGRAM_STATUS_BIT 🔒

DATAGRAM_ZERO_OBJECT_ID_BIT 🔒

FETCH_DATAGRAM_BIT 🔒

Bit 0x40: the Object’s forwarding preference is Datagram, so it has no Subgroup ID and bits 0-1 are to be ignored.

FETCH_END_OF_NON_EXISTENT_RANGE 🔒

Serialization Flags value 0x8C: End of Non-Existent Range.

FETCH_END_OF_UNKNOWN_RANGE 🔒

Serialization Flags value 0x10C: End of Unknown Range.

FETCH_FLAGS_MAX 🔒

The largest Serialization Flags value that is a set of flags. Draft-18 Section 11.4.4: “When less than 128, the bits represent flags described below.”

FETCH_GROUP_ID_DELTA_BIT 🔒

Bit 0x08: the Group ID Delta field is present.

FETCH_OBJECT_ID_DELTA_BIT 🔒

Bit 0x04: the Object ID Delta field is present.

FETCH_PRIORITY_BIT 🔒

Bit 0x10: the Publisher Priority field is present.

FETCH_PROPERTIES_BIT 🔒

Bit 0x20: the Properties field is present.

FETCH_STREAM_TYPE 🔒

FETCH_SUBGROUP_MODE_MASK 🔒

Serialization Flags bits 0-1 (mask 0x03): how the Subgroup ID is encoded.

FETCH_SUBGROUP_MODE_PRESENT 🔒

Mode 0x03: the Subgroup ID field is present.

FETCH_SUBGROUP_MODE_PRIOR 🔒

Mode 0x01: the Subgroup ID is the prior Object’s.

FETCH_SUBGROUP_MODE_PRIOR_PLUS_ONE 🔒

Mode 0x02: the Subgroup ID is the prior Object’s plus one.

FETCH_SUBGROUP_MODE_ZERO 🔒

Mode 0x00: the Subgroup ID is zero.

PADDING_DATAGRAM_TYPE

Datagram type for padding, draft-18 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-18 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-18 Section 10.3 gives the control stream.

STATUS_AND_END_OF_GROUP 🔒

Both bits of the combination Section 11.3.1 forbids.

SUBGROUP_BASE_BIT 🔒

SUBGROUP_DEFAULT_PRIORITY_BIT 🔒

SUBGROUP_END_OF_GROUP_BIT 🔒

SUBGROUP_FIRST_OBJECT_BIT 🔒

SUBGROUP_FORM_MASK 🔒

The bits the subgroup header form 0b0XX1XXXX fixes: bit 7 and bit 4.

SUBGROUP_FORM_VALUE 🔒

The values the form fixes them to: bit 7 clear, bit 4 set.

SUBGROUP_ID_MODE_MASK 🔒

SUBGROUP_ID_MODE_RESERVED 🔒

The SUBGROUP_ID_MODE value draft-18 reserves for future use.

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

datagram_type_is_valid 🔒

Whether datagram_type is a Type value draft-18 Section 11.3.1 allows on a datagram.

decoded_status 🔒

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

payload_permission_of 🔒

The payload permission draft-18 Section 11.2.1.1 gives status.

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

subgroup_type_is_valid 🔒

Whether header_type is a Type value draft-18 Section 11.4.2 allows on a subgroup stream.

wide_type_refusal 🔒

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