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.

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

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.”