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>
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_message_end(self, message_end: usize) -> Self
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.
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.