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.
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>
impl<'a> DecodeContext<'a>
Sourcepub fn new(depth: u32, unknown_field_limit: &'a Cell<usize>) -> Self
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.
Sourcepub fn with_element_memory(self, element_memory_limit: &'a Cell<usize>) -> Self
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.
Sourcepub fn remaining_unknown_fields(&self) -> usize
pub fn remaining_unknown_fields(&self) -> usize
The number of additional unknown fields this decode may materialize.
Sourcepub fn rejects_unknown_fields(&self) -> bool
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.
Sourcepub fn check_unknown_field(&self) -> Result<(), DecodeError>
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.
Sourcepub fn descend(self) -> Result<Self, DecodeError>
pub fn descend(self) -> Result<Self, DecodeError>
Consume one level of recursion depth.
§Errors
Returns DecodeError::RecursionLimitExceeded when the depth budget
is exhausted.
Sourcepub fn register_unknown_field(&self) -> Result<(), DecodeError>
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.
Sourcepub fn remaining_element_memory(&self) -> Option<usize>
pub fn remaining_element_memory(&self) -> Option<usize>
The element-memory budget left to this decode, or None when no budget
is attached.
Sourcepub fn register_element_memory(&self, bytes: usize) -> Result<(), DecodeError>
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.