Struct AnyFetchObjectReader 

pub struct AnyFetchObjectReader { /* private fields */ }

Stateful reader for the frames on a fetch data stream, for any enabled draft.

Fetch objects are self-describing on drafts 07-14 and this reader carries no state there. From draft-15 a Serialization Flags field decides which of an object’s Group ID, Subgroup ID, Object ID and Priority reach the wire at all, and every field it omits is the object before it on the stream — repeated, or stepped by one, or (from draft-18) counted from by a difference. This reader holds that running state, so the values it produces are absolute on every draft.

One reader belongs to one stream. Every draft counts “the prior Object” along a single stream, so sharing a reader between streams, or restarting one mid-stream, resolves later frames onto the wrong group, subgroup, ID or priority — usually without an error anywhere.

The reader is Clone specifically so callers can probe a partial buffer against a copy and commit only on success; see the module docs.

Frames that are not objects

Drafts 16-19 add End of Range indicators, which state that a run of Objects was not serialized. They arrive through the same calls as objects and are told apart by AnyFetchObject::end_of_range.

Implementations

impl AnyFetchObjectReader

pub fn new( header: &AnyFetchHeader, group_order: AnyFetchGroupOrder, ) -> Result<Self, CodecError>

Create a reader from the stream’s fetch header and the Group Order the fetch was opened with.

The order matters only on drafts 18 and 19, where an Object’s Group ID is a difference from the previous Object’s and the order decides its sign. Nothing on the data stream carries it — the FETCH settles it — and it is an argument rather than a default because a descending stream read as ascending does not fail: it decodes, under Group IDs walking the wrong way, and neither this crate nor the caller can tell afterwards. Both readings are legal streams.

AnyControlMessage::fetch_group_order answers it from the FETCH, including the case where the message names no GROUP_ORDER — draft-19 Section 10.2.8: “If omitted from FETCH, the receiver uses Ascending (0x1)”. On drafts 07-17 the argument is ignored.

Returns CodecError::UnsupportedDraft for drafts not compiled in.

pub fn draft(&self) -> DraftVersion

The draft this reader decodes.

pub fn read_object( &mut self, buf: &mut impl Buf, ) -> Result<AnyFetchObject, CodecError>

Decode the next fetch frame, including its payload.

Returns CodecError::UnexpectedEnd when buf holds only part of a frame; the reader’s state is unspecified after such an error, so callers that may be fed partial buffers must probe against a clone.

Returns CodecError::InvalidField on drafts 15-19 when a frame takes a field from an object before it that does not exist — the first frame of a stream doing so is a protocol violation on every one of those drafts — and when a resolved Group ID, Subgroup ID or Object ID would leave the 64-bit range.

pub fn read_object_frame( &mut self, buf: &mut impl Buf, ) -> Result<AnyFetchFrame, CodecError>

Decode the next fetch frame, keeping what re-encoding it later takes.

Advances buf and this reader exactly as read_object_meta does, and reports the same framing in AnyFetchFrame::meta. What it additionally keeps is the shape the frame arrived in, which is the whole of what AnyFetchObjectWriter::reemit_object needs to write the frame back out against a different predecessor.

Costs nothing over read_object_meta, which is itself defined over this: the per-draft header it keeps is one the decode produced and dropped.

pub fn read_object_meta( &mut self, buf: &mut impl Buf, ) -> Result<AnyFetchObjectMeta, CodecError>

Decode the next fetch frame’s framing without copying its payload.

Advances buf past the whole frame exactly as read_object does, and advances the same reader state, so the two are interchangeable on one stream.

Trait Implementations

impl Clone for AnyFetchObjectReader

fn clone(&self) -> AnyFetchObjectReader

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AnyFetchObjectReader

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.