Struct ObjectHeader

Source

pub struct ObjectHeader {
    pub object_id: VarInt,
    pub extension_headers_length: VarInt,
    pub extensions: Vec<u8>,
    pub payload_length: VarInt,
    pub object_status: ObjectStatus,
}

Expand description

Object within a subgroup stream (draft-11).

Fields§

§object_id: VarInt

Object identifier within the subgroup.

§extension_headers_length: VarInt

Total byte length of extension headers (0 if no extensions).

§extensions: Vec<u8>

Raw extension bytes (opaque).

§payload_length: VarInt

Length of the object payload in bytes.

§object_status: ObjectStatus

Object status (Normal unless payload_length == 0).

Implementations§

Source §

impl ObjectHeader

Source

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

Encode the object header in the framing that carries no extension block.

Lossy, and lossy in a way the caller cannot see: an object holding extension headers is written without them and without a word. Which framing is correct is not a property of the object at all - Section 9.4.2 gives the stream’s type an Extensions Present column, and every object on the stream follows it - so this entry point can only guess, and it guesses “absent”. Prefer Self::encode_with_extensions, which is told, or Self::encode_checked, which refuses what it would otherwise drop.

Source

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

Encode the header, refusing a status the framing cannot carry.

Section 9.4.2 puts the Object Status field on the wire only when the Object Payload Length is zero, and Section 9.1.1.1 says “Any object with a status code other than zero MUST have an empty payload”. A non-zero status paired with a non-zero payload length therefore has no encoding at all: Self::encode drops the status and the peer reads an ordinary object, which is a different object from the one the caller described. This refuses instead.

The datagram types on this draft already refuse the same pairing. These two did not, and they are the ones a publisher writes on every stream.

Extension headers are refused here rather than dropped, for a reason the status rule does not share: this entry point writes the framing that has no Extension Headers Length field, so the bytes have nowhere to go. Writing them anyway is not an option and losing them silently puts a stream on the wire that no reader can follow - a reader on an extensions-bearing stream takes the Object Payload Length as the extension length and every object after it is misread. A caller that knows the stream’s framing wants Self::encode_checked_with_extensions.

§Errors

CodecError::InvalidField if a non-zero Object Status is paired with a non-zero Object Payload Length, or if the object carries extension headers this framing cannot write.

Source

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

Encode the object header into a stream whose type has already settled whether objects carry an extension block, refusing what that framing cannot express.

has_extensions is the stream’s answer, not the object’s: Section 9.4.2 fixes it for the whole stream from the SUBGROUP_HEADER type, so an object with no extensions on a stream that carries them still writes a length of zero, and that is the one direction not refused here. The other direction has no encoding, so it is refused.

§Errors

CodecError::InvalidField if a non-zero Object Status is paired with a non-zero Object Payload Length, or if has_extensions is false while the object carries extension headers.

Source

pub fn encode_with_extensions( &self, has_extensions: bool, buf: &mut impl BufMut, )

Encode the object header, writing the extension block only when the stream’s type says objects carry one.

Infallible, and so unable to say that a false here discards the extension headers the object holds. Self::encode_checked_with_extensions is the same write with that refusal in front of it.

Source