Enum AnySubgroupHeader

Source

pub enum AnySubgroupHeader {
Show 13 variants
    Draft07(SubgroupHeader),
    Draft08(SubgroupHeader),
    Draft09(SubgroupHeader),
    Draft10(SubgroupHeader),
    Draft11(SubgroupHeader),
    Draft12(SubgroupHeader),
    Draft13(SubgroupHeader),
    Draft14(SubgroupHeader),
    Draft15(SubgroupHeader),
    Draft16(SubgroupHeader),
    Draft17(SubgroupHeader),
    Draft18(SubgroupHeader),
    Draft19(SubgroupHeader),
}

Expand description

A subgroup header from any enabled draft.

Variants§

§

Implementations§

Source §

impl AnySubgroupHeader

Source

pub fn decode( version: DraftVersion, buf: &mut impl Buf, ) -> Result<Self, CodecError>

Decode from wire using the specified draft version.

Source

pub fn encode(&self, buf: &mut impl BufMut)

Encode to wire using the appropriate draft’s format.

Source

pub fn draft(&self) -> DraftVersion

Returns the draft version this value belongs to.

Source §

impl AnySubgroupHeader

Source

pub fn decode_stream( version: DraftVersion, buf: &mut impl Buf, ) -> Result<Self, CodecError>

Decode a subgroup stream header including its leading stream-type field, for any enabled draft.

Drafts 07-13 encode the stream type as a varint ahead of the header body; drafts 14-19 fold it into the header itself. This entry point hides that difference: callers hand it the stream’s first byte onwards and it consumes exactly the header, type field included.

On drafts 11-13 the stream type also selects the header layout and fixes whether objects carry extension headers, which Self::decode cannot know; prefer this entry point whenever the stream’s first byte is available.

Source

pub fn encode_stream(&self, buf: &mut impl BufMut)

Encode a subgroup stream header including its leading stream-type field, the inverse of Self::decode_stream.

Self::encode is not that inverse on drafts 07-13 and never was: it writes the header body alone, so bytes written with it and read back with Self::decode_stream lose their first field and shift every field after it. Use this for a stream’s first write and Self::encode only once the stream is already open.

Source

pub fn encode_stream_checked( &self, buf: &mut impl BufMut, ) -> Result<(), CodecError>

Encode the header body, refusing a value the stream type will not carry, and write the type field in front of it.

The checked form of Self::encode_stream. Every draft from 11 on has a header type table with a column the value can disagree with - a Subgroup ID the type does not write, an Option that does not match what the type says is present - and disagreeing does not produce a malformed stream. It produces a well-formed stream for a different subgroup, or with a different priority, which the peer has no way to question. Each draft’s own encode_checked says no to that; this is the one entry point that reaches all of them.

Drafts 07 through 10 have nothing to refuse: their SUBGROUP_HEADER has one shape, every field is written every time, and no type byte selects between them. They are written unchanged.

§Errors

CodecError::InvalidField if the header’s fields disagree with its own type. A refused header leaves buf untouched.

Source

pub fn track_alias(&self) -> u64

The Track Alias every object on this stream belongs to.

Source

pub fn group_id(&self) -> u64

The Group ID every object on this stream belongs to.

Source

pub fn publisher_priority(&self) -> Option<u8>

The Publisher Priority, or None when the header set a default-priority flag and omitted the field (drafts 15+).

Source

pub fn subgroup_id(&self) -> Option<u64>

The Subgroup ID this header fixes for its objects, or None when the header does not determine one.

None covers two cases. The first is the subgroup ID is the first object’s ID stream, which every draft from 11 on defines and this codec never resolves — nine of the thirteen, not the eight this said, and the miscount is worth naming because draft-15 spent a long time excluded from lists elsewhere on exactly that reading. The second is a header whose type the draft does not assign at all: drafts 17-19 mode 3, and the same fourth combination of the 0x06 bits on drafts 15 and 16. In every one of them the codec stores a placeholder zero that a caller must not report.

Imposes draft-14’s !has_subgroup_id_field() guard uniformly. Every per-draft accessor it reaches through now reads the Subgroup ID carrier the way that draft’s own decoder does, so there is no longer a disagreement here for this accessor to paper over. Draft-16 used to read its two mode bits one at a time and so reported a first-object carrier for a Type whose mode is reserved, which made reaching for its per-draft accessor directly a way to resolve such a header to the wrong subgroup.

Source

pub fn subgroup_id_mode(&self) -> Option<u8>

The two-bit subgroup-ID mode, on the five drafts that put one in the header type, or None on the eight that do not.

0 = the header carries no subgroup ID and it is zero; 1 = the subgroup ID is the first object’s ID; 2 = an explicit ID follows; 3 = the fourth combination, which no draft assigns.

Exists because on those five drafts Self::subgroup_id returns None for both mode 1 and mode 3 — the decoder stores a placeholder zero for each — and the two mean different things to a caller deciding whether an object may be elided. Without it, eliding index 0 of a reserved-mode stream is indistinguishable from eliding it on a stream whose subgroup ID the first object defines.

Reported wherever that ambiguity exists, and that is what picks the five. Drafts 16 through 19 name a SUBGROUP_ID_MODE field; draft-15 does not, and spells the same three carriers out as a Subgroup ID Field Present column beside a Subgroup ID Value one, reaching the fourth combination by leaving it out of the table rather than by reserving it. That is a difference in wording and not in bytes — same mask, same shift, same four values — so the question this accessor asks has one answer on both. It is named for the question and not for any draft’s field, as Self::carries_extension_block is, and answering it here adds nothing to draft15, which goes on describing its own bits in its own words.

None on drafts 07 through 14 means the ambiguity is absent, not the carrier. Drafts 07-10 always put the subgroup ID on the wire. Drafts 11 through 14 give each carrier a stream type of its own and assign every type they define, so Self::subgroup_id answers None for the first-object carrier and for nothing else, and there is no second reading for a mode to resolve.

Source

pub fn carries_extension_block(&self) -> bool

Whether every object on this stream writes a length-prefixed extension block — the field drafts 17-19 renamed Properties.

A property of the stream, not of any object on it. The header’s type settles it once, and an object with nothing to put in the block still writes a length of zero on a stream that carries one. So a writer cannot work the answer out from the object in its hand, and one that guesses puts a stream on the wire that no reader can follow: the missing length is read out of the next field along, and every object after it is misframed.

Answered false on draft-07, which has no such block at all, and true on drafts 08 through 10, where every object carries one and no header type can say otherwise. From draft-11 on it is the header’s own answer.

Exists because nothing else exposed it. subgroup_id and publisher_priority report what the header holds; this reports what the objects after it must write, and only the first kind was reachable without matching on the concrete per-draft variant.