Skip to main content

DecodeContext

Struct DecodeContext 

Source
pub struct DecodeContext<'a> { /* private fields */ }
Expand description

Per-decode limits threaded through every merge call.

Carries the remaining recursion depth and a shared unknown-field allowance. The context is Copy — passing it to a callee hands over the current depth by value, while the unknown-field allowance lives in a Cell owned by the top-level decode entry point, so every field decoded under one entry point draws from the same allowance.

It also records where the message being decoded ends in the buffer the context is passed with. The default Message::merge_to_limit (and so Message::merge) records it; Message::merge_length_delimited, map entries and decode_string_to_ctx / decode_bytes_to_ctx reject a declared length that runs past it, before decoding what it covers. DecodeContext::new records no end, so the whole buffer is allowed.

Because the end belongs to one buffer, hand-written code that decodes a different buffer with a context it was given (a copy of the message, a decompressed payload) must record that buffer’s end first, with with_message_end — 0 when the message runs to the end of that buffer — or start it with the default implementations of Message::merge or Message::merge_to_limit, which do so. Otherwise a valid nested field near the end of that buffer can be rejected with DecodeError::UnexpectedEof.

Constructed automatically by the Message convenience methods (decode, decode_from_slice, merge_from_slice) and by DecodeOptions. Construct one manually only when calling Message::merge or the other depth-threading methods directly — and construct a fresh limit cell per top-level decode. Reusing one cell across decode calls makes the limit cumulative: each call drains it further until every decode fails with DecodeError::UnknownFieldLimitExceeded.

use core::cell::Cell;
use buffa::{DecodeContext, Message, DEFAULT_UNKNOWN_FIELD_LIMIT, RECURSION_LIMIT};

let limit = Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
let mut msg = Person::default();
msg.merge(&mut bytes, DecodeContext::new(RECURSION_LIMIT, &limit))?;

Implementations§

Source§

impl<'a> DecodeContext<'a>

Source

pub fn new(depth: u32, unknown_field_limit: &'a Cell<usize>) -> Self

Create a context with depth remaining recursion levels and the remaining unknown-field allowance stored in unknown_field_limit.

Source

pub fn with_message_end(self, message_end: usize) -> Self

Record that the message being decoded ends when the buffer this context is passed with has message_end bytes left, so a field, sub-message or map entry of it that would reach further is rejected.

message_end is a count of the bytes that follow the message, the value buf.remaining() will have when the message ends: the same limit that Message::merge_to_limit takes. It is not the message’s length or end offset. For a buffer that holds exactly the message, pass 0.

The default Message::merge_to_limit calls this with its limit. Call it yourself in a merge_to_limit override that calls Message::merge_field directly, passing the limit (or 0 when the override decodes a buffer holding exactly the message), and before decoding a buffer other than the one the context came with.

Source

pub fn with_element_memory(self, element_memory_limit: &'a Cell<usize>) -> Self

Attach the shared element-memory budget in element_memory_limit.

Without this the budget is absent and register_element_memory is a no-op, which is what a DecodeContext::new built elsewhere — older generated code, say — gets. buffa’s own entry points attach it, so a decode through DecodeOptions or the Message conveniences is bounded by DEFAULT_ELEMENT_MEMORY_LIMIT.

Attach a fresh cell per top-level decode, for the same reason the unknown-field allowance needs one: a reused cell drains across calls.

Source

pub fn depth(&self) -> u32

The remaining recursion depth.

Source

pub fn remaining_unknown_fields(&self) -> usize

The number of additional unknown fields this decode may materialize.

Source

pub fn rejects_unknown_fields(&self) -> bool

Whether this decode explicitly rejects all unknown wire fields. Exhausting a positive storage budget does not change this policy.

Source

pub fn check_unknown_field(&self) -> Result<(), DecodeError>

Check an unknown occurrence independently of its storage policy.

§Errors

Returns UnknownFieldLimitExceeded when this decode started with a zero allowance. Discarded fields do not consume a positive storage budget.

Source

pub fn descend(self) -> Result<Self, DecodeError>

Consume one level of recursion depth.

§Errors

Returns DecodeError::RecursionLimitExceeded when the depth budget is exhausted.

Source

pub fn register_unknown_field(&self) -> Result<(), DecodeError>

Consume one slot of the shared unknown-field allowance.

Call before materializing an unknown field. Discarded occurrences use check_unknown_field instead, preserving the storage budget’s meaning.

§Errors

Returns DecodeError::UnknownFieldLimitExceeded (leaving the allowance unchanged) when no slots remain.

Source

pub fn remaining_element_memory(&self) -> Option<usize>

The element-memory budget left to this decode, or None when no budget is attached.

Source

pub fn register_element_memory(&self, bytes: usize) -> Result<(), DecodeError>

Charge bytes against the shared element-memory budget.

Call before materializing an element of a repeated length-delimited field, passing that element’s size_of. Those are the fields where the wire is far cheaper than what it decodes into: an empty message element is two bytes and costs size_of::<T>(), so a payload well inside DecodeOptions::with_max_message_size can still expand by two orders of magnitude. Packed scalars are not charged by the generated or view decoders — there the worst case is a 1-byte varint becoming a 4-byte i32, and bounding that would reject legitimate columnar payloads. The reflective DynamicMessage decoder does charge them: its store is a Vec<Value>, so a 1-byte varint becomes a whole Value slot and the ratio is an order of magnitude worse.

No-op when no budget is attached (see with_element_memory).

§Errors

Returns DecodeError::ElementMemoryLimitExceeded (leaving the budget unchanged) when bytes exceeds what remains.

Trait Implementations§

Source§

impl<'a> Clone for DecodeContext<'a>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl<'a> Copy for DecodeContext<'a>

Source§

impl<'a> Debug for DecodeContext<'a>

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a> !RefUnwindSafe for DecodeContext<'a>

§

impl<'a> !Send for DecodeContext<'a>

§

impl<'a> !Sync for DecodeContext<'a>

§

impl<'a> !UnwindSafe for DecodeContext<'a>

§

impl<'a> Forget for DecodeContext<'a>

§

impl<'a> Freeze for DecodeContext<'a>

§

impl<'a> Move for DecodeContext<'a>

§

impl<'a> Unpin for DecodeContext<'a>

§

impl<'a> UnsafeUnpin for DecodeContext<'a>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.