Skip to main content

buffa/
message.rs

1// Modified by ReallyMe Technologies Limited.
2//! The core [`Message`] trait and [`DecodeOptions`] builder.
3//!
4//! Every generated message type implements [`Message`], which provides
5//! encode/decode/merge methods and a two-pass serialization model
6//! (`compute_size` populates a [`SizeCache`](crate::SizeCache), `write_to`
7//! consumes it) that avoids the exponential-time problem affecting naïve
8//! length-delimited encoders.
9
10use crate::encode_sink::EncodeSink;
11use bytes::Buf;
12
13use crate::error::{DecodeError, EncodeError};
14use crate::message_field::DefaultInstance;
15
16/// Default recursion depth limit for decoding nested messages.
17///
18/// Protobuf implementations are required to enforce a recursion limit to
19/// prevent stack overflow from deeply nested messages in untrusted input.
20/// This value (100) matches the limit used by the official protobuf
21/// implementations and the protobuf conformance suite.
22///
23/// Pass this constant as the depth when constructing a [`DecodeContext`] for
24/// a top-level [`Message::merge`] call.  The provided convenience methods
25/// ([`Message::decode`], [`Message::decode_from_slice`],
26/// [`Message::merge_from_slice`]) use this limit automatically.
27pub const RECURSION_LIMIT: u32 = 100;
28
29/// Default limit on unknown fields decoded per top-level decode: 1,000,000.
30///
31/// Bounds the number of [`UnknownField`](crate::UnknownField) values the
32/// decoder will materialize in a single top-level decode, independent of
33/// the input size. Without this bound, wire data can force allocation far
34/// in excess of its own size: every 2-byte unknown varint field
35/// materialises a ~40-byte `UnknownField`, a ~20× amplification, so a
36/// 64 MiB payload of unknown fields would otherwise force over 1 GiB of
37/// heap. The count limit caps that overhead at roughly `limit × 40` bytes
38/// (~40 MB at the default); unknown length-delimited *payload* bytes are
39/// not counted against the limit because they are already bounded by the
40/// input size, which [`DecodeOptions::with_max_message_size`] governs.
41///
42/// The `limit × 40` figure prices a *flat* unknown field, and nesting costs
43/// more than that. Each unknown group allocates its own `Vec` of children,
44/// and `Vec`'s minimum non-zero capacity is four elements — so a group
45/// holding a single child occupies ~160 bytes of that `Vec` plus its own
46/// ~40-byte slot, roughly 200 bytes charged as one. A payload of many
47/// shallow groups therefore reaches about five times the flat ceiling,
48/// ~200 MB at the default rather than ~40 MB. Still bounded and still
49/// proportional to the limit, but worth knowing when choosing one: the
50/// count bounds *slots*, and a slot is not a fixed number of bytes.
51///
52/// A million unknown fields is far more than any realistic
53/// forward-compatibility scenario needs. Raise the limit with
54/// [`DecodeOptions::with_unknown_field_limit`] if you decode trusted
55/// messages that legitimately carry more (e.g. a proxy forwarding messages
56/// with a huge unpacked repeated field from a much newer schema).
57pub const DEFAULT_UNKNOWN_FIELD_LIMIT: usize = 1_000_000;
58
59/// Default element-memory budget: 32 MiB per top-level decode.
60///
61/// Bounds the memory a single decode may materialize in the elements of
62/// length-delimited containers — repeated message, string and bytes fields, and
63/// map entries — independent of the input size. These amplify the same way unknown fields do, and further: an
64/// empty repeated message element is 2 wire bytes and materializes
65/// `size_of::<T>()` in the `Vec` it lands in, measured at 256 bytes for a
66/// message of a few `Vec`/`String` fields — a 128x ratio, so 4 MiB of such
67/// elements would otherwise force ~512 MiB. Empty `bytes` and `string`
68/// elements amplify 16x and 12x by the same route.
69///
70/// A map entry is charged for both halves, key and value: an omitted message
71/// value still materializes in the map, and a few bytes of key buy a distinct
72/// slot, so `map<string, Message>` amplifies exactly as a repeated message does.
73///
74/// Only the element footprint is counted. The *contents* of a string or bytes
75/// element are not, being already bounded by the input size that
76/// [`DecodeOptions::with_max_message_size`] governs, and packed scalars are not
77/// charged by the generated or view decoders: their worst case there is a
78/// 1-byte varint becoming a 4-byte `i32`, which is not an amplification vector,
79/// and bounding it would reject legitimate columnar payloads that carry
80/// millions of elements by design. The reflective `DynamicMessage` decoder is
81/// the exception — it stores each element as a `Value`, so the same varint
82/// costs `size_of::<Value>()` and is charged accordingly. A columnar payload
83/// decoded reflectively may therefore need this limit raised.
84///
85/// The textproto parser defaults to this same constant, raised through
86/// [`TextDecoder::with_element_memory_limit`](crate::text::TextDecoder::with_element_memory_limit).
87/// `buffa_descriptor`'s reflective JSON parser defaults to it too, raised
88/// through `buffa_descriptor::DynamicMessageSeed::with_element_memory_limit`.
89///
90/// 32 MiB of elements is far more than a realistic message carries, and sits
91/// alongside what [`DEFAULT_UNKNOWN_FIELD_LIMIT`] already permits (~38 MiB of
92/// `UnknownField`). Raise it with
93/// [`DecodeOptions::with_element_memory_limit`] for trusted inputs that
94/// legitimately decode into more. Note `Vec` grows by doubling, so peak
95/// resident memory can reach roughly twice the budget; this bounds what is
96/// materialized, not what the allocator reserves.
97pub const DEFAULT_ELEMENT_MEMORY_LIMIT: usize = 32 * 1024 * 1024;
98
99/// Per-decode limits threaded through every merge call.
100///
101/// Carries the remaining recursion depth and a shared unknown-field
102/// allowance. The context is `Copy` — passing it to a callee hands over the
103/// current depth by value, while the unknown-field allowance lives in a
104/// [`Cell`](core::cell::Cell) owned by the top-level decode entry point, so
105/// every field decoded under one entry point draws from the same
106/// allowance.
107///
108/// It also records where the message being decoded ends in the buffer the
109/// context is passed with. The default [`Message::merge_to_limit`] (and so
110/// [`Message::merge`]) records it; [`Message::merge_length_delimited`], map
111/// entries and
112/// [`decode_string_to_ctx`](crate::types::decode_string_to_ctx) /
113/// [`decode_bytes_to_ctx`](crate::types::decode_bytes_to_ctx) reject a declared
114/// length that runs past it, before decoding what it covers.
115/// [`DecodeContext::new`] records no end, so the whole buffer is allowed.
116///
117/// Because the end belongs to one buffer, hand-written code that decodes a
118/// *different* buffer with a context it was given (a copy of the message, a
119/// decompressed payload) must record that buffer's end first, with
120/// [`with_message_end`](Self::with_message_end) — `0` when the message runs to
121/// the end of that buffer — or start it with the default implementations of
122/// [`Message::merge`] or [`Message::merge_to_limit`], which do so. Otherwise a valid nested field
123/// near the end of that buffer can be rejected with
124/// [`DecodeError::UnexpectedEof`].
125///
126/// Constructed automatically by the [`Message`] convenience methods
127/// ([`decode`](Message::decode), [`decode_from_slice`](Message::decode_from_slice),
128/// [`merge_from_slice`](Message::merge_from_slice)) and by [`DecodeOptions`].
129/// Construct one manually only when calling [`Message::merge`] or the other
130/// depth-threading methods directly — and construct a **fresh limit cell
131/// per top-level decode**. Reusing one cell across decode calls makes the
132/// limit cumulative: each call drains it further until every decode fails
133/// with [`DecodeError::UnknownFieldLimitExceeded`].
134///
135/// ```rust
136/// # use buffa::__doctest_fixtures::Person;
137/// use core::cell::Cell;
138/// use buffa::{DecodeContext, Message, DEFAULT_UNKNOWN_FIELD_LIMIT, RECURSION_LIMIT};
139///
140/// # fn example(mut bytes: &[u8]) -> Result<(), buffa::DecodeError> {
141/// let limit = Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
142/// let mut msg = Person::default();
143/// msg.merge(&mut bytes, DecodeContext::new(RECURSION_LIMIT, &limit))?;
144/// # Ok(())
145/// # }
146/// ```
147#[derive(Clone, Copy, Debug)]
148pub struct DecodeContext<'a> {
149    depth: u32,
150    unknown_fields_remaining: &'a core::cell::Cell<usize>,
151    reject_unknown_fields: bool,
152    element_memory_remaining: Option<&'a core::cell::Cell<usize>>,
153    /// `buf.remaining()` at the end of the innermost enclosing
154    /// length-delimited message; 0 when the message runs to the end of the
155    /// buffer.
156    message_end: usize,
157}
158
159impl<'a> DecodeContext<'a> {
160    /// Create a context with `depth` remaining recursion levels and the
161    /// remaining unknown-field allowance stored in `unknown_field_limit`.
162    #[must_use]
163    pub fn new(depth: u32, unknown_field_limit: &'a core::cell::Cell<usize>) -> Self {
164        Self {
165            depth,
166            unknown_fields_remaining: unknown_field_limit,
167            reject_unknown_fields: unknown_field_limit.get() == 0,
168            element_memory_remaining: None,
169            message_end: 0,
170        }
171    }
172
173    /// The number of bytes of the buffer that follow the innermost enclosing
174    /// length-delimited message, or 0 when it runs to the end of the buffer.
175    #[inline]
176    pub(crate) fn message_end(&self) -> usize {
177        self.message_end
178    }
179
180    /// Record that the message being decoded ends when the buffer this
181    /// context is passed with has `message_end` bytes left, so a field,
182    /// sub-message or map entry of it that would reach further is rejected.
183    ///
184    /// `message_end` is a count of the bytes that *follow* the message, the
185    /// value `buf.remaining()` will have when the message ends: the same
186    /// `limit` that [`Message::merge_to_limit`] takes. It is not the
187    /// message's length or end offset. For a buffer that holds exactly the
188    /// message, pass `0`.
189    ///
190    /// The default [`Message::merge_to_limit`] calls this with its `limit`.
191    /// Call it yourself in a `merge_to_limit` override that calls
192    /// [`Message::merge_field`] directly, passing the `limit` (or `0` when the
193    /// override decodes a buffer holding exactly the message), and before
194    /// decoding a buffer other than the one the context came with.
195    #[inline]
196    #[must_use]
197    pub fn with_message_end(self, message_end: usize) -> Self {
198        Self {
199            message_end,
200            ..self
201        }
202    }
203
204    /// Check a declared length against the enclosing message: the bytes
205    /// `buf` holds before [`message_end`](Self::message_end), given its
206    /// `remaining` bytes.
207    ///
208    /// # Errors
209    ///
210    /// Returns [`DecodeError::UnexpectedEof`] if `len` runs past the end of
211    /// the enclosing message or of the buffer.
212    #[inline]
213    pub(crate) fn check_len(&self, remaining: usize, len: usize) -> Result<(), DecodeError> {
214        // A prefix may already have crossed the boundary. Saturation would
215        // turn that invalid state into a valid zero-length payload.
216        let available = remaining
217            .checked_sub(self.message_end)
218            .ok_or(DecodeError::UnexpectedEof)?;
219        if len > available {
220            return Err(DecodeError::UnexpectedEof);
221        }
222        Ok(())
223    }
224
225    /// Attach the shared element-memory budget in `element_memory_limit`.
226    ///
227    /// Without this the budget is absent and [`register_element_memory`] is a
228    /// no-op, which is what a [`DecodeContext::new`] built elsewhere — older
229    /// generated code, say — gets. buffa's own entry points attach it, so a
230    /// decode through [`DecodeOptions`] or the [`Message`] conveniences is
231    /// bounded by [`DEFAULT_ELEMENT_MEMORY_LIMIT`].
232    ///
233    /// Attach a **fresh cell per top-level decode**, for the same reason the
234    /// unknown-field allowance needs one: a reused cell drains across calls.
235    ///
236    /// [`register_element_memory`]: DecodeContext::register_element_memory
237    #[must_use]
238    pub fn with_element_memory(
239        mut self,
240        element_memory_limit: &'a core::cell::Cell<usize>,
241    ) -> Self {
242        self.element_memory_remaining = Some(element_memory_limit);
243        self
244    }
245
246    /// The remaining recursion depth.
247    #[must_use]
248    pub fn depth(&self) -> u32 {
249        self.depth
250    }
251
252    /// The number of additional unknown fields this decode may materialize.
253    #[must_use]
254    pub fn remaining_unknown_fields(&self) -> usize {
255        self.unknown_fields_remaining.get()
256    }
257
258    /// Whether this decode explicitly rejects all unknown wire fields.
259    /// Exhausting a positive storage budget does not change this policy.
260    #[must_use]
261    pub fn rejects_unknown_fields(&self) -> bool {
262        self.reject_unknown_fields
263    }
264
265    /// Check an unknown occurrence independently of its storage policy.
266    ///
267    /// # Errors
268    /// Returns `UnknownFieldLimitExceeded` when this decode started with a
269    /// zero allowance. Discarded fields do not consume a positive storage budget.
270    pub fn check_unknown_field(&self) -> Result<(), DecodeError> {
271        if self.reject_unknown_fields {
272            Err(DecodeError::UnknownFieldLimitExceeded)
273        } else {
274            Ok(())
275        }
276    }
277
278    // Deferred children replay the rejection policy separately from a storage
279    // allowance that may have reached zero before their bytes were recorded.
280    pub(crate) fn with_unknown_field_rejection(mut self, reject: bool) -> Self {
281        self.reject_unknown_fields = reject;
282        self
283    }
284
285    /// Consume one level of recursion depth.
286    ///
287    /// # Errors
288    ///
289    /// Returns [`DecodeError::RecursionLimitExceeded`] when the depth budget
290    /// is exhausted.
291    pub fn descend(self) -> Result<Self, DecodeError> {
292        let depth = self
293            .depth
294            .checked_sub(1)
295            .ok_or(DecodeError::RecursionLimitExceeded)?;
296        Ok(Self { depth, ..self })
297    }
298
299    /// Consume one slot of the shared unknown-field allowance.
300    ///
301    /// Call before materializing an unknown field. Discarded occurrences use
302    /// `check_unknown_field` instead, preserving the storage budget's meaning.
303    ///
304    /// # Errors
305    ///
306    /// Returns [`DecodeError::UnknownFieldLimitExceeded`] (leaving the
307    /// allowance unchanged) when no slots remain.
308    pub fn register_unknown_field(&self) -> Result<(), DecodeError> {
309        self.check_unknown_field()?;
310        let remaining = self
311            .unknown_fields_remaining
312            .get()
313            .checked_sub(1)
314            .ok_or(DecodeError::UnknownFieldLimitExceeded)?;
315        self.unknown_fields_remaining.set(remaining);
316        Ok(())
317    }
318
319    /// The element-memory budget left to this decode, or `None` when no budget
320    /// is attached.
321    #[must_use]
322    pub fn remaining_element_memory(&self) -> Option<usize> {
323        self.element_memory_remaining.map(core::cell::Cell::get)
324    }
325
326    /// Spend what is left of the element-memory budget, so that every later
327    /// nonzero charge on this context fails.
328    ///
329    /// A caller that drops a value after
330    /// [`ElementMemoryLimitExceeded`](DecodeError::ElementMemoryLimitExceeded)
331    /// and keeps decoding with the same context uses this to make the first
332    /// value that does not fit the last one it reads: a failed charge leaves
333    /// the budget unchanged, so a smaller value after it could otherwise
334    /// still be charged. The bound on the total does not depend on this
335    /// call; it comes from never refunding a charge.
336    pub(crate) fn exhaust_element_memory(&self) {
337        if let Some(cell) = self.element_memory_remaining {
338            cell.set(0);
339        }
340    }
341
342    /// Charge `bytes` against the shared element-memory budget.
343    ///
344    /// Call **before** materializing an element of a repeated
345    /// length-delimited field, passing that element's `size_of`. Those are the
346    /// fields where the wire is far cheaper than what it decodes into: an empty
347    /// message element is two bytes and costs `size_of::<T>()`, so a payload
348    /// well inside [`DecodeOptions::with_max_message_size`] can still expand by
349    /// two orders of magnitude. Packed scalars are not charged by the
350    /// generated or view decoders — there the worst case is a 1-byte varint
351    /// becoming a 4-byte `i32`, and bounding that would reject legitimate
352    /// columnar payloads. The reflective `DynamicMessage` decoder does charge
353    /// them: its store is a `Vec<Value>`, so a 1-byte varint becomes a whole
354    /// `Value` slot and the ratio is an order of magnitude worse.
355    ///
356    /// No-op when no budget is attached (see
357    /// [`with_element_memory`](DecodeContext::with_element_memory)).
358    ///
359    /// # Errors
360    ///
361    /// Returns [`DecodeError::ElementMemoryLimitExceeded`] (leaving the budget
362    /// unchanged) when `bytes` exceeds what remains.
363    pub fn register_element_memory(&self, bytes: usize) -> Result<(), DecodeError> {
364        let Some(cell) = self.element_memory_remaining else {
365            return Ok(());
366        };
367        let remaining = cell.get();
368        if bytes > remaining {
369            return Err(DecodeError::ElementMemoryLimitExceeded);
370        }
371        cell.set(remaining - bytes);
372        Ok(())
373    }
374}
375
376/// Maximum encoded size of a protobuf message: 2 GiB − 1 (`0x7FFF_FFFF`).
377///
378/// The protobuf specification limits any message — top-level or nested — to
379/// 2 GiB. buffa enforces this symmetrically:
380///
381/// - **Decode** rejects length-delimited payloads declared larger than this
382///   with [`DecodeError::MessageTooLarge`], matching protobuf C++ and Java.
383/// - **Encode** refuses to serialize a message whose encoded size would
384///   exceed it: the panicking entry points ([`Message::encode`] and friends)
385///   panic, the `try_*` twins ([`Message::try_encode`] and friends) return
386///   [`EncodeError::MessageTooLarge`]. Without this check a writer could
387///   produce bytes that no conforming decoder — including buffa's own —
388///   will read back.
389pub const MAX_MESSAGE_BYTES: u32 = 0x7FFF_FFFF;
390
391/// Saturate a `u64` size accumulator to `u32`.
392///
393/// Generated `compute_size` implementations accumulate in `u64` (which
394/// cannot overflow for any message that fits in memory) and saturate to
395/// `u32` once at each message node's return. A saturated value is
396/// necessarily greater than [`MAX_MESSAGE_BYTES`], so any over-limit
397/// message — whether from one huge field or from aggregation — surfaces at
398/// the encode entry points' size check; the byte-exact value is preserved
399/// for every message the wire format can actually represent.
400///
401/// Manual [`Message`] implementations should use the same pattern:
402/// accumulate the encoded size in a `u64` and `saturate_size` it at return.
403#[inline]
404#[must_use]
405pub fn saturate_size(size: u64) -> u32 {
406    u32::try_from(size).unwrap_or(u32::MAX)
407}
408
409/// Validate a computed encode size against [`MAX_MESSAGE_BYTES`].
410///
411/// The error-returning half of the encode-size funnel: the `try_encode*`
412/// methods (and generated inherent encode entry points, e.g. on lazy view
413/// types) validate their [`compute_size`](Message::compute_size) result
414/// through this before writing anything.
415///
416/// # Errors
417///
418/// Returns [`EncodeError::MessageTooLarge`] if `size` exceeds
419/// [`MAX_MESSAGE_BYTES`].
420#[inline]
421pub fn checked_encode_size(size: u32) -> Result<u32, EncodeError> {
422    if size > MAX_MESSAGE_BYTES {
423        Err(EncodeError::MessageTooLarge)
424    } else {
425        Ok(size)
426    }
427}
428
429/// Write `msg`, whose encoded size is `size` and whose nested sizes are
430/// recorded in `cache`, into `buf` through the shared pre-sized writer (see
431/// [`encode_sink`](crate::encode_sink)).
432#[inline]
433fn write_sized<M: Message>(
434    msg: &M,
435    size: u32,
436    cache: &mut crate::SizeCache,
437    buf: &mut impl EncodeSink,
438) {
439    crate::encode_sink::write_contiguous(
440        size as usize,
441        cache,
442        buf,
443        |cache, sink| msg.write_to(cache, sink),
444        |cache, sink| msg.write_to(cache, sink),
445    );
446}
447
448/// Debug-build two-pass coherence ledger: asserts `write_to` produced
449/// exactly the byte count `compute_size` declared.
450///
451/// Called by the provided encode entry points (through
452/// `encode_sink::write_contiguous` for a `BufMut`, and directly by
453/// `encode_to_vec` / `try_encode_to_vec` and their generated lazy-view
454/// counterparts) after the write pass; the `*_to_bytes` entry points reach
455/// it through those. The write pass is ground truth — leaf writers emit `len as u64` prefixes and
456/// full payloads — so any divergence indicates a size-pass bug (wrong
457/// presence check, traversal drift) in a generated or manual
458/// implementation. Free in release builds.
459#[doc(hidden)]
460#[inline]
461#[track_caller]
462pub fn debug_assert_two_pass(written: usize, declared: usize) {
463    debug_assert_eq!(
464        written, declared,
465        "write_to produced a different byte count than compute_size \
466         declared (two-pass traversal mismatch)"
467    );
468}
469
470/// Panic shim shared by every panicking encode entry point — the provided
471/// `Message` / `ViewEncode` methods, `SizeCachePool`, and generated
472/// lazy-view inherent methods all delegate to their `try_*` twin and route
473/// the `Err` here, so the panicking and fallible paths cannot diverge.
474///
475/// # Panics
476///
477/// Always — that is its entire job: one cold, out-of-line panic site with
478/// the canonical over-limit message.
479#[doc(hidden)]
480#[cold]
481#[inline(never)]
482pub fn encode_size_overflow() -> ! {
483    panic!(
484        "message encoded size exceeds the 2 GiB protobuf limit \
485         (the try_* variant of this method returns this as an error instead)"
486    )
487}
488
489/// The core trait implemented by all protobuf message types.
490///
491/// This trait is implemented by **generated code** — you write a `.proto` file,
492/// codegen emits the Rust struct and its `Message` impl. You should almost
493/// never implement this trait by hand.
494///
495/// # Manual implementation is discouraged
496///
497/// The only reason to implement `Message` yourself is when you need a
498/// custom in-memory representation that codegen cannot produce — for
499/// example, wrapping a `std::ops::Range<i64>` as a leaf message so the
500/// rest of your code uses the natural Rust type. If you just want a message
501/// type, **write a `.proto` file instead.**
502///
503/// Manual implementation is intentionally high-friction:
504/// - You must correctly implement the two-pass serialization contract
505///   (`compute_size` populates the [`SizeCache`](crate::SizeCache) in the
506///   same traversal order that `write_to` consumes it).
507/// - You must implement wire-format decoding in `merge_field`.
508/// - You must implement the [`DefaultInstance`] supertrait, which provides
509///   the lazily-initialized static default that [`MessageField`](crate::MessageField)
510///   dereferences to when unset.
511///
512/// If you still need to do this, see the [custom types section of the
513/// user guide](https://github.com/anthropics/buffa/blob/main/docs/guide.md#custom-type-implementations)
514/// for a complete worked example.
515///
516/// # Serialization model
517///
518/// Serialization is a two-pass process to avoid the exponential-time problem
519/// that affects prost with deeply nested messages:
520///
521/// 1. **`compute_size()`** — walks the message tree and records the encoded
522///    size of every length-delimited sub-message in a [`SizeCache`].
523/// 2. **`write_to()`** — walks the tree again, writing bytes and consuming
524///    cached sizes for length-prefixed sub-messages.
525///
526/// The provided [`encode`](Self::encode) method performs both passes with a
527/// fresh [`SizeCache`] — most callers use that and never touch the cache
528/// directly. `compute_size` / `write_to` take the cache explicitly so that
529/// manual `Message` implementations can thread it through nested-message
530/// recursion.
531///
532/// # Thread safety
533///
534/// `Message` requires `Send + Sync`. Generated structs contain no interior
535/// mutability — serialization state lives in the external [`SizeCache`], not
536/// in the message — so messages can be placed in an `Arc` and shared across
537/// threads freely. `merge` requires `&mut self`, so mutation is exclusive.
538///
539/// # Struct evolution policy
540///
541/// Generated message structs (and their [`MessageView`](crate::MessageView) /
542/// [`LazyMessageView`](crate::LazyMessageView) counterparts) may gain fields
543/// across releases — both when the source `.proto` schema evolves and when
544/// buffa adds internal bookkeeping such as `__buffa_unknown_fields` or the
545/// required-field presence bitmaps. **Exhaustive struct literals and
546/// exhaustive destructuring patterns are not covered by buffa's semver
547/// guarantees**: code that names every field will fail to compile when a field
548/// is added, and that breakage is not considered a breaking change.
549///
550/// The forward-compatible ways to construct a generated struct are:
551///
552/// - decode it from bytes;
553/// - struct-update syntax over the default: `Foo { x, y, ..Default::default() }`;
554/// - start from `Foo::default()` and assign fields (or call generated `with_*`
555///   setters when `generate_with_setters` is enabled).
556///
557/// The structs are deliberately *not* `#[non_exhaustive]`, so struct-update
558/// syntax remains available from downstream crates; this policy is a documented
559/// contract rather than a compiler-enforced one.
560///
561/// [`SizeCache`]: crate::SizeCache
562pub trait Message: DefaultInstance + Clone + PartialEq + Send + Sync {
563    /// Compute the encoded byte size of this message, recording nested
564    /// sub-message sizes in `cache` for `write_to` to consume.
565    ///
566    /// Most callers should use [`encode`](Self::encode) instead, which runs
567    /// both passes with a fresh cache. Manual `Message` implementations call
568    /// this recursively on nested message fields, wrapping each call in
569    /// [`SizeCache::reserve`] / [`SizeCache::set`] for length-delimited
570    /// fields — see the user guide's custom-types section for the pattern.
571    ///
572    /// # Size limit
573    ///
574    /// The protobuf specification limits messages to 2 GiB
575    /// ([`MAX_MESSAGE_BYTES`]). Generated implementations accumulate in
576    /// `u64` and saturate the return value via [`saturate_size`], so an
577    /// over-limit message yields a return greater than [`MAX_MESSAGE_BYTES`]
578    /// rather than a wrapped value; the provided encode methods check this
579    /// and refuse to produce over-limit output. Manual implementations must
580    /// follow the same pattern — if their arithmetic can wrap, over-limit
581    /// messages may encode corrupt bytes that bypass the check.
582    ///
583    /// [`SizeCache::reserve`]: crate::SizeCache::reserve
584    /// [`SizeCache::set`]: crate::SizeCache::set
585    fn compute_size(&self, cache: &mut crate::SizeCache) -> u32;
586
587    /// Write this message's encoded bytes to a buffer, consuming
588    /// nested-message sizes from `cache` (populated by a prior
589    /// `compute_size` call on the same cache).
590    ///
591    /// Most callers should use [`encode`](Self::encode) instead. This is a
592    /// low-level primitive: the 2 GiB size check ([`MAX_MESSAGE_BYTES`])
593    /// lives in the provided encode entry points, so callers driving
594    /// `compute_size` / `write_to` directly must validate the size
595    /// themselves (via [`checked_encode_size`]).
596    ///
597    /// An implementation must write exactly the number of bytes
598    /// `compute_size` returned. The provided encode methods write a
599    /// `BufMut` into space sized by `compute_size` and panic if `write_to`
600    /// writes more; in debug builds they also panic if it writes fewer.
601    fn write_to(&self, cache: &mut crate::SizeCache, buf: &mut impl EncodeSink);
602
603    /// Compute size, then write. This is the primary encoding API.
604    ///
605    /// The sink can be any [`BufMut`](bytes::BufMut) (contiguous output) or
606    /// a [`Rope`](crate::Rope), which captures large `bytes::Bytes` fields
607    /// as reference-counted segments for zero-copy handoff to networking
608    /// code — see [`encode_sink`](crate::encode_sink).
609    ///
610    /// # Panics
611    ///
612    /// Panics if the encoded size exceeds the 2 GiB protobuf limit
613    /// ([`MAX_MESSAGE_BYTES`]) — see [`try_encode`](Self::try_encode) for
614    /// the error-returning variant.
615    /// Also panics, when `buf` is a [`BufMut`](bytes::BufMut), if a manual
616    /// implementation's `write_to` produces more bytes than its
617    /// `compute_size` declared, and in debug builds if it produces a
618    /// different number.
619    #[inline]
620    fn encode(&self, buf: &mut impl EncodeSink) {
621        self.try_encode(buf)
622            .unwrap_or_else(|_| encode_size_overflow())
623    }
624
625    /// Encode, returning an error instead of panicking if the encoded size
626    /// exceeds the 2 GiB protobuf limit ([`MAX_MESSAGE_BYTES`]).
627    ///
628    /// On `Err`, nothing is written to `buf`.
629    ///
630    /// # Errors
631    ///
632    /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
633    /// [`MAX_MESSAGE_BYTES`].
634    fn try_encode(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError> {
635        let mut cache = crate::SizeCache::new();
636        let size = checked_encode_size(self.compute_size(&mut cache))?;
637        write_sized(self, size, &mut cache, buf);
638        Ok(())
639    }
640
641    /// Encode using a caller-supplied [`SizeCache`](crate::SizeCache), for
642    /// reuse across many encodes in a hot loop. Clears the cache first.
643    ///
644    /// # Panics
645    ///
646    /// Panics if the encoded size exceeds the 2 GiB protobuf limit
647    /// ([`MAX_MESSAGE_BYTES`]) — see
648    /// [`try_encode_with_cache`](Self::try_encode_with_cache) for the
649    /// error-returning variant.
650    /// Also panics, when `buf` is a [`BufMut`](bytes::BufMut), if a manual
651    /// implementation's `write_to` produces more bytes than its
652    /// `compute_size` declared, and in debug builds if it produces a
653    /// different number.
654    #[inline]
655    fn encode_with_cache(&self, cache: &mut crate::SizeCache, buf: &mut impl EncodeSink) {
656        self.try_encode_with_cache(cache, buf)
657            .unwrap_or_else(|_| encode_size_overflow())
658    }
659
660    /// Encode with a caller-supplied [`SizeCache`](crate::SizeCache),
661    /// returning an error instead of panicking if the encoded size exceeds
662    /// the 2 GiB protobuf limit ([`MAX_MESSAGE_BYTES`]). Clears the cache
663    /// first.
664    ///
665    /// On `Err`, nothing is written to `buf`.
666    ///
667    /// # Errors
668    ///
669    /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
670    /// [`MAX_MESSAGE_BYTES`].
671    fn try_encode_with_cache(
672        &self,
673        cache: &mut crate::SizeCache,
674        buf: &mut impl EncodeSink,
675    ) -> Result<(), EncodeError> {
676        cache.clear();
677        let size = checked_encode_size(self.compute_size(cache))?;
678        write_sized(self, size, cache, buf);
679        Ok(())
680    }
681
682    /// Encode this message into `buf` only if its encoded size fits within
683    /// `max_bytes`, using a single size pass that is then reused for the write.
684    ///
685    /// This avoids the double tree-walk that `try_encoded_len` + `encode`
686    /// would require: one `compute_size` pass populates the [`SizeCache`];
687    /// the budget check happens before `write_to` runs, so on `Err` nothing
688    /// is written to `buf`.
689    ///
690    /// Returns the encoded body length on success (excludes any length prefix
691    /// you add for framing) — useful for metrics or frame sizing. Note that
692    /// this return type is `u32`, unlike `try_encode`'s `()`. `max_bytes` is
693    /// also `u32` to match the encode-size domain; callers with a `usize`
694    /// budget can cast with `u32::try_from(budget).unwrap_or(u32::MAX)`.
695    ///
696    /// # Errors
697    ///
698    /// - [`EncodeError::MessageTooLarge`] if the encoded size exceeds the
699    ///   2 GiB protobuf limit ([`MAX_MESSAGE_BYTES`]).
700    ///   `MessageTooLarge` takes precedence if both limits are exceeded.
701    /// - [`EncodeError::ExceedsBudget`] if the encoded size is within the
702    ///   protobuf limit but exceeds `max_bytes`.
703    ///
704    /// [`SizeCache`]: crate::SizeCache
705    fn try_encode_bounded(
706        &self,
707        max_bytes: u32,
708        buf: &mut impl EncodeSink,
709    ) -> Result<u32, EncodeError> {
710        let mut cache = crate::SizeCache::new();
711        self.try_encode_bounded_with_cache(max_bytes, &mut cache, buf)
712    }
713
714    /// Like [`try_encode_bounded`](Self::try_encode_bounded) but reuses an
715    /// existing [`SizeCache`], clearing it first.
716    ///
717    /// Prefer [`SizeCachePool::try_encode_bounded`](crate::SizeCachePool::try_encode_bounded)
718    /// for hot-loop use — the pool amortizes the cache's spill allocation.
719    ///
720    /// # Errors
721    ///
722    /// Same as [`try_encode_bounded`](Self::try_encode_bounded).
723    ///
724    /// [`SizeCache`]: crate::SizeCache
725    fn try_encode_bounded_with_cache(
726        &self,
727        max_bytes: u32,
728        cache: &mut crate::SizeCache,
729        buf: &mut impl EncodeSink,
730    ) -> Result<u32, EncodeError> {
731        cache.clear();
732        let len = checked_encode_size(self.compute_size(cache))?;
733        if len > max_bytes {
734            return Err(EncodeError::ExceedsBudget { len, max_bytes });
735        }
736        write_sized(self, len, cache, buf);
737        Ok(len)
738    }
739
740    /// Compute the encoded byte size of this message.
741    ///
742    /// Walks the message tree, discarding the intermediate [`SizeCache`].
743    /// If you also intend to encode, prefer [`encode`](Self::encode) or
744    /// [`encode_to_vec`](Self::encode_to_vec) — they do a single size pass
745    /// and reuse the cache for the write.
746    ///
747    /// # Panics
748    ///
749    /// Panics if the encoded size exceeds the 2 GiB protobuf limit
750    /// ([`MAX_MESSAGE_BYTES`]) — see [`try_encoded_len`](Self::try_encoded_len)
751    /// for the error-returning variant.
752    ///
753    /// [`SizeCache`]: crate::SizeCache
754    #[inline]
755    #[must_use]
756    fn encoded_len(&self) -> u32 {
757        self.try_encoded_len()
758            .unwrap_or_else(|_| encode_size_overflow())
759    }
760
761    /// Compute the encoded byte size, returning an error instead of
762    /// panicking if it exceeds the 2 GiB protobuf limit
763    /// ([`MAX_MESSAGE_BYTES`]).
764    ///
765    /// # Errors
766    ///
767    /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
768    /// [`MAX_MESSAGE_BYTES`].
769    fn try_encoded_len(&self) -> Result<u32, EncodeError> {
770        checked_encode_size(self.compute_size(&mut crate::SizeCache::new()))
771    }
772
773    /// Encode this message as a length-delimited byte sequence.
774    ///
775    /// # Panics
776    ///
777    /// Panics if the encoded size exceeds the 2 GiB protobuf limit
778    /// ([`MAX_MESSAGE_BYTES`]); the check runs before the length prefix is
779    /// written, so nothing reaches `buf` on failure. See
780    /// [`try_encode_length_delimited`](Self::try_encode_length_delimited)
781    /// for the error-returning variant.
782    /// Also panics, when `buf` is a [`BufMut`](bytes::BufMut), if a manual
783    /// implementation's `write_to` produces more bytes than its
784    /// `compute_size` declared, and in debug builds if it produces a
785    /// different number.
786    #[inline]
787    fn encode_length_delimited(&self, buf: &mut impl EncodeSink) {
788        self.try_encode_length_delimited(buf)
789            .unwrap_or_else(|_| encode_size_overflow())
790    }
791
792    /// Encode as a length-delimited byte sequence, returning an error
793    /// instead of panicking if the encoded size exceeds the 2 GiB protobuf
794    /// limit ([`MAX_MESSAGE_BYTES`]).
795    ///
796    /// On `Err`, nothing is written to `buf`.
797    ///
798    /// # Errors
799    ///
800    /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
801    /// [`MAX_MESSAGE_BYTES`].
802    fn try_encode_length_delimited(&self, buf: &mut impl EncodeSink) -> Result<(), EncodeError> {
803        let mut cache = crate::SizeCache::new();
804        let len = checked_encode_size(self.compute_size(&mut cache))?;
805        crate::encoding::encode_varint(u64::from(len), buf);
806        write_sized(self, len, &mut cache, buf);
807        Ok(())
808    }
809
810    /// Encode this message to a new `Vec<u8>`.
811    ///
812    /// # Panics
813    ///
814    /// Panics if the encoded size exceeds the 2 GiB protobuf limit
815    /// ([`MAX_MESSAGE_BYTES`]) — see
816    /// [`try_encode_to_vec`](Self::try_encode_to_vec) for the
817    /// error-returning variant. Also panics if a manual
818    /// implementation's `write_to` produces more bytes than its
819    /// `compute_size` declared, and in debug builds if it produces a
820    /// different number.
821    // Direct body rather than delegating to try_encode_to_vec: LLVM does
822    // not fold the Result<Vec<u8>> niche away even under full inlining, so
823    // the delegating form re-checks the capacity sentinel and round-trips
824    // the Vec through a Result temp in every caller — measured +7.5% on
825    // dense-small-message encode (google_message1, quieted metal,
826    // layout-normalized). `encode_to_bytes` reuses this infallible body via
827    // `Bytes::from`. The unit- and scalar-returning entry points delegate —
828    // their Results stay in registers and fold cleanly.
829    #[inline]
830    #[must_use]
831    fn encode_to_vec(&self) -> alloc::vec::Vec<u8> {
832        let mut cache = crate::SizeCache::new();
833        let size = match checked_encode_size(self.compute_size(&mut cache)) {
834            Ok(size) => size as usize,
835            Err(_) => encode_size_overflow(),
836        };
837        let buf =
838            crate::encode_sink::write_to_new_vec(size, |sink| self.write_to(&mut cache, sink));
839        debug_assert_two_pass(buf.len(), size);
840        buf
841    }
842
843    /// Encode to a new `Vec<u8>`, returning an error instead of panicking
844    /// if the encoded size exceeds the 2 GiB protobuf limit
845    /// ([`MAX_MESSAGE_BYTES`]).
846    ///
847    /// # Errors
848    ///
849    /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
850    /// [`MAX_MESSAGE_BYTES`].
851    ///
852    /// # Panics
853    ///
854    /// Panics if a manual implementation's `write_to` produces more
855    /// bytes than its `compute_size` declared, and in debug builds if it
856    /// produces a different number.
857    fn try_encode_to_vec(&self) -> Result<alloc::vec::Vec<u8>, EncodeError> {
858        let mut cache = crate::SizeCache::new();
859        let size = checked_encode_size(self.compute_size(&mut cache))? as usize;
860        let buf =
861            crate::encode_sink::write_to_new_vec(size, |sink| self.write_to(&mut cache, sink));
862        debug_assert_two_pass(buf.len(), size);
863        Ok(buf)
864    }
865
866    /// Encode this message to a new [`bytes::Bytes`].
867    ///
868    /// Useful when handing off to networking code (hyper, tonic, axum)
869    /// that expects `Bytes` frame or body payloads. Works in `no_std`.
870    ///
871    /// This is `Bytes::from(self.encode_to_vec())` — zero-copy and
872    /// allocation-free for the exactly-sized vector `encode_to_vec` returns —
873    /// and saves readers from having to know that `From<Vec<u8>> for Bytes`
874    /// is zero-copy. Because it is defined in terms of
875    /// [`encode_to_vec`](Self::encode_to_vec), an implementation that
876    /// overrides that method must not call this one from it.
877    ///
878    /// # Panics
879    ///
880    /// Panics if the encoded size exceeds the 2 GiB protobuf limit
881    /// ([`MAX_MESSAGE_BYTES`]) — see
882    /// [`try_encode_to_bytes`](Self::try_encode_to_bytes) for the
883    /// error-returning variant. Also panics if a manual
884    /// implementation's `write_to` produces more bytes than its
885    /// `compute_size` declared, and in debug builds if it produces a
886    /// different number.
887    // Encodes into an exactly-sized `Vec<u8>` and converts:
888    // `From<Vec<u8>> for Bytes` is zero-copy and allocation-free for it.
889    #[inline]
890    #[must_use]
891    fn encode_to_bytes(&self) -> bytes::Bytes {
892        bytes::Bytes::from(self.encode_to_vec())
893    }
894
895    /// Encode to a new [`bytes::Bytes`], returning an error instead of
896    /// panicking if the encoded size exceeds the 2 GiB protobuf limit
897    /// ([`MAX_MESSAGE_BYTES`]).
898    ///
899    /// # Errors
900    ///
901    /// Returns [`EncodeError::MessageTooLarge`] if the encoded size exceeds
902    /// [`MAX_MESSAGE_BYTES`].
903    ///
904    /// # Panics
905    ///
906    /// Panics if a manual implementation's `write_to` produces more
907    /// bytes than its `compute_size` declared, and in debug builds if it
908    /// produces a different number.
909    fn try_encode_to_bytes(&self) -> Result<bytes::Bytes, EncodeError> {
910        self.try_encode_to_vec().map(bytes::Bytes::from)
911    }
912
913    /// Decode a message from a buffer.
914    fn decode(buf: &mut impl Buf) -> Result<Self, DecodeError>
915    where
916        Self: Sized,
917    {
918        let limit = core::cell::Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
919        let elem_budget = core::cell::Cell::new(DEFAULT_ELEMENT_MEMORY_LIMIT);
920        let mut msg = Self::default();
921        msg.merge(
922            buf,
923            DecodeContext::new(RECURSION_LIMIT, &limit).with_element_memory(&elem_budget),
924        )?;
925        Ok(msg)
926    }
927
928    /// Decode a message from a byte slice.
929    ///
930    /// Convenience wrapper around [`decode`](Self::decode) that avoids the
931    /// `&mut bytes.as_slice()` incantation.
932    fn decode_from_slice(mut data: &[u8]) -> Result<Self, DecodeError>
933    where
934        Self: Sized,
935    {
936        // `mut data` creates a local mutable copy of the fat pointer so that
937        // `Buf::advance` can move the read cursor without affecting the caller.
938        Self::decode(&mut data)
939    }
940
941    /// Decode a length-delimited message from a buffer.
942    ///
943    /// This is a **top-level** entry point.  It reads a varint length prefix,
944    /// then decodes using arithmetic bounds checking, calling
945    /// [`merge_to_limit`](Self::merge_to_limit) with a fresh
946    /// [`RECURSION_LIMIT`] budget.  Any sub-messages inside are decoded via
947    /// [`merge_length_delimited`](Self::merge_length_delimited), which tracks
948    /// and decrements the budget.
949    ///
950    /// Do **not** call this method from within a
951    /// [`merge_to_limit`](Self::merge_to_limit) implementation to decode a
952    /// nested sub-message field; use
953    /// [`merge_length_delimited`](Self::merge_length_delimited) instead so
954    /// that the caller's depth budget is propagated correctly.
955    fn decode_length_delimited(buf: &mut impl Buf) -> Result<Self, DecodeError>
956    where
957        Self: Sized,
958    {
959        // Refuse messages larger than 2 GiB to prevent allocating attacker-
960        // controlled amounts of memory from a crafted length prefix.
961        let len_u64 = crate::encoding::decode_varint(buf)?;
962        if len_u64 > MAX_MESSAGE_BYTES as u64 {
963            return Err(DecodeError::MessageTooLarge);
964        }
965        // Safe on 32-bit: len_u64 <= 2 GiB - 1 < u32::MAX, so the cast never truncates.
966        let len = usize::try_from(len_u64).map_err(|_| DecodeError::MessageTooLarge)?;
967        if buf.remaining() < len {
968            return Err(DecodeError::UnexpectedEof);
969        }
970        // Arithmetic limit: decode `len` bytes from the buffer without
971        // wrapping it in `Take`.  This keeps the buffer type `B` unchanged
972        // through every recursion level, avoiding E0275 for recursive
973        // message types like `google.protobuf.Struct ↔ Value`.
974        let limit = buf.remaining() - len;
975        let field_limit = core::cell::Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
976        let elem_budget = core::cell::Cell::new(DEFAULT_ELEMENT_MEMORY_LIMIT);
977        let mut msg = Self::default();
978        // Recorded here as well as by the default `merge_to_limit`, so an
979        // override that does not record it is still bounded by the frame.
980        msg.merge_to_limit(
981            buf,
982            DecodeContext::new(RECURSION_LIMIT, &field_limit)
983                .with_element_memory(&elem_budget)
984                .with_message_end(limit),
985            limit,
986        )?;
987        if buf.remaining() != limit {
988            let remaining = buf.remaining();
989            if remaining > limit {
990                buf.advance(remaining - limit);
991            } else {
992                return Err(DecodeError::UnexpectedEof);
993            }
994        }
995        Ok(msg)
996    }
997
998    /// Processes a single already-decoded tag and its associated field data
999    /// from `buf`.
1000    ///
1001    /// This is the per-field dispatch method generated for each message type.
1002    /// Both [`merge_to_limit`](Self::merge_to_limit) and
1003    /// [`merge_group`](Self::merge_group) call this in their respective loops.
1004    ///
1005    /// `ctx` carries the remaining nesting depth and the shared allocation
1006    /// budget.
1007    ///
1008    /// # Errors
1009    ///
1010    /// Returns a [`DecodeError`] if:
1011    /// - the buffer is truncated or malformed,
1012    /// - a wire-type mismatch is detected for a known field,
1013    /// - the recursion limit is exceeded, or
1014    /// - the allocation budget is exhausted.
1015    fn merge_field(
1016        &mut self,
1017        tag: crate::encoding::Tag,
1018        buf: &mut impl Buf,
1019        ctx: DecodeContext<'_>,
1020    ) -> Result<(), DecodeError>;
1021
1022    /// Merge fields from a buffer until `buf.remaining()` reaches `limit`.
1023    ///
1024    /// This is the core decode loop.  [`merge`](Self::merge) delegates to this
1025    /// with `limit = 0` (read until exhausted).
1026    /// [`merge_length_delimited`](Self::merge_length_delimited) computes
1027    /// `limit` from the declared sub-message length and calls this directly.
1028    ///
1029    /// The caller must ensure `limit <= buf.remaining()`.  The default
1030    /// implementations of [`merge`](Self::merge) and
1031    /// [`merge_length_delimited`](Self::merge_length_delimited) uphold this
1032    /// invariant.
1033    ///
1034    /// `ctx` carries the remaining nesting depth and the shared allocation
1035    /// budget.  Each call to
1036    /// [`merge_length_delimited`](Self::merge_length_delimited) consumes one
1037    /// depth level before recursing; when the depth reaches zero the call
1038    /// returns [`DecodeError::RecursionLimitExceeded`].  The default
1039    /// implementation records `limit` in `ctx` as the end of the message
1040    /// ([`DecodeContext::with_message_end`]), so a sub-message, map entry, or
1041    /// custom string or bytes field of it whose declared length runs past
1042    /// `limit` is rejected before it is decoded. Other fields are checked only
1043    /// against the buffer, so a caller passing `limit > 0` must still check
1044    /// that `buf.remaining() == limit` afterwards, as
1045    /// [`merge_length_delimited`](Self::merge_length_delimited) does. An
1046    /// override should record `limit` the same way; `merge_length_delimited`
1047    /// and the length-delimited decode entry points also record it before
1048    /// calling this, so an override called from them is bounded either way.
1049    fn merge_to_limit(
1050        &mut self,
1051        buf: &mut impl Buf,
1052        ctx: DecodeContext<'_>,
1053        limit: usize,
1054    ) -> Result<(), DecodeError> {
1055        let ctx = ctx.with_message_end(limit);
1056        while buf.remaining() > limit {
1057            let tag = crate::encoding::Tag::decode(buf)?;
1058            self.merge_field(tag, buf, ctx)?;
1059        }
1060        Ok(())
1061    }
1062
1063    /// Merges a group-encoded message from `buf`, reading fields until an
1064    /// EndGroup tag with the given `field_number` is encountered.
1065    ///
1066    /// Proto2 groups use StartGroup/EndGroup wire types instead of
1067    /// length-delimited encoding. The opening StartGroup tag has already been
1068    /// consumed by the caller; this method reads the group body and the
1069    /// closing EndGroup tag.
1070    ///
1071    /// # Errors
1072    ///
1073    /// Returns a [`DecodeError`] if:
1074    /// - the buffer is truncated before the EndGroup tag,
1075    /// - an EndGroup tag is encountered with a mismatched field number,
1076    /// - a wire-type mismatch is detected for a known field, or
1077    /// - the recursion limit is exceeded.
1078    fn merge_group(
1079        &mut self,
1080        buf: &mut impl Buf,
1081        ctx: DecodeContext<'_>,
1082        field_number: u32,
1083    ) -> Result<(), DecodeError> {
1084        let ctx = ctx.descend()?;
1085        loop {
1086            if !buf.has_remaining() {
1087                return Err(DecodeError::UnexpectedEof);
1088            }
1089            let tag = crate::encoding::Tag::decode(buf)?;
1090            if tag.wire_type() == crate::encoding::WireType::EndGroup {
1091                return if tag.field_number() == field_number {
1092                    Ok(())
1093                } else {
1094                    Err(DecodeError::InvalidEndGroup(tag.field_number()))
1095                };
1096            }
1097            self.merge_field(tag, buf, ctx)?;
1098        }
1099    }
1100
1101    /// Merge fields from a buffer into this message.
1102    ///
1103    /// Fields that are already set will be overwritten for singular fields,
1104    /// or appended for repeated fields, following standard protobuf merge
1105    /// semantics.
1106    ///
1107    /// `ctx` carries the remaining nesting depth and the shared allocation
1108    /// budget.  Each call to
1109    /// [`merge_length_delimited`](Self::merge_length_delimited) consumes one
1110    /// depth level before recursing; when the depth reaches zero the call
1111    /// returns [`DecodeError::RecursionLimitExceeded`].  Construct a fresh
1112    /// [`DecodeContext`] at the outermost call site, or use the convenience
1113    /// methods ([`decode`](Self::decode),
1114    /// [`merge_from_slice`](Self::merge_from_slice)) which do this
1115    /// automatically.
1116    fn merge(&mut self, buf: &mut impl Buf, ctx: DecodeContext<'_>) -> Result<(), DecodeError> {
1117        self.merge_to_limit(buf, ctx, 0)
1118    }
1119
1120    /// Merge fields from a byte slice into this message.
1121    ///
1122    /// Convenience wrapper around [`merge`](Self::merge) that avoids the
1123    /// `&mut bytes.as_slice()` incantation.
1124    fn merge_from_slice(&mut self, mut data: &[u8]) -> Result<(), DecodeError> {
1125        let limit = core::cell::Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
1126        let elem_budget = core::cell::Cell::new(DEFAULT_ELEMENT_MEMORY_LIMIT);
1127        self.merge(
1128            &mut data,
1129            DecodeContext::new(RECURSION_LIMIT, &limit).with_element_memory(&elem_budget),
1130        )
1131    }
1132
1133    /// Merge fields from a length-delimited sub-message payload into this message.
1134    ///
1135    /// Reads a varint length prefix, then calls [`merge_to_limit`](Self::merge_to_limit)
1136    /// with an arithmetic bound derived from the declared sub-message length.
1137    /// The buffer type `B` passes through unchanged at every recursion level,
1138    /// avoiding the `E0275` trait-solver recursion limit that occurs with
1139    /// `Take<&mut Take<&mut T>>` type growth.
1140    ///
1141    /// Used by generated code when decoding singular `MessageField<T>` fields
1142    /// — the sub-message is merged into the existing value rather than
1143    /// replaced, per protobuf merge semantics.
1144    ///
1145    /// `ctx` carries the remaining nesting depth and the shared allocation
1146    /// budget passed down from the enclosing
1147    /// [`merge_to_limit`](Self::merge_to_limit) call.  This method consumes
1148    /// one depth level before calling the inner `merge_to_limit`; when the
1149    /// depth reaches zero it returns
1150    /// [`DecodeError::RecursionLimitExceeded`].
1151    ///
1152    /// Enforces the same 2 GiB safety limit as [`decode_length_delimited`](Self::decode_length_delimited).
1153    ///
1154    /// # Errors
1155    ///
1156    /// Returns an error if the buffer is too short or the declared length runs
1157    /// past the end of the message being decoded with `ctx` (both
1158    /// [`DecodeError::UnexpectedEof`]), if the declared length exceeds 2 GiB,
1159    /// if the recursion limit is reached, or if the inner `merge_to_limit`
1160    /// call fails.
1161    fn merge_length_delimited(
1162        &mut self,
1163        buf: &mut impl Buf,
1164        ctx: DecodeContext<'_>,
1165    ) -> Result<(), DecodeError> {
1166        let ctx = ctx.descend()?;
1167        let len_u64 = crate::encoding::decode_varint(buf)?;
1168        if len_u64 > MAX_MESSAGE_BYTES as u64 {
1169            return Err(DecodeError::MessageTooLarge);
1170        }
1171        let len = usize::try_from(len_u64).map_err(|_| DecodeError::MessageTooLarge)?;
1172        // The sub-message must also end within the message that holds it.
1173        ctx.check_len(buf.remaining(), len)?;
1174        // Arithmetic limit: the sub-message occupies `len` bytes, so the
1175        // decode loop should stop when `buf.remaining()` drops to
1176        // `remaining - len`.  This avoids wrapping the buffer in `Take`,
1177        // which would grow the type at each recursion level and trigger
1178        // E0275 for recursive message types like `Struct ↔ Value`.
1179        let limit = buf.remaining() - len;
1180        // Recorded here as well as by the default `merge_to_limit`, so an
1181        // override that does not record it is still bounded by the sub-message.
1182        self.merge_to_limit(buf, ctx.with_message_end(limit), limit)?;
1183        if buf.remaining() != limit {
1184            let remaining = buf.remaining();
1185            if remaining > limit {
1186                // Sub-message consumed fewer bytes than declared; skip the rest.
1187                buf.advance(remaining - limit);
1188            } else {
1189                return Err(DecodeError::UnexpectedEof);
1190            }
1191        }
1192        Ok(())
1193    }
1194
1195    /// Clear all fields to their default values.
1196    fn clear(&mut self);
1197}
1198
1199/// Compile-time access to a generated message's protobuf identifiers.
1200///
1201/// Generic code that needs to *name* a message type — type-erased event
1202/// registries, structured logging, `Any` packing, schema lookups — can
1203/// bound on `T: MessageName` and read [`PACKAGE`], [`NAME`],
1204/// [`FULL_NAME`], or [`TYPE_URL`] without descriptor machinery or runtime
1205/// reflection. All four are `&'static str` literals computed at codegen
1206/// time, so there's no allocation or concatenation at runtime — unlike
1207/// `prost::Name`, whose `full_name()` and `type_url()` are runtime
1208/// `format!` calls.
1209///
1210/// Bring `buffa::MessageName` into scope to use `MyMessage::FULL_NAME`.
1211/// Without the trait in scope, use
1212/// `<MyMessage as buffa::MessageName>::FULL_NAME`.
1213///
1214/// Codegen implements `MessageName` for both the owned message type and
1215/// its zero-copy view type (`MyMessageView<'a>`), so the same generic
1216/// bound dispatches either. The trait has **no** [`Message`] supertrait —
1217/// it doesn't reach into the wire codec and a name-keyed registry should
1218/// be able to register a type without proving it can encode.
1219///
1220/// Hand-written [`Message`] implementations can opt in by also
1221/// implementing `MessageName`; it is a separate trait specifically so
1222/// that omitting it stays non-breaking. For messages that also implement
1223/// [`ExtensionSet`](crate::ExtensionSet), [`FULL_NAME`] is guaranteed
1224/// equal to [`ExtensionSet::PROTO_FQN`](crate::ExtensionSet::PROTO_FQN);
1225/// the inherent `MyMessage::TYPE_URL` const is equal to [`TYPE_URL`].
1226/// All derive from the same `proto_fqn` source in codegen.
1227///
1228/// Because the only items are associated `const`s, this trait is **not**
1229/// object-safe (`dyn MessageName` does not compile). Use it as a generic
1230/// bound (`fn foo<T: MessageName>()`), not a trait object.
1231///
1232/// ```
1233/// # use buffa::MessageName;
1234/// /// A name-keyed registry can register any `MessageName` type — owned
1235/// /// or view — without proving it can encode.
1236/// fn registry_key<T: MessageName>() -> &'static str {
1237///     T::FULL_NAME
1238/// }
1239/// # // No generated types in `buffa` itself; just check it monomorphises.
1240/// # struct Demo;
1241/// # impl MessageName for Demo {
1242/// #     const PACKAGE: &'static str = "demo";
1243/// #     const NAME: &'static str = "Demo";
1244/// #     const FULL_NAME: &'static str = "demo.Demo";
1245/// #     const TYPE_URL: &'static str = "type.googleapis.com/demo.Demo";
1246/// # }
1247/// assert_eq!(registry_key::<Demo>(), "demo.Demo");
1248/// ```
1249///
1250/// [`PACKAGE`]: Self::PACKAGE
1251/// [`NAME`]: Self::NAME
1252/// [`FULL_NAME`]: Self::FULL_NAME
1253/// [`TYPE_URL`]: Self::TYPE_URL
1254pub trait MessageName {
1255    /// The protobuf package the message is declared in.
1256    ///
1257    /// `"my.pkg"` for `package my.pkg;`. Empty string for the unnamed
1258    /// root package. Does not include a leading or trailing dot.
1259    const PACKAGE: &'static str;
1260
1261    /// The unqualified message name, with `.` between nesting levels.
1262    ///
1263    /// `"Foo"` for a top-level message; `"Outer.Inner"` for a message
1264    /// nested inside `Outer`. This is the "type name relative to the
1265    /// package" — what `prost::Name::NAME` calls the same thing — *not*
1266    /// `DescriptorProto.name`, which is only the leaf segment (`"Inner"`)
1267    /// for nested types.
1268    const NAME: &'static str;
1269
1270    /// The fully-qualified protobuf type name with no leading dot.
1271    ///
1272    /// `"my.pkg.Outer.Inner"` for a nested message in package `my.pkg`,
1273    /// or just `"Foo"` for a top-level message in the unnamed root
1274    /// package. Equal to `PACKAGE` + `"."` + `NAME` (with the joining
1275    /// dot omitted when `PACKAGE` is empty); shipped as its own const
1276    /// because consumers almost always want the joined form and the
1277    /// dotted string can't be re-split unambiguously
1278    /// (`foo.Bar.Baz` could be package `foo.Bar` + message `Baz`, or
1279    /// package `foo` + nested `Bar.Baz`).
1280    const FULL_NAME: &'static str;
1281
1282    /// The `google.protobuf.Any.type_url` form for this message.
1283    ///
1284    /// `"type.googleapis.com/" + FULL_NAME`. This is the value the
1285    /// runtime stores in [`Any::type_url`] when packing a message, and
1286    /// the one a generic `Any` registry should key on.
1287    ///
1288    /// [`Any::type_url`]: https://protobuf.dev/programming-guides/proto3/#any
1289    const TYPE_URL: &'static str;
1290}
1291
1292/// Options for configuring message decoding behavior.
1293///
1294/// Use this to set custom recursion depth limits or maximum message sizes
1295/// when decoding from untrusted input.
1296///
1297/// # Scope: the protobuf binary codec
1298///
1299/// Every limit here bounds the binary decoders — owned, view, and the
1300/// reflective `DynamicMessage` codec — and only those. Decoding the same
1301/// message from JSON goes through `serde_json` (or another `Deserializer`)
1302/// straight into the generated `Deserialize` impls, which never see a
1303/// `DecodeOptions`, so none of these limits apply to it. JSON input that must
1304/// be bounded needs a bound imposed by the caller, for example by capping the
1305/// input length before parsing.
1306///
1307/// One JSON path applies an element-memory limit of its own:
1308/// `buffa_descriptor`'s reflective parser (`DynamicMessage::from_json`)
1309/// charges the repeated elements and map entries it builds against a limit
1310/// that defaults to [`DEFAULT_ELEMENT_MEMORY_LIMIT`] and is changed with
1311/// `buffa_descriptor::DynamicMessageSeed::with_element_memory_limit`, not
1312/// here. The parser also charges that limit for the buffer it reads a
1313/// `google.protobuf.Any` payload into, until it has decoded the payload.
1314///
1315/// # Examples
1316///
1317/// ```no_run
1318/// # use buffa::__doctest_fixtures::Person;
1319/// use buffa::DecodeOptions;
1320///
1321/// # fn example(bytes: &[u8]) -> Result<(), buffa::DecodeError> {
1322/// // Restrict recursion depth to 50 and message size to 1 MiB:
1323/// let msg: Person = DecodeOptions::new()
1324///     .with_recursion_limit(50)
1325///     .with_max_message_size(1024 * 1024)
1326///     .decode_from_slice(bytes)?;
1327/// # Ok(())
1328/// # }
1329/// ```
1330#[derive(Debug, Clone)]
1331pub struct DecodeOptions {
1332    recursion_limit: u32,
1333    max_message_size: usize,
1334    unbounded_reader_size: bool,
1335    unknown_field_limit: usize,
1336    element_memory_limit: usize,
1337    clear_on_merge_error: bool,
1338}
1339
1340/// Default maximum message size: 2 GiB - 1 (matches the sub-message limit
1341/// in `merge_length_delimited` and the encode-side limit — see
1342/// [`MAX_MESSAGE_BYTES`]).
1343const DEFAULT_MAX_MESSAGE_SIZE: usize = MAX_MESSAGE_BYTES as usize;
1344
1345impl Default for DecodeOptions {
1346    fn default() -> Self {
1347        Self::new()
1348    }
1349}
1350
1351impl DecodeOptions {
1352    /// Create new decode options with defaults.
1353    ///
1354    /// Defaults:
1355    /// - `recursion_limit`: 100 (same as [`RECURSION_LIMIT`])
1356    /// - `max_message_size`: 2 GiB - 1
1357    /// - `unknown_field_limit`: 1,000,000 (same as [`DEFAULT_UNKNOWN_FIELD_LIMIT`])
1358    /// - `element_memory_limit`: 32 MiB (same as [`DEFAULT_ELEMENT_MEMORY_LIMIT`])
1359    pub fn new() -> Self {
1360        Self {
1361            recursion_limit: RECURSION_LIMIT,
1362            max_message_size: DEFAULT_MAX_MESSAGE_SIZE,
1363            unbounded_reader_size: false,
1364            unknown_field_limit: DEFAULT_UNKNOWN_FIELD_LIMIT,
1365            element_memory_limit: DEFAULT_ELEMENT_MEMORY_LIMIT,
1366            clear_on_merge_error: false,
1367        }
1368    }
1369
1370    /// Set the maximum recursion depth for nested messages.
1371    ///
1372    /// Each nested sub-message consumes one level of depth budget. When
1373    /// the budget reaches zero, decoding returns
1374    /// [`DecodeError::RecursionLimitExceeded`].
1375    ///
1376    /// Default: 100.
1377    #[must_use]
1378    pub fn with_recursion_limit(mut self, limit: u32) -> Self {
1379        self.recursion_limit = limit;
1380        self
1381    }
1382
1383    /// Set the maximum total message size in bytes.
1384    ///
1385    /// If the input buffer or length-delimited payload exceeds this size,
1386    /// decoding returns [`DecodeError::MessageTooLarge`].
1387    ///
1388    /// Values above the protobuf message-size limit (2 GiB - 1) are clamped to
1389    /// that limit. Debug builds assert on out-of-range values so accidental
1390    /// `usize::MAX` sentinels are caught during development. On `std` builds,
1391    /// use `without_reader_size_limit` when EOF-bounded `decode_reader` input
1392    /// intentionally has no byte cap.
1393    ///
1394    /// Calling this re-enables the reader byte cap, overriding any prior
1395    /// `without_reader_size_limit`.
1396    ///
1397    /// This is checked at the top-level decode entry point. Individual
1398    /// sub-messages are still bounded by the internal 2 GiB limit
1399    /// regardless of this setting.
1400    ///
1401    /// Default: 2 GiB - 1 (0x7FFF_FFFF).
1402    #[must_use]
1403    pub fn with_max_message_size(mut self, max_bytes: usize) -> Self {
1404        debug_assert!(
1405            max_bytes <= DEFAULT_MAX_MESSAGE_SIZE,
1406            "DecodeOptions::with_max_message_size clamps values above the protobuf 2 GiB limit; \
1407             on std builds, use DecodeOptions::without_reader_size_limit for intentionally \
1408             unbounded reader input — there is no unbounded slice/Buf path"
1409        );
1410        self.max_message_size = max_bytes.min(DEFAULT_MAX_MESSAGE_SIZE);
1411        self.unbounded_reader_size = false;
1412        self
1413    }
1414
1415    /// Remove the byte cap for EOF-bounded [`decode_reader`](Self::decode_reader)
1416    /// input.
1417    ///
1418    /// This is only used by the `std::io::Read` entry point that reads until
1419    /// EOF. Slice-, [`Buf`]-, and view-based entry points remain bounded by
1420    /// the configured [`with_max_message_size`](Self::with_max_message_size)
1421    /// (itself capped at the protobuf 2 GiB - 1 maximum), and length-delimited
1422    /// paths keep the same hard cap because their declared length is
1423    /// attacker-controlled.
1424    ///
1425    /// An unbounded reader can exhaust memory if the source does not end or is
1426    /// larger than available allocation capacity. Prefer
1427    /// [`with_max_message_size`](Self::with_max_message_size) for untrusted
1428    /// input.
1429    #[cfg(feature = "std")]
1430    #[must_use]
1431    pub fn without_reader_size_limit(mut self) -> Self {
1432        self.unbounded_reader_size = true;
1433        self
1434    }
1435
1436    /// Set the maximum number of unknown fields decoded per decode call.
1437    ///
1438    /// Preserved unknown fields consume this allowance. A zero allowance also
1439    /// rejects discarded unknown wire fields regardless of storage configuration.
1440    /// Positive limits retain their storage-budget semantics.
1441    ///
1442    /// Each preserved unknown field occupies a ~40-byte
1443    /// [`UnknownField`](crate::UnknownField) slot regardless of its wire
1444    /// size (a minimal field is 2 wire bytes — a ~20× amplification), so an
1445    /// input-size cap alone does not bound decoder memory; this limit does,
1446    /// at roughly `limit × 40` bytes of slot overhead. Unknown
1447    /// length-delimited *payload* bytes are not counted — they are bounded
1448    /// by the input size, which
1449    /// [`with_max_message_size`](Self::with_max_message_size) governs. When
1450    /// the limit is exceeded, decoding returns
1451    /// [`DecodeError::UnknownFieldLimitExceeded`].
1452    ///
1453    /// Zero-copy view decoding ([`decode_view`](Self::decode_view)) charges
1454    /// one slot per unknown field — including fields nested inside unknown
1455    /// groups — even though views store unknown fields as coalesced spans
1456    /// (~16 bytes per contiguous run): coalescing bounds view memory, while
1457    /// this limit bounds what converting the view to an owned message would
1458    /// materialize. Conversion replays under exactly the budget decoding
1459    /// charged, so a view that decodes within this limit always converts.
1460    ///
1461    /// Default: 1,000,000 ([`DEFAULT_UNKNOWN_FIELD_LIMIT`]).
1462    #[must_use]
1463    pub fn with_unknown_field_limit(mut self, count: usize) -> Self {
1464        self.unknown_field_limit = count;
1465        self
1466    }
1467
1468    /// Reject unknown wire fields independently of generated storage settings.
1469    /// Equivalent to a zero unknown-field allowance. Unknown closed-enum values
1470    /// are included; open-enum numbers remain valid values of known fields.
1471    /// Generated static messages retain extensions, MessageSet items and custom
1472    /// descriptor options as unknown fields, so they are rejected too. A dynamic
1473    /// message can recognize extensions registered in its descriptor pool.
1474    ///
1475    /// Deferred lazy children are checked only when materialized: constructing a
1476    /// lazy view alone does not establish rejection throughout its subtree.
1477    #[must_use]
1478    pub fn reject_unknown_fields(self) -> Self {
1479        self.with_unknown_field_limit(0)
1480    }
1481
1482    /// Set the memory this decode may materialize in the elements of
1483    /// length-delimited containers — repeated message, string and bytes fields,
1484    /// and map entries — shared across the whole decode tree rather than per
1485    /// field or per message.
1486    ///
1487    /// The lazy view family is the exception: there the budget is replayed
1488    /// per deferred subtree rather than shared, so a full traversal can
1489    /// spend it more than once. See
1490    /// [`decode_lazy_view`](Self::decode_lazy_view).
1491    ///
1492    /// This is not [`with_max_message_size`](Self::with_max_message_size) by
1493    /// another name: that bounds the bytes going *in*, this bounds what they
1494    /// expand *into*. They are not redundant, because the two are not
1495    /// proportional — an empty repeated message element is 2 wire bytes and
1496    /// `size_of::<T>()` of `Vec` footprint (measured at 256 bytes for a message
1497    /// of a few `Vec`/`String` fields), so a payload well inside any input
1498    /// bound can still materialize 128x its own size. Charging is by element
1499    /// footprint, so a budget means the same amount of memory whatever the
1500    /// element size — which a count limit could not offer.
1501    ///
1502    /// Packed scalar fields are not charged by the generated or view
1503    /// decoders, but are by the reflective `DynamicMessage` codec; see
1504    /// [`DEFAULT_ELEMENT_MEMORY_LIMIT`] for why, and for the `Vec`-doubling
1505    /// caveat on peak memory.
1506    ///
1507    /// Like every option on [`DecodeOptions`], this bounds the binary decoders
1508    /// only. The textproto parser applies the same default through its own
1509    /// knob,
1510    /// [`TextDecoder::with_element_memory_limit`](crate::text::TextDecoder::with_element_memory_limit).
1511    /// The same message decoded from JSON into a generated type is not
1512    /// charged against this budget, and the amplification it guards against
1513    /// is very nearly as large there — `{}` is three JSON bytes for the same
1514    /// element footprint. The reflective JSON parser in `buffa_descriptor`
1515    /// applies the same default, changed with
1516    /// `buffa_descriptor::DynamicMessageSeed::with_element_memory_limit`.
1517    ///
1518    /// Default: 32 MiB ([`DEFAULT_ELEMENT_MEMORY_LIMIT`]).
1519    #[must_use]
1520    pub fn with_element_memory_limit(mut self, bytes: usize) -> Self {
1521        self.element_memory_limit = bytes;
1522        self
1523    }
1524
1525    /// Returns the configured element-memory budget.
1526    #[must_use]
1527    pub fn element_memory_limit(&self) -> usize {
1528        self.element_memory_limit
1529    }
1530
1531    /// Returns the configured recursion depth limit.
1532    pub fn recursion_limit(&self) -> u32 {
1533        self.recursion_limit
1534    }
1535
1536    /// Returns the configured unknown-field limit.
1537    pub fn unknown_field_limit(&self) -> usize {
1538        self.unknown_field_limit
1539    }
1540
1541    /// Returns the configured maximum message size in bytes for bounded decode
1542    /// entry points.
1543    ///
1544    /// This returns the configured (clamped) value even when
1545    /// `without_reader_size_limit` is enabled for EOF-bounded reader input —
1546    /// the slice/`Buf`/view paths still honor it. Use
1547    /// `is_reader_size_unbounded` (std only) to inspect the reader flag.
1548    pub fn max_message_size(&self) -> usize {
1549        self.max_message_size
1550    }
1551
1552    /// Returns whether EOF-bounded reader input has no byte cap.
1553    #[cfg(feature = "std")]
1554    pub fn is_reader_size_unbounded(&self) -> bool {
1555        self.unbounded_reader_size
1556    }
1557
1558    /// Returns whether a failed merge clears the destination message.
1559    ///
1560    /// See [`Self::with_clear_on_merge_error`].
1561    #[must_use]
1562    pub fn clears_on_merge_error(&self) -> bool {
1563        self.clear_on_merge_error
1564    }
1565
1566    /// Decode a message from a buffer.
1567    pub fn decode<M: Message>(&self, buf: &mut impl Buf) -> Result<M, DecodeError> {
1568        if buf.remaining() > self.max_message_size {
1569            return Err(DecodeError::MessageTooLarge);
1570        }
1571        let limit = core::cell::Cell::new(self.unknown_field_limit);
1572        let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1573        let mut msg = M::default();
1574        msg.merge(
1575            buf,
1576            DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1577        )?;
1578        Ok(msg)
1579    }
1580
1581    /// Decode a message from a byte slice.
1582    pub fn decode_from_slice<M: Message>(&self, data: &[u8]) -> Result<M, DecodeError> {
1583        if data.len() > self.max_message_size {
1584            return Err(DecodeError::MessageTooLarge);
1585        }
1586        self.decode_from_slice_unchecked_size(data)
1587    }
1588
1589    fn decode_from_slice_unchecked_size<M: Message>(&self, data: &[u8]) -> Result<M, DecodeError> {
1590        let limit = core::cell::Cell::new(self.unknown_field_limit);
1591        let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1592        let mut msg = M::default();
1593        msg.merge(
1594            &mut &*data,
1595            DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1596        )?;
1597        Ok(msg)
1598    }
1599
1600    /// Decode a length-delimited message from a buffer.
1601    pub fn decode_length_delimited<M: Message>(
1602        &self,
1603        buf: &mut impl Buf,
1604    ) -> Result<M, DecodeError> {
1605        // Enforce the 2 GiB internal safety cap even if the user sets a
1606        // larger max_message_size, to prevent allocating attacker-controlled
1607        // amounts of memory from a crafted length prefix.
1608        let max = core::cmp::min(
1609            self.max_message_size as u64,
1610            DEFAULT_MAX_MESSAGE_SIZE as u64,
1611        );
1612        let len_u64 = crate::encoding::decode_varint(buf)?;
1613        if len_u64 > max {
1614            return Err(DecodeError::MessageTooLarge);
1615        }
1616        let len = usize::try_from(len_u64).map_err(|_| DecodeError::MessageTooLarge)?;
1617        if buf.remaining() < len {
1618            return Err(DecodeError::UnexpectedEof);
1619        }
1620        let limit = buf.remaining() - len;
1621        let field_limit = core::cell::Cell::new(self.unknown_field_limit);
1622        let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1623        let mut msg = M::default();
1624        // Recorded here as well as by the default `merge_to_limit`, so an
1625        // override that does not record it is still bounded by the frame.
1626        msg.merge_to_limit(
1627            buf,
1628            DecodeContext::new(self.recursion_limit, &field_limit)
1629                .with_element_memory(&elem_budget)
1630                .with_message_end(limit),
1631            limit,
1632        )?;
1633        if buf.remaining() != limit {
1634            let remaining = buf.remaining();
1635            if remaining > limit {
1636                buf.advance(remaining - limit);
1637            } else {
1638                return Err(DecodeError::UnexpectedEof);
1639            }
1640        }
1641        Ok(msg)
1642    }
1643
1644    /// Enable clearing the destination when a merge returns an error.
1645    ///
1646    /// Equivalent to [`Self::with_clear_on_merge_error`] with `true`. See that
1647    /// method for the cleanup and input-buffer guarantees.
1648    #[must_use]
1649    pub fn clear_on_merge_error(self) -> Self {
1650        self.with_clear_on_merge_error(true)
1651    }
1652
1653    /// Set whether a merge error clears the entire destination, including
1654    /// when the input exceeds the message size limit. Disabled by default.
1655    ///
1656    /// Use this when a failed merge must not leave old values or a partially
1657    /// merged message available to the caller. Passing `false` restores the
1658    /// normal partial-merge behavior, including on a cloned configuration.
1659    ///
1660    /// This option applies to [`Self::merge`] and [`Self::merge_from_slice`],
1661    /// which call [`Message::clear`], so memory is wiped only if the message's
1662    /// implementation wipes its fields. It also applies to
1663    /// `buffa_descriptor::reflect::DynamicMessage::merge_with_options`, which
1664    /// removes every set and unknown field without wiping memory. Backing
1665    /// storage may be retained.
1666    ///
1667    /// The typed decode methods on `DecodeOptions` do not apply this policy.
1668    /// `DynamicMessage::decode_with_options` delegates to its merge method,
1669    /// so it applies the policy to its temporary destination on error; it
1670    /// still returns no message and provides no memory-wiping guarantee.
1671    ///
1672    /// The caller's input is not wiped. A failed buffer merge may already
1673    /// have consumed bytes; clearing does not rewind that buffer.
1674    #[must_use]
1675    pub fn with_clear_on_merge_error(mut self, enabled: bool) -> Self {
1676        self.clear_on_merge_error = enabled;
1677        self
1678    }
1679
1680    /// Merge fields from a buffer into an existing message.
1681    ///
1682    /// On error the destination can contain old and partially merged fields,
1683    /// unless [`Self::clear_on_merge_error`] was requested. Buffer consumption
1684    /// is not rolled back on failure, regardless of the clearing policy.
1685    pub fn merge<M: Message>(&self, msg: &mut M, buf: &mut impl Buf) -> Result<(), DecodeError> {
1686        let result = if buf.remaining() > self.max_message_size {
1687            Err(DecodeError::MessageTooLarge)
1688        } else {
1689            let limit = core::cell::Cell::new(self.unknown_field_limit);
1690            let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1691            msg.merge(
1692                buf,
1693                DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1694            )
1695        };
1696        if self.clear_on_merge_error && result.is_err() {
1697            msg.clear();
1698        }
1699        result
1700    }
1701
1702    /// Merge fields from a byte slice into an existing message.
1703    ///
1704    /// The destination follows the same failure policy as [`Self::merge`].
1705    pub fn merge_from_slice<M: Message>(
1706        &self,
1707        msg: &mut M,
1708        mut data: &[u8],
1709    ) -> Result<(), DecodeError> {
1710        self.merge(msg, &mut data)
1711    }
1712
1713    /// Decode a zero-copy view from a byte slice.
1714    ///
1715    /// Enforces `max_message_size` on the input, and passes the recursion
1716    /// limit, unknown-field limit, and element-memory budget to the view
1717    /// decoder (views charge the unknown-field limit per field, including
1718    /// fields nested in unknown groups — see
1719    /// [`with_unknown_field_limit`](Self::with_unknown_field_limit)).
1720    ///
1721    /// # Errors
1722    ///
1723    /// Returns [`DecodeError::MessageTooLarge`] for oversized input, or any
1724    /// error from the view decoder (malformed wire data,
1725    /// [`DecodeError::RecursionLimitExceeded`],
1726    /// [`DecodeError::UnknownFieldLimitExceeded`], or
1727    /// [`DecodeError::ElementMemoryLimitExceeded`]).
1728    pub fn decode_view<'a, V: crate::view::MessageView<'a>>(
1729        &self,
1730        buf: &'a [u8],
1731    ) -> Result<V, DecodeError> {
1732        if buf.len() > self.max_message_size {
1733            return Err(DecodeError::MessageTooLarge);
1734        }
1735        let limit = core::cell::Cell::new(self.unknown_field_limit);
1736        let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1737        V::decode_view_with_ctx(
1738            buf,
1739            DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1740        )
1741    }
1742
1743    /// Decode a lazy view from a byte slice (see
1744    /// [`LazyMessageView`](crate::view::LazyMessageView)).
1745    ///
1746    /// The budgets remaining at each deferred field's position are recorded
1747    /// and charged when that field is accessed, so the configured limits
1748    /// flow through deferred decoding. Unlike
1749    /// [`decode_view`](Self::decode_view), the unknown-field and
1750    /// element-memory limits are not enforced globally across the message
1751    /// tree at decode time: each deferred subtree independently replays the
1752    /// budgets recorded at its position, so a full traversal can materialize
1753    /// records proportional to input size. Prefer `decode_view` for
1754    /// untrusted input if the global bound matters.
1755    ///
1756    /// # Errors
1757    ///
1758    /// Returns [`DecodeError::MessageTooLarge`] for oversized input, or any
1759    /// error from decoding the message's own fields — including
1760    /// [`DecodeError::RecursionLimitExceeded`],
1761    /// [`DecodeError::UnknownFieldLimitExceeded`], or
1762    /// [`DecodeError::ElementMemoryLimitExceeded`] when the configured limits
1763    /// are exhausted by them. Deferred sub-message bytes surface errors on
1764    /// access instead.
1765    pub fn decode_lazy_view<'a, L: crate::view::LazyMessageView<'a>>(
1766        &self,
1767        buf: &'a [u8],
1768    ) -> Result<L, DecodeError> {
1769        if buf.len() > self.max_message_size {
1770            return Err(DecodeError::MessageTooLarge);
1771        }
1772        let limit = core::cell::Cell::new(self.unknown_field_limit);
1773        let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1774        L::decode_lazy_with_ctx(
1775            buf,
1776            DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1777        )
1778    }
1779
1780    /// Decode a message by reading all bytes from a [`std::io::Read`] source.
1781    ///
1782    /// Reads until EOF, enforces the configured reader size limit unless
1783    /// [`without_reader_size_limit`](Self::without_reader_size_limit) was
1784    /// selected, then decodes the buffered bytes. Returns `std::io::Error` to
1785    /// be compatible with `Read`-based error handling.
1786    #[cfg(feature = "std")]
1787    pub fn decode_reader<M: Message>(
1788        &self,
1789        reader: &mut impl std::io::Read,
1790    ) -> Result<M, std::io::Error> {
1791        let bytes = self.read_limited(reader)?;
1792        self.decode_from_slice_unchecked_size::<M>(&bytes)
1793            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))
1794    }
1795
1796    /// Decode a length-delimited message from a [`std::io::Read`] source.
1797    ///
1798    /// Reads a varint length prefix, enforces `max_message_size`, reads
1799    /// exactly that many bytes, then decodes. Useful for reading sequential
1800    /// length-delimited messages from a file or stream.
1801    ///
1802    /// The declared length is treated as untrusted: the read buffer grows
1803    /// as bytes actually arrive rather than being allocated up front, so a
1804    /// source that declares a large length but never delivers the bytes
1805    /// cannot force a large allocation.
1806    #[cfg(feature = "std")]
1807    pub fn decode_length_delimited_reader<M: Message>(
1808        &self,
1809        reader: &mut impl std::io::Read,
1810    ) -> Result<M, std::io::Error> {
1811        use std::io::Read as _;
1812        let len = read_varint(reader)?;
1813        let max = core::cmp::min(
1814            self.max_message_size as u64,
1815            DEFAULT_MAX_MESSAGE_SIZE as u64,
1816        );
1817        if len > max {
1818            return Err(std::io::Error::new(
1819                std::io::ErrorKind::InvalidData,
1820                DecodeError::MessageTooLarge,
1821            ));
1822        }
1823        let len = usize::try_from(len).map_err(|_| {
1824            std::io::Error::new(
1825                std::io::ErrorKind::InvalidData,
1826                DecodeError::MessageTooLarge,
1827            )
1828        })?;
1829        // Pre-size only up to a small bound; `read_to_end` grows the buffer
1830        // geometrically as data is actually delivered, so peak allocation
1831        // tracks delivered bytes, not the wire-declared length.
1832        const INITIAL_CAPACITY_CAP: usize = 64 * 1024;
1833        let mut buf = alloc::vec::Vec::with_capacity(len.min(INITIAL_CAPACITY_CAP));
1834        reader.take(len as u64).read_to_end(&mut buf)?;
1835        if buf.len() < len {
1836            return Err(std::io::Error::new(
1837                std::io::ErrorKind::UnexpectedEof,
1838                DecodeError::UnexpectedEof,
1839            ));
1840        }
1841        self.decode_from_slice::<M>(&buf)
1842            .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))
1843    }
1844
1845    /// Read all bytes from a reader up to the configured reader limit.
1846    #[cfg(feature = "std")]
1847    fn read_limited(
1848        &self,
1849        reader: &mut impl std::io::Read,
1850    ) -> Result<alloc::vec::Vec<u8>, std::io::Error> {
1851        use std::io::Read as _;
1852        let mut buf = alloc::vec::Vec::new();
1853        if self.unbounded_reader_size {
1854            reader.read_to_end(&mut buf)?;
1855            return Ok(buf);
1856        }
1857        reader
1858            .take((self.max_message_size as u64).saturating_add(1))
1859            .read_to_end(&mut buf)?;
1860        if buf.len() > self.max_message_size {
1861            return Err(std::io::Error::new(
1862                std::io::ErrorKind::InvalidData,
1863                DecodeError::MessageTooLarge,
1864            ));
1865        }
1866        Ok(buf)
1867    }
1868}
1869
1870/// Read a varint from a `std::io::Read` source, one byte at a time.
1871///
1872/// Mirrors the validation in [`decode_varint_slow`](crate::encoding): a
1873/// 10th byte > `0x01` (overflow bits set, or continuation bit implying an
1874/// 11th byte) is rejected.
1875#[cfg(feature = "std")]
1876fn read_varint(reader: &mut impl std::io::Read) -> Result<u64, std::io::Error> {
1877    let mut value: u64 = 0;
1878    let mut shift: u32 = 0;
1879    loop {
1880        let mut byte = [0u8; 1];
1881        reader.read_exact(&mut byte)?;
1882        let b = byte[0];
1883        if shift < 63 {
1884            value |= ((b & 0x7F) as u64) << shift;
1885            if b < 0x80 {
1886                return Ok(value);
1887            }
1888            shift += 7;
1889        } else {
1890            // 10th byte: only bit 0 maps to bit 63 of the result. A byte
1891            // > 0x01 means either data overflow (bits 1-6 set) or an 11th
1892            // byte (continuation bit 0x80 set).
1893            if b > 0x01 {
1894                return Err(std::io::Error::new(
1895                    std::io::ErrorKind::InvalidData,
1896                    DecodeError::VarintTooLong,
1897                ));
1898            }
1899            value |= (b as u64) << 63;
1900            return Ok(value);
1901        }
1902    }
1903}
1904
1905#[cfg(test)]
1906mod tests {
1907    use super::*;
1908    use crate::encoding::encode_varint;
1909    use crate::error::DecodeError;
1910    use crate::message_field::DefaultInstance;
1911    use crate::SizeCache;
1912
1913    // Minimal hand-written Message for testing merge_length_delimited.
1914    #[derive(Clone, Debug, Default, PartialEq)]
1915    struct FlatMsg {
1916        value: i32,
1917    }
1918
1919    impl DefaultInstance for FlatMsg {
1920        fn default_instance() -> &'static Self {
1921            static INST: crate::__private::OnceBox<FlatMsg> = crate::__private::OnceBox::new();
1922            INST.get_or_init(|| alloc::boxed::Box::new(FlatMsg::default()))
1923        }
1924    }
1925
1926    impl Message for FlatMsg {
1927        fn compute_size(&self, _cache: &mut SizeCache) -> u32 {
1928            if self.value != 0 {
1929                1 + crate::types::int32_encoded_len(self.value) as u32
1930            } else {
1931                0
1932            }
1933        }
1934
1935        fn write_to(&self, _cache: &mut SizeCache, buf: &mut impl EncodeSink) {
1936            if self.value != 0 {
1937                crate::encoding::Tag::new(1, crate::encoding::WireType::Varint).encode(buf);
1938                crate::types::encode_int32(self.value, buf);
1939            }
1940        }
1941
1942        fn merge_field(
1943            &mut self,
1944            tag: crate::encoding::Tag,
1945            buf: &mut impl Buf,
1946            _ctx: DecodeContext<'_>,
1947        ) -> Result<(), DecodeError> {
1948            match tag.field_number() {
1949                1 => {
1950                    self.value = crate::types::decode_int32(buf)?;
1951                }
1952                _ => {
1953                    crate::encoding::skip_field(tag, buf)?;
1954                }
1955            }
1956            Ok(())
1957        }
1958
1959        fn clear(&mut self) {
1960            *self = Self::default();
1961        }
1962    }
1963
1964    /// A message whose `merge_to_limit` override does not record its limit,
1965    /// and whose `merge_field` reports the end its context carries.
1966    #[derive(Clone, Debug, Default, PartialEq)]
1967    struct OverrideMsg {
1968        seen_end: Option<usize>,
1969    }
1970
1971    impl DefaultInstance for OverrideMsg {
1972        fn default_instance() -> &'static Self {
1973            static INST: crate::__private::OnceBox<OverrideMsg> = crate::__private::OnceBox::new();
1974            INST.get_or_init(|| alloc::boxed::Box::new(OverrideMsg::default()))
1975        }
1976    }
1977
1978    impl Message for OverrideMsg {
1979        fn compute_size(&self, _cache: &mut SizeCache) -> u32 {
1980            0
1981        }
1982
1983        fn write_to(&self, _cache: &mut SizeCache, _buf: &mut impl EncodeSink) {}
1984
1985        fn merge_field(
1986            &mut self,
1987            tag: crate::encoding::Tag,
1988            buf: &mut impl Buf,
1989            ctx: DecodeContext<'_>,
1990        ) -> Result<(), DecodeError> {
1991            self.seen_end = Some(ctx.message_end());
1992            crate::encoding::skip_field(tag, buf)
1993        }
1994
1995        fn merge_to_limit(
1996            &mut self,
1997            buf: &mut impl Buf,
1998            ctx: DecodeContext<'_>,
1999            limit: usize,
2000        ) -> Result<(), DecodeError> {
2001            while buf.remaining() > limit {
2002                let tag = crate::encoding::Tag::decode(buf)?;
2003                self.merge_field(tag, buf, ctx)?;
2004            }
2005            Ok(())
2006        }
2007
2008        fn clear(&mut self) {
2009            *self = Self::default();
2010        }
2011    }
2012
2013    #[test]
2014    fn length_delimited_callers_record_the_end_for_an_override() {
2015        // A frame holding one varint field, then three bytes of a next frame.
2016        let stream = [2u8, 0x08, 0x01, 0xaa, 0xbb, 0xcc];
2017
2018        let mut input = &stream[..];
2019        let msg = OverrideMsg::decode_length_delimited(&mut input).unwrap();
2020        assert_eq!(msg.seen_end, Some(3));
2021
2022        let mut input = &stream[..];
2023        let msg: OverrideMsg = DecodeOptions::new()
2024            .decode_length_delimited(&mut input)
2025            .unwrap();
2026        assert_eq!(msg.seen_end, Some(3));
2027
2028        let limit = core::cell::Cell::new(DEFAULT_UNKNOWN_FIELD_LIMIT);
2029        let mut msg = OverrideMsg::default();
2030        msg.merge_length_delimited(
2031            &mut &stream[..],
2032            DecodeContext::new(RECURSION_LIMIT, &limit),
2033        )
2034        .unwrap();
2035        assert_eq!(msg.seen_end, Some(3));
2036    }
2037
2038    fn wire_bytes(msg: &FlatMsg) -> alloc::vec::Vec<u8> {
2039        let mut buf = alloc::vec::Vec::new();
2040        msg.encode_length_delimited(&mut buf);
2041        buf
2042    }
2043
2044    #[test]
2045    fn test_merge_length_delimited_basic() {
2046        let src = FlatMsg { value: 42 };
2047        let mut dst = FlatMsg::default();
2048        dst.merge_length_delimited(
2049            &mut wire_bytes(&src).as_slice(),
2050            crate::test_ctx(RECURSION_LIMIT),
2051        )
2052        .unwrap();
2053        assert_eq!(dst.value, 42);
2054    }
2055
2056    #[test]
2057    fn test_merge_length_delimited_merges_into_existing() {
2058        // Second merge overwrites (proto3 last-wins for scalar fields).
2059        let mut dst = FlatMsg::default();
2060        dst.merge_length_delimited(
2061            &mut wire_bytes(&FlatMsg { value: 1 }).as_slice(),
2062            crate::test_ctx(RECURSION_LIMIT),
2063        )
2064        .unwrap();
2065        assert_eq!(dst.value, 1);
2066        dst.merge_length_delimited(
2067            &mut wire_bytes(&FlatMsg { value: 2 }).as_slice(),
2068            crate::test_ctx(RECURSION_LIMIT),
2069        )
2070        .unwrap();
2071        assert_eq!(dst.value, 2);
2072    }
2073
2074    #[test]
2075    fn test_merge_length_delimited_truncated() {
2076        // Length prefix says 10 bytes but buffer contains only 2.
2077        let mut buf = alloc::vec::Vec::new();
2078        encode_varint(10, &mut buf);
2079        buf.extend_from_slice(&[0x01, 0x01]);
2080        let mut dst = FlatMsg::default();
2081        assert_eq!(
2082            dst.merge_length_delimited(&mut buf.as_slice(), crate::test_ctx(RECURSION_LIMIT)),
2083            Err(DecodeError::UnexpectedEof)
2084        );
2085    }
2086
2087    #[test]
2088    fn test_merge_length_delimited_oversized() {
2089        // Length prefix exceeds the 2 GiB safety limit.
2090        let mut buf = alloc::vec::Vec::new();
2091        encode_varint(0x8000_0000u64, &mut buf); // 2 GiB + 1
2092        let mut dst = FlatMsg::default();
2093        assert_eq!(
2094            dst.merge_length_delimited(&mut buf.as_slice(), crate::test_ctx(RECURSION_LIMIT)),
2095            Err(DecodeError::MessageTooLarge)
2096        );
2097    }
2098
2099    #[test]
2100    fn test_merge_length_delimited_recursion_limit() {
2101        // depth=1 means merge_length_delimited will decrement to 0, then any
2102        // nested call would return RecursionLimitExceeded.  Passing depth=1
2103        // to merge_length_delimited itself is the boundary: it decrements to
2104        // 0 and calls merge with depth=0, which for FlatMsg (a leaf) succeeds.
2105        // Passing depth=0 directly must return RecursionLimitExceeded.
2106        let src = FlatMsg { value: 7 };
2107        let mut dst = FlatMsg::default();
2108        assert_eq!(
2109            dst.merge_length_delimited(&mut wire_bytes(&src).as_slice(), crate::test_ctx(0)),
2110            Err(DecodeError::RecursionLimitExceeded)
2111        );
2112        // depth=1 succeeds: exactly one level is consumed.
2113        dst.merge_length_delimited(&mut wire_bytes(&src).as_slice(), crate::test_ctx(1))
2114            .unwrap();
2115        assert_eq!(dst.value, 7);
2116    }
2117
2118    #[test]
2119    fn test_decode_from_slice_basic() {
2120        let src = FlatMsg { value: 42 };
2121        let bytes = src.encode_to_vec();
2122        let dst = FlatMsg::decode_from_slice(&bytes).unwrap();
2123        assert_eq!(dst.value, 42);
2124    }
2125
2126    #[test]
2127    fn test_encode_to_bytes_matches_encode_to_vec() {
2128        let src = FlatMsg { value: 42 };
2129        let vec = src.encode_to_vec();
2130        let bytes = src.encode_to_bytes();
2131        assert_eq!(vec.as_slice(), bytes.as_ref());
2132        // Round-trip through the Bytes variant.
2133        let dst = FlatMsg::decode_from_slice(&bytes).unwrap();
2134        assert_eq!(dst.value, 42);
2135        // Empty-message case: zero-length buffer is well-defined.
2136        assert!(FlatMsg::default().encode_to_bytes().is_empty());
2137    }
2138
2139    #[test]
2140    fn test_decode_from_slice_empty() {
2141        let dst = FlatMsg::decode_from_slice(&[]).unwrap();
2142        assert_eq!(dst.value, 0);
2143    }
2144
2145    #[test]
2146    fn test_decode_from_slice_invalid_returns_error() {
2147        // A lone 0xFF byte is not a valid varint tag.
2148        let result = FlatMsg::decode_from_slice(&[0xFF]);
2149        assert!(result.is_err());
2150    }
2151
2152    #[test]
2153    fn test_merge_from_slice_basic() {
2154        let src = FlatMsg { value: 7 };
2155        let bytes = src.encode_to_vec();
2156        let mut dst = FlatMsg::default();
2157        dst.merge_from_slice(&bytes).unwrap();
2158        assert_eq!(dst.value, 7);
2159    }
2160
2161    #[test]
2162    fn test_merge_from_slice_last_wins() {
2163        let src1 = FlatMsg { value: 1 };
2164        let src2 = FlatMsg { value: 2 };
2165        let mut dst = FlatMsg::default();
2166        dst.merge_from_slice(&src1.encode_to_vec()).unwrap();
2167        dst.merge_from_slice(&src2.encode_to_vec()).unwrap();
2168        // Proto3 last-wins semantics for scalar fields.
2169        assert_eq!(dst.value, 2);
2170    }
2171
2172    // ── DecodeOptions tests ──────────────────────────────────────────
2173
2174    #[test]
2175    fn test_decode_options_default_works() {
2176        let src = FlatMsg { value: 99 };
2177        let bytes = src.encode_to_vec();
2178        let msg: FlatMsg = DecodeOptions::new().decode_from_slice(&bytes).unwrap();
2179        assert_eq!(msg.value, 99);
2180    }
2181
2182    #[test]
2183    fn test_decode_options_max_message_size_rejects() {
2184        let src = FlatMsg { value: 42 };
2185        let bytes = src.encode_to_vec();
2186        // Set max size to 1 byte — smaller than the encoded message.
2187        let result: Result<FlatMsg, _> = DecodeOptions::new()
2188            .with_max_message_size(1)
2189            .decode_from_slice(&bytes);
2190        assert_eq!(result, Err(DecodeError::MessageTooLarge));
2191    }
2192
2193    #[test]
2194    fn test_decode_options_max_message_size_exact_boundary() {
2195        let src = FlatMsg { value: 42 };
2196        let bytes = src.encode_to_vec();
2197        // Exact size should succeed.
2198        let msg: FlatMsg = DecodeOptions::new()
2199            .with_max_message_size(bytes.len())
2200            .decode_from_slice(&bytes)
2201            .unwrap();
2202        assert_eq!(msg.value, 42);
2203        // One byte less should fail.
2204        let result: Result<FlatMsg, _> = DecodeOptions::new()
2205            .with_max_message_size(bytes.len() - 1)
2206            .decode_from_slice(&bytes);
2207        assert_eq!(result, Err(DecodeError::MessageTooLarge));
2208    }
2209
2210    #[test]
2211    fn test_decode_options_custom_recursion_limit() {
2212        // FlatMsg has no nested messages, so any recursion limit >= 0 works.
2213        // Just verify the API compiles and runs.
2214        let src = FlatMsg { value: 7 };
2215        let bytes = src.encode_to_vec();
2216        let msg: FlatMsg = DecodeOptions::new()
2217            .with_recursion_limit(1)
2218            .decode_from_slice(&bytes)
2219            .unwrap();
2220        assert_eq!(msg.value, 7);
2221    }
2222
2223    #[test]
2224    fn test_decode_options_merge() {
2225        let src = FlatMsg { value: 55 };
2226        let bytes = src.encode_to_vec();
2227        let mut msg = FlatMsg::default();
2228        DecodeOptions::new()
2229            .merge_from_slice(&mut msg, &bytes)
2230            .unwrap();
2231        assert_eq!(msg.value, 55);
2232    }
2233
2234    #[test]
2235    fn test_decode_options_merge_rejects_oversize() {
2236        let src = FlatMsg { value: 55 };
2237        let bytes = src.encode_to_vec();
2238        let mut msg = FlatMsg::default();
2239        let result = DecodeOptions::new()
2240            .with_max_message_size(1)
2241            .merge_from_slice(&mut msg, &bytes);
2242        assert_eq!(result, Err(DecodeError::MessageTooLarge));
2243    }
2244
2245    #[test]
2246    fn merge_error_clears_destination_only_when_requested() {
2247        let mut message = FlatMsg { value: 17 };
2248        let mut malformed = FlatMsg { value: 42 }.encode_to_vec();
2249        malformed.push(0); // illegal field number
2250        assert_eq!(
2251            DecodeOptions::new().merge_from_slice(&mut message, &malformed),
2252            Err(DecodeError::InvalidFieldNumber)
2253        );
2254        assert_eq!(message.value, 42);
2255        assert!(!DecodeOptions::new().clears_on_merge_error());
2256
2257        let options = DecodeOptions::new().clear_on_merge_error();
2258        assert!(options.clears_on_merge_error());
2259        assert_eq!(
2260            options.merge(&mut message, &mut malformed.as_slice()),
2261            Err(DecodeError::InvalidFieldNumber)
2262        );
2263        assert_eq!(message.value, 0);
2264
2265        let wire = FlatMsg { value: 27 }.encode_to_vec();
2266        options.merge_from_slice(&mut message, &wire).unwrap();
2267        assert_eq!(message.value, 27);
2268        assert_eq!(
2269            options
2270                .with_max_message_size(1)
2271                .merge_from_slice(&mut message, &wire),
2272            Err(DecodeError::MessageTooLarge)
2273        );
2274        assert_eq!(message.value, 0);
2275    }
2276
2277    #[test]
2278    fn clear_policy_can_be_disabled_on_a_cloned_configuration() {
2279        let enabled = DecodeOptions::new()
2280            .with_recursion_limit(7)
2281            .with_max_message_size(99)
2282            .with_unknown_field_limit(3)
2283            .with_element_memory_limit(64)
2284            .clear_on_merge_error();
2285        #[cfg(feature = "std")]
2286        let enabled = enabled.without_reader_size_limit();
2287        let disabled = enabled.clone().with_clear_on_merge_error(false);
2288        assert!(enabled.clears_on_merge_error());
2289        assert!(!disabled.clears_on_merge_error());
2290        assert_eq!(disabled.recursion_limit(), enabled.recursion_limit());
2291        assert_eq!(disabled.max_message_size(), enabled.max_message_size());
2292        assert_eq!(
2293            disabled.unknown_field_limit(),
2294            enabled.unknown_field_limit()
2295        );
2296        assert_eq!(
2297            disabled.element_memory_limit(),
2298            enabled.element_memory_limit()
2299        );
2300        #[cfg(feature = "std")]
2301        assert_eq!(
2302            disabled.is_reader_size_unbounded(),
2303            enabled.is_reader_size_unbounded()
2304        );
2305        assert!(disabled
2306            .clone()
2307            .with_clear_on_merge_error(true)
2308            .clears_on_merge_error());
2309
2310        let mut wire = FlatMsg { value: 42 }.encode_to_vec();
2311        wire.push(0);
2312        let mut message = FlatMsg { value: 17 };
2313        assert_eq!(
2314            disabled.merge_from_slice(&mut message, &wire),
2315            Err(DecodeError::InvalidFieldNumber)
2316        );
2317        assert_eq!(message.value, 42);
2318        assert_eq!(
2319            enabled.merge_from_slice(&mut message, &wire),
2320            Err(DecodeError::InvalidFieldNumber)
2321        );
2322        assert_eq!(message.value, 0);
2323    }
2324
2325    #[derive(Clone, Debug, Default, PartialEq)]
2326    struct ClearObserved {
2327        inner: FlatMsg,
2328        clear_calls: usize,
2329    }
2330    crate::impl_default_instance!(ClearObserved);
2331    impl Message for ClearObserved {
2332        fn compute_size(&self, cache: &mut SizeCache) -> u32 {
2333            self.inner.compute_size(cache)
2334        }
2335        fn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink) {
2336            self.inner.write_to(cache, buf);
2337        }
2338        fn merge_field(
2339            &mut self,
2340            tag: crate::encoding::Tag,
2341            buf: &mut impl Buf,
2342            ctx: DecodeContext<'_>,
2343        ) -> Result<(), DecodeError> {
2344            self.inner.merge_field(tag, buf, ctx)
2345        }
2346        fn clear(&mut self) {
2347            self.inner.clear();
2348            self.clear_calls = self.clear_calls.checked_add(1).unwrap();
2349        }
2350    }
2351
2352    #[test]
2353    fn merge_cleanup_calls_the_message_hook_once_without_rewinding_input() {
2354        let valid = FlatMsg { value: 42 }.encode_to_vec();
2355        let mut malformed = valid.clone();
2356        malformed.extend_from_slice(&[0, 0x7f]);
2357        let input_before = malformed.clone();
2358        for clear in [false, true] {
2359            let options = DecodeOptions::new().with_clear_on_merge_error(clear);
2360            let mut message = ClearObserved::default();
2361            options.merge_from_slice(&mut message, &valid).unwrap();
2362            options.merge_from_slice(&mut message, &[]).unwrap();
2363            assert_eq!(message.clear_calls, 0, "success must not run cleanup");
2364            assert_eq!(message.inner.value, 42);
2365
2366            // Fragmented buffers retain the same consumed cursor when the
2367            // destination policy changes. The sentinel is outside the error.
2368            let (first, rest) = malformed.split_at(1);
2369            let mut input = first.chain(rest);
2370            assert_eq!(
2371                options.merge(&mut message, &mut input),
2372                Err(DecodeError::InvalidFieldNumber)
2373            );
2374            assert_eq!(input.chunk(), &[0x7f]);
2375            assert_eq!(message.clear_calls, usize::from(clear));
2376            assert_eq!(message.inner.value, if clear { 0 } else { 42 });
2377
2378            let mut message = ClearObserved::default();
2379            let mut input = valid.as_slice();
2380            assert_eq!(
2381                options
2382                    .with_max_message_size(0)
2383                    .merge(&mut message, &mut input),
2384                Err(DecodeError::MessageTooLarge)
2385            );
2386            assert_eq!(input, valid, "size rejection must not consume input");
2387            // This remains necessary even when the message is already empty:
2388            // its clear hook may erase retained allocation or external state.
2389            assert_eq!(message.clear_calls, usize::from(clear));
2390        }
2391        assert_eq!(malformed, input_before, "caller input bytes are not wiped");
2392    }
2393
2394    #[derive(Clone, Debug, Default, PartialEq)]
2395    struct MergeOverride(ClearObserved);
2396    crate::impl_default_instance!(MergeOverride);
2397    impl Message for MergeOverride {
2398        fn compute_size(&self, cache: &mut SizeCache) -> u32 {
2399            self.0.compute_size(cache)
2400        }
2401        fn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink) {
2402            self.0.write_to(cache, buf);
2403        }
2404        fn merge_field(
2405            &mut self,
2406            tag: crate::encoding::Tag,
2407            buf: &mut impl Buf,
2408            ctx: DecodeContext<'_>,
2409        ) -> Result<(), DecodeError> {
2410            self.0.merge_field(tag, buf, ctx)
2411        }
2412        fn merge(
2413            &mut self,
2414            _buf: &mut impl Buf,
2415            _ctx: DecodeContext<'_>,
2416        ) -> Result<(), DecodeError> {
2417            // Hand-written implementations can reject empty input after
2418            // changing state, without entering the default field loop.
2419            self.0.inner.value = 42;
2420            Err(DecodeError::Custom("merge override rejected input"))
2421        }
2422        fn clear(&mut self) {
2423            self.0.clear();
2424        }
2425    }
2426
2427    #[test]
2428    fn empty_input_still_calls_an_overridden_merge_and_its_cleanup_hook() {
2429        for clear in [false, true] {
2430            let options = DecodeOptions::new()
2431                .with_max_message_size(0)
2432                .with_clear_on_merge_error(clear);
2433            for from_slice in [false, true] {
2434                let mut message = MergeOverride::default();
2435                let mut input = [].as_slice();
2436                let result = if from_slice {
2437                    options.merge_from_slice(&mut message, input)
2438                } else {
2439                    options.merge(&mut message, &mut input)
2440                };
2441                assert_eq!(
2442                    result,
2443                    Err(DecodeError::Custom("merge override rejected input"))
2444                );
2445                assert!(input.is_empty());
2446                assert_eq!(message.0.clear_calls, usize::from(clear));
2447                assert_eq!(message.0.inner.value, if clear { 0 } else { 42 });
2448            }
2449        }
2450    }
2451
2452    #[test]
2453    fn test_decode_options_length_delimited() {
2454        let src = FlatMsg { value: 42 };
2455        let mut ld_bytes = alloc::vec::Vec::new();
2456        src.encode_length_delimited(&mut ld_bytes);
2457        let msg: FlatMsg = DecodeOptions::new()
2458            .decode_length_delimited(&mut ld_bytes.as_slice())
2459            .unwrap();
2460        assert_eq!(msg.value, 42);
2461    }
2462
2463    #[test]
2464    fn test_decode_options_length_delimited_rejects_oversize() {
2465        let src = FlatMsg { value: 42 };
2466        let mut ld_bytes = alloc::vec::Vec::new();
2467        src.encode_length_delimited(&mut ld_bytes);
2468        let result: Result<FlatMsg, _> = DecodeOptions::new()
2469            .with_max_message_size(1)
2470            .decode_length_delimited(&mut ld_bytes.as_slice());
2471        assert_eq!(result, Err(DecodeError::MessageTooLarge));
2472    }
2473
2474    #[test]
2475    fn decode_options_getters_return_defaults() {
2476        let opts = DecodeOptions::new();
2477        assert_eq!(opts.recursion_limit(), RECURSION_LIMIT);
2478        assert_eq!(opts.max_message_size(), 0x7FFF_FFFF);
2479        assert_eq!(opts.unknown_field_limit(), DEFAULT_UNKNOWN_FIELD_LIMIT);
2480    }
2481
2482    #[test]
2483    fn decode_options_getters_return_custom_values() {
2484        let opts = DecodeOptions::new()
2485            .with_recursion_limit(42)
2486            .with_max_message_size(1024)
2487            .with_unknown_field_limit(2048);
2488        assert_eq!(opts.recursion_limit(), 42);
2489        assert_eq!(opts.max_message_size(), 1024);
2490        assert_eq!(opts.unknown_field_limit(), 2048);
2491    }
2492
2493    #[cfg(debug_assertions)]
2494    #[test]
2495    #[should_panic(expected = "protobuf 2 GiB limit")]
2496    fn decode_options_max_message_size_above_protobuf_limit_debug_asserts() {
2497        let _ = DecodeOptions::new().with_max_message_size(DEFAULT_MAX_MESSAGE_SIZE + 1);
2498    }
2499
2500    #[cfg(not(debug_assertions))]
2501    #[test]
2502    fn decode_options_max_message_size_above_protobuf_limit_saturates() {
2503        let opts = DecodeOptions::new().with_max_message_size(DEFAULT_MAX_MESSAGE_SIZE + 1);
2504        assert_eq!(opts.max_message_size(), DEFAULT_MAX_MESSAGE_SIZE);
2505    }
2506
2507    #[test]
2508    fn test_decode_options_default_impl() {
2509        // DecodeOptions::default() ≡ DecodeOptions::new().
2510        let opts = DecodeOptions::default();
2511        assert_eq!(opts.recursion_limit(), RECURSION_LIMIT);
2512        assert_eq!(opts.max_message_size(), 0x7FFF_FFFF);
2513        assert_eq!(opts.unknown_field_limit(), DEFAULT_UNKNOWN_FIELD_LIMIT);
2514    }
2515
2516    #[test]
2517    fn test_decode_options_decode_buf() {
2518        // The Buf-taking decode() variant (vs decode_from_slice).
2519        let src = FlatMsg { value: 123 };
2520        let bytes = src.encode_to_vec();
2521        let msg: FlatMsg = DecodeOptions::new().decode(&mut bytes.as_slice()).unwrap();
2522        assert_eq!(msg.value, 123);
2523        // Oversize check on the Buf variant.
2524        let result: Result<FlatMsg, _> = DecodeOptions::new()
2525            .with_max_message_size(1)
2526            .decode(&mut bytes.as_slice());
2527        assert_eq!(result, Err(DecodeError::MessageTooLarge));
2528    }
2529
2530    #[test]
2531    fn test_decode_options_merge_buf() {
2532        // The Buf-taking merge() variant (vs merge_from_slice).
2533        let src = FlatMsg { value: 77 };
2534        let bytes = src.encode_to_vec();
2535        let mut msg = FlatMsg::default();
2536        DecodeOptions::new()
2537            .merge(&mut msg, &mut bytes.as_slice())
2538            .unwrap();
2539        assert_eq!(msg.value, 77);
2540        // Oversize check.
2541        let mut msg = FlatMsg::default();
2542        let result = DecodeOptions::new()
2543            .with_max_message_size(1)
2544            .merge(&mut msg, &mut bytes.as_slice());
2545        assert_eq!(result, Err(DecodeError::MessageTooLarge));
2546    }
2547
2548    // ── Message trait default methods ─────────────────────────────────
2549
2550    #[test]
2551    fn test_message_encode_trait_default() {
2552        // Message::encode(buf) ≡ compute_size() then write_to(buf).
2553        let src = FlatMsg { value: 42 };
2554        let mut buf = alloc::vec::Vec::new();
2555        src.encode(&mut buf);
2556        assert_eq!(buf, src.encode_to_vec());
2557    }
2558
2559    #[test]
2560    fn test_message_decode_length_delimited_trait_default() {
2561        // The trait-level decode_length_delimited (distinct from
2562        // DecodeOptions::decode_length_delimited).
2563        let src = FlatMsg { value: 42 };
2564        let mut ld = alloc::vec::Vec::new();
2565        src.encode_length_delimited(&mut ld);
2566        let got = FlatMsg::decode_length_delimited(&mut ld.as_slice()).unwrap();
2567        assert_eq!(got.value, 42);
2568    }
2569
2570    #[test]
2571    fn test_message_decode_length_delimited_oversize() {
2572        // Length prefix > 2 GiB → MessageTooLarge.
2573        let mut buf = alloc::vec::Vec::new();
2574        encode_varint(0x8000_0000u64, &mut buf);
2575        let result = FlatMsg::decode_length_delimited(&mut buf.as_slice());
2576        assert_eq!(result, Err(DecodeError::MessageTooLarge));
2577    }
2578
2579    #[test]
2580    fn test_message_decode_length_delimited_truncated() {
2581        // Length prefix says 10 bytes, buffer has 2.
2582        let mut buf = alloc::vec::Vec::new();
2583        encode_varint(10, &mut buf);
2584        buf.push(0x08);
2585        buf.push(0x01);
2586        let result = FlatMsg::decode_length_delimited(&mut buf.as_slice());
2587        assert_eq!(result, Err(DecodeError::UnexpectedEof));
2588    }
2589
2590    #[test]
2591    fn test_message_decode_length_delimited_with_trailing() {
2592        // Buffer has two back-to-back length-delimited messages.
2593        // decode_length_delimited should consume exactly the first one
2594        // and leave the buffer positioned at the second.
2595        let a = FlatMsg { value: 1 };
2596        let b = FlatMsg { value: 2 };
2597        let mut buf = alloc::vec::Vec::new();
2598        a.encode_length_delimited(&mut buf);
2599        b.encode_length_delimited(&mut buf);
2600
2601        let mut cur = buf.as_slice();
2602        let first = FlatMsg::decode_length_delimited(&mut cur).unwrap();
2603        assert_eq!(first.value, 1);
2604        let second = FlatMsg::decode_length_delimited(&mut cur).unwrap();
2605        assert_eq!(second.value, 2);
2606        assert!(cur.is_empty());
2607    }
2608
2609    // ── merge_group tests ─────────────────────────────────────────────
2610
2611    /// Build a group body for FlatMsg (field 1 = value) terminated by
2612    /// EndGroup with the given field number.
2613    fn group_bytes(value: i32, group_field_number: u32) -> alloc::vec::Vec<u8> {
2614        use crate::encoding::{Tag, WireType};
2615        let mut buf = alloc::vec::Vec::new();
2616        if value != 0 {
2617            Tag::new(1, WireType::Varint).encode(&mut buf);
2618            crate::types::encode_int32(value, &mut buf);
2619        }
2620        Tag::new(group_field_number, WireType::EndGroup).encode(&mut buf);
2621        buf
2622    }
2623
2624    #[test]
2625    fn test_merge_group_basic() {
2626        let data = group_bytes(42, 5);
2627        let mut dst = FlatMsg::default();
2628        dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2629            .unwrap();
2630        assert_eq!(dst.value, 42);
2631    }
2632
2633    #[test]
2634    fn test_merge_group_empty() {
2635        // Group with no fields — just EndGroup.
2636        let data = group_bytes(0, 3);
2637        let mut dst = FlatMsg::default();
2638        dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 3)
2639            .unwrap();
2640        assert_eq!(dst.value, 0);
2641    }
2642
2643    #[test]
2644    fn test_merge_group_merges_into_existing() {
2645        let data1 = group_bytes(1, 5);
2646        let data2 = group_bytes(2, 5);
2647        let mut dst = FlatMsg::default();
2648        dst.merge_group(&mut data1.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2649            .unwrap();
2650        assert_eq!(dst.value, 1);
2651        dst.merge_group(&mut data2.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2652            .unwrap();
2653        assert_eq!(dst.value, 2);
2654    }
2655
2656    #[test]
2657    fn test_merge_group_recursion_limit_zero() {
2658        // depth=0 should immediately fail with RecursionLimitExceeded
2659        // because merge_group decrements before entering the loop.
2660        let data = group_bytes(42, 5);
2661        let mut dst = FlatMsg::default();
2662        assert_eq!(
2663            dst.merge_group(&mut data.as_slice(), crate::test_ctx(0), 5),
2664            Err(DecodeError::RecursionLimitExceeded)
2665        );
2666    }
2667
2668    #[test]
2669    fn test_merge_group_recursion_limit_one_succeeds() {
2670        // depth=1 succeeds: merge_group decrements to 0, but FlatMsg's
2671        // merge_field doesn't recurse further.
2672        let data = group_bytes(7, 5);
2673        let mut dst = FlatMsg::default();
2674        dst.merge_group(&mut data.as_slice(), crate::test_ctx(1), 5)
2675            .unwrap();
2676        assert_eq!(dst.value, 7);
2677    }
2678
2679    #[test]
2680    fn test_merge_group_mismatched_end() {
2681        // EndGroup with wrong field number.
2682        use crate::encoding::{Tag, WireType};
2683        let mut data = alloc::vec::Vec::new();
2684        Tag::new(99, WireType::EndGroup).encode(&mut data);
2685
2686        let mut dst = FlatMsg::default();
2687        assert_eq!(
2688            dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5),
2689            Err(DecodeError::InvalidEndGroup(99))
2690        );
2691    }
2692
2693    #[test]
2694    fn test_merge_group_truncated() {
2695        // Buffer ends without EndGroup tag.
2696        use crate::encoding::{Tag, WireType};
2697        let mut data = alloc::vec::Vec::new();
2698        Tag::new(1, WireType::Varint).encode(&mut data);
2699        crate::types::encode_int32(42, &mut data);
2700        // No EndGroup.
2701
2702        let mut dst = FlatMsg::default();
2703        assert_eq!(
2704            dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5),
2705            Err(DecodeError::UnexpectedEof)
2706        );
2707    }
2708
2709    #[test]
2710    fn test_merge_group_empty_buffer() {
2711        let mut dst = FlatMsg::default();
2712        assert_eq!(
2713            dst.merge_group(&mut [].as_slice(), crate::test_ctx(RECURSION_LIMIT), 5),
2714            Err(DecodeError::UnexpectedEof)
2715        );
2716    }
2717
2718    #[test]
2719    fn test_merge_group_unknown_fields_skipped() {
2720        // Group body contains an unknown field (field 99) which FlatMsg
2721        // routes to skip_field; the known field (field 1) should still
2722        // be decoded.
2723        use crate::encoding::{Tag, WireType};
2724        let mut data = alloc::vec::Vec::new();
2725        // Unknown varint field 99 = 0
2726        Tag::new(99, WireType::Varint).encode(&mut data);
2727        crate::encoding::encode_varint(0, &mut data);
2728        // Known field 1 = 99
2729        Tag::new(1, WireType::Varint).encode(&mut data);
2730        crate::types::encode_int32(99, &mut data);
2731        // EndGroup(5)
2732        Tag::new(5, WireType::EndGroup).encode(&mut data);
2733
2734        let mut dst = FlatMsg::default();
2735        dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2736            .unwrap();
2737        assert_eq!(dst.value, 99);
2738    }
2739
2740    #[test]
2741    fn test_merge_group_trailing_data_preserved() {
2742        // After the EndGroup tag, trailing data should remain in the buffer.
2743        let mut data = group_bytes(42, 5);
2744        data.extend_from_slice(&[0xDE, 0xAD]);
2745
2746        let mut cur = data.as_slice();
2747        let mut dst = FlatMsg::default();
2748        dst.merge_group(&mut cur, crate::test_ctx(RECURSION_LIMIT), 5)
2749            .unwrap();
2750        assert_eq!(dst.value, 42);
2751        assert_eq!(cur, &[0xDE, 0xAD]);
2752    }
2753
2754    // ── read_varint (std::io::Read) tests ──────────────────────────────
2755
2756    #[cfg(feature = "std")]
2757    mod read_varint_tests {
2758        use super::super::read_varint;
2759        use crate::encoding::encode_varint;
2760
2761        #[test]
2762        fn roundtrip_values() {
2763            let cases: &[u64] = &[0, 1, 127, 128, 300, 1 << 14, 1 << 35, 1 << 63, u64::MAX];
2764            for &v in cases {
2765                let mut buf = Vec::new();
2766                encode_varint(v, &mut buf);
2767                let got = read_varint(&mut buf.as_slice()).unwrap();
2768                assert_eq!(got, v, "roundtrip failed for {v}");
2769            }
2770        }
2771
2772        #[test]
2773        fn rejects_10th_byte_overflow() {
2774            // 9 continuation bytes + 10th byte with overflow bit (0x02).
2775            // Mirrors encoding::tests::test_varint_10th_byte_overflow_rejected.
2776            let mut bad: Vec<u8> = vec![0xFF; 9];
2777            bad.push(0x02);
2778            let err = read_varint(&mut bad.as_slice()).unwrap_err();
2779            assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2780        }
2781
2782        #[test]
2783        fn rejects_11th_byte() {
2784            // 10 continuation bytes — implies an 11th byte is needed.
2785            let bad: &[u8] = &[0xFF; 10];
2786            let err = read_varint(&mut &bad[..]).unwrap_err();
2787            assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2788        }
2789
2790        #[test]
2791        fn u64_max_roundtrips() {
2792            // u64::MAX requires 10 bytes with the 10th byte == 0x01.
2793            let mut buf = Vec::new();
2794            encode_varint(u64::MAX, &mut buf);
2795            assert_eq!(buf.len(), 10);
2796            assert_eq!(buf[9], 0x01);
2797            let got = read_varint(&mut buf.as_slice()).unwrap();
2798            assert_eq!(got, u64::MAX);
2799        }
2800
2801        #[test]
2802        fn eof_before_terminator_is_error() {
2803            // Single continuation byte with no follow-up.
2804            let bad: &[u8] = &[0x80];
2805            let err = read_varint(&mut &bad[..]).unwrap_err();
2806            assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
2807        }
2808
2809        #[test]
2810        fn empty_input_is_error() {
2811            let err = read_varint(&mut &[][..]).unwrap_err();
2812            assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
2813        }
2814    }
2815
2816    // ── Encode-side 2 GiB guard tests ──────────────────────────────────
2817
2818    use crate::test_doubles::{Mismatched, SizedMsg};
2819
2820    const OVER_LIMIT: u32 = MAX_MESSAGE_BYTES + 1;
2821
2822    #[test]
2823    fn saturate_size_is_exact_below_u32_max_and_saturates_above() {
2824        assert_eq!(saturate_size(0), 0);
2825        assert_eq!(saturate_size(MAX_MESSAGE_BYTES as u64), MAX_MESSAGE_BYTES);
2826        // 2–4 GiB window: exact (this is what makes the guard byte-precise).
2827        assert_eq!(saturate_size(0x8000_0000), 0x8000_0000u32);
2828        assert_eq!(saturate_size(u32::MAX as u64), u32::MAX);
2829        assert_eq!(saturate_size(u32::MAX as u64 + 1), u32::MAX);
2830        assert_eq!(saturate_size(u64::MAX), u32::MAX);
2831    }
2832
2833    #[test]
2834    fn encode_at_exactly_max_size_is_allowed() {
2835        // The guard is strictly-greater-than: a (fake) message of exactly
2836        // MAX_MESSAGE_BYTES passes. The pre-sized path and its ledger apply
2837        // only to `BufMut` sinks, and `NullSink` lets this no-op write_to
2838        // declare 2 GiB without allocating it.
2839        let msg = SizedMsg {
2840            reported_size: MAX_MESSAGE_BYTES,
2841        };
2842        let mut sink = crate::test_doubles::NullSink;
2843        msg.encode(&mut sink);
2844        assert!(msg.try_encode(&mut sink).is_ok());
2845    }
2846
2847    #[test]
2848    #[should_panic(expected = "2 GiB protobuf limit")]
2849    fn encode_over_limit_panics() {
2850        let msg = SizedMsg {
2851            reported_size: OVER_LIMIT,
2852        };
2853        let mut buf = alloc::vec::Vec::new();
2854        msg.encode(&mut buf);
2855    }
2856
2857    #[test]
2858    #[should_panic(expected = "2 GiB protobuf limit")]
2859    fn encoded_len_over_limit_panics() {
2860        let msg = SizedMsg {
2861            reported_size: OVER_LIMIT,
2862        };
2863        let _ = msg.encoded_len();
2864    }
2865
2866    #[test]
2867    #[should_panic(expected = "2 GiB protobuf limit")]
2868    fn encode_with_cache_over_limit_panics() {
2869        let msg = SizedMsg {
2870            reported_size: OVER_LIMIT,
2871        };
2872        let mut cache = SizeCache::new();
2873        let mut buf = alloc::vec::Vec::new();
2874        msg.encode_with_cache(&mut cache, &mut buf);
2875    }
2876
2877    #[test]
2878    #[should_panic(expected = "2 GiB protobuf limit")]
2879    fn encode_to_vec_over_limit_panics() {
2880        let msg = SizedMsg {
2881            reported_size: OVER_LIMIT,
2882        };
2883        let _ = msg.encode_to_vec();
2884    }
2885
2886    #[test]
2887    #[should_panic(expected = "2 GiB protobuf limit")]
2888    fn encode_to_bytes_over_limit_panics() {
2889        let msg = SizedMsg {
2890            reported_size: OVER_LIMIT,
2891        };
2892        let _ = msg.encode_to_bytes();
2893    }
2894
2895    #[test]
2896    #[should_panic(expected = "2 GiB protobuf limit")]
2897    fn encode_length_delimited_over_limit_panics() {
2898        let msg = SizedMsg {
2899            reported_size: OVER_LIMIT,
2900        };
2901        let mut buf = alloc::vec::Vec::new();
2902        msg.encode_length_delimited(&mut buf);
2903    }
2904
2905    #[test]
2906    fn try_encode_over_limit_errors_and_writes_nothing() {
2907        let msg = SizedMsg {
2908            reported_size: OVER_LIMIT,
2909        };
2910        let mut buf = alloc::vec::Vec::new();
2911        assert_eq!(msg.try_encode(&mut buf), Err(EncodeError::MessageTooLarge));
2912        assert!(buf.is_empty(), "no bytes may reach the buffer on Err");
2913        let mut cache = SizeCache::new();
2914        assert_eq!(
2915            msg.try_encode_with_cache(&mut cache, &mut buf),
2916            Err(EncodeError::MessageTooLarge)
2917        );
2918        assert!(buf.is_empty(), "no bytes may reach the buffer on Err");
2919        assert_eq!(
2920            msg.try_encode_length_delimited(&mut buf),
2921            Err(EncodeError::MessageTooLarge)
2922        );
2923        assert!(buf.is_empty(), "not even the length prefix");
2924        assert_eq!(msg.try_encode_to_vec(), Err(EncodeError::MessageTooLarge));
2925        assert_eq!(msg.try_encode_to_bytes(), Err(EncodeError::MessageTooLarge));
2926        assert_eq!(msg.try_encoded_len(), Err(EncodeError::MessageTooLarge));
2927    }
2928
2929    #[test]
2930    fn try_encode_matches_encode_for_normal_messages() {
2931        let msg = FlatMsg { value: 42 };
2932        let mut expected = alloc::vec::Vec::new();
2933        msg.encode(&mut expected);
2934        let mut actual = alloc::vec::Vec::new();
2935        msg.try_encode(&mut actual).unwrap();
2936        assert_eq!(actual, expected);
2937        let mut cache = SizeCache::new();
2938        let mut cached = alloc::vec::Vec::new();
2939        msg.try_encode_with_cache(&mut cache, &mut cached).unwrap();
2940        assert_eq!(cached, expected);
2941        assert_eq!(msg.try_encode_to_vec().unwrap(), expected);
2942        assert_eq!(msg.try_encode_to_bytes().unwrap(), expected);
2943        assert_eq!(msg.try_encoded_len().unwrap(), expected.len() as u32);
2944
2945        let mut ld_expected = alloc::vec::Vec::new();
2946        msg.encode_length_delimited(&mut ld_expected);
2947        let mut ld_actual = alloc::vec::Vec::new();
2948        msg.try_encode_length_delimited(&mut ld_actual).unwrap();
2949        assert_eq!(ld_actual, ld_expected);
2950    }
2951
2952    #[test]
2953    fn try_encode_bounded_within_budget_encodes_and_returns_len() {
2954        let msg = FlatMsg { value: 42 };
2955        let mut expected = alloc::vec::Vec::new();
2956        msg.encode(&mut expected);
2957        let budget = expected.len() as u32;
2958
2959        let mut buf = alloc::vec::Vec::new();
2960        let len = msg.try_encode_bounded(budget, &mut buf).unwrap();
2961        assert_eq!(buf, expected);
2962        assert_eq!(len, budget);
2963
2964        // with_cache variant agrees
2965        let mut cache = SizeCache::new();
2966        let mut buf2 = alloc::vec::Vec::new();
2967        let len2 = msg
2968            .try_encode_bounded_with_cache(budget, &mut cache, &mut buf2)
2969            .unwrap();
2970        assert_eq!(buf2, expected);
2971        assert_eq!(len2, budget);
2972    }
2973
2974    #[test]
2975    fn try_encode_bounded_at_exact_limit_succeeds() {
2976        let msg = FlatMsg { value: 42 };
2977        let exact = msg.encoded_len();
2978        let mut buf = alloc::vec::Vec::new();
2979        assert!(msg.try_encode_bounded(exact, &mut buf).is_ok());
2980    }
2981
2982    #[test]
2983    fn try_encode_bounded_over_budget_errors_and_writes_nothing() {
2984        let msg = FlatMsg { value: 42 };
2985        let len = msg.encoded_len();
2986        let budget = len - 1; // one byte under
2987
2988        let mut buf = alloc::vec::Vec::new();
2989        assert_eq!(
2990            msg.try_encode_bounded(budget, &mut buf),
2991            Err(EncodeError::ExceedsBudget {
2992                len,
2993                max_bytes: budget
2994            })
2995        );
2996        assert!(buf.is_empty(), "nothing written on budget exceeded");
2997    }
2998
2999    /// "Nothing written on `Err`" has to hold for a sink that already has
3000    /// bytes in it, which is how a caller framing several messages uses one
3001    /// buffer. Every other test starts from an empty `Vec`, so the append
3002    /// case — where a partial write would corrupt the *preceding* message
3003    /// rather than produce an obviously empty one — would go unnoticed.
3004    #[test]
3005    fn try_encode_bounded_over_budget_leaves_a_populated_buffer_untouched() {
3006        let msg = FlatMsg { value: 42 };
3007        let len = msg.encoded_len();
3008        let budget = len - 1;
3009
3010        let prefix = b"already framed".to_vec();
3011        let mut buf = prefix.clone();
3012        assert_eq!(
3013            msg.try_encode_bounded(budget, &mut buf),
3014            Err(EncodeError::ExceedsBudget {
3015                len,
3016                max_bytes: budget
3017            })
3018        );
3019        assert_eq!(buf, prefix, "the bytes already in the sink must survive");
3020    }
3021
3022    #[test]
3023    fn try_encode_bounded_zero_budget_with_empty_message_succeeds() {
3024        // A default FlatMsg with value=0 encodes to 0 bytes (all defaults
3025        // are elided in proto3), so budget=0 is exactly satisfied.
3026        let msg = FlatMsg { value: 0 };
3027        let mut buf = alloc::vec::Vec::new();
3028        let len = msg.try_encode_bounded(0, &mut buf).unwrap();
3029        assert_eq!(len, 0);
3030        assert!(buf.is_empty());
3031    }
3032
3033    #[test]
3034    fn try_encode_bounded_over_protobuf_limit_errors_as_too_large() {
3035        let msg = SizedMsg {
3036            reported_size: OVER_LIMIT,
3037        };
3038        let mut buf = alloc::vec::Vec::new();
3039        assert_eq!(
3040            msg.try_encode_bounded(u32::MAX, &mut buf),
3041            Err(EncodeError::MessageTooLarge)
3042        );
3043        assert!(buf.is_empty());
3044    }
3045
3046    #[test]
3047    fn pool_try_encode_bounded_within_budget_encodes_and_returns_len() {
3048        let msg = FlatMsg { value: 42 };
3049        let mut expected = alloc::vec::Vec::new();
3050        msg.encode(&mut expected);
3051        let budget = expected.len() as u32;
3052
3053        let mut pool = crate::SizeCachePool::sequential(64);
3054        let mut buf = alloc::vec::Vec::new();
3055        let len = pool.try_encode_bounded(&msg, budget, &mut buf).unwrap();
3056        assert_eq!(buf, expected);
3057        assert_eq!(len, budget);
3058    }
3059
3060    #[test]
3061    fn pool_try_encode_bounded_over_budget_errors_and_writes_nothing() {
3062        let msg = FlatMsg { value: 42 };
3063        let len = msg.encoded_len();
3064        let budget = len - 1;
3065
3066        let mut pool = crate::SizeCachePool::sequential(64);
3067        let mut buf = alloc::vec::Vec::new();
3068        assert_eq!(
3069            pool.try_encode_bounded(&msg, budget, &mut buf),
3070            Err(EncodeError::ExceedsBudget {
3071                len,
3072                max_bytes: budget
3073            })
3074        );
3075        assert!(buf.is_empty());
3076        // Pool buffer must be returned even on Err.
3077        assert_eq!(pool.try_encode_bounded(&msg, len, &mut buf).unwrap(), len);
3078    }
3079
3080    #[test]
3081    fn pool_try_encode_bounded_over_protobuf_limit_errors_as_too_large() {
3082        let msg = SizedMsg {
3083            reported_size: OVER_LIMIT,
3084        };
3085        let mut pool = crate::SizeCachePool::sequential(64);
3086        let mut buf = alloc::vec::Vec::new();
3087        assert_eq!(
3088            pool.try_encode_bounded(&msg, u32::MAX, &mut buf),
3089            Err(EncodeError::MessageTooLarge)
3090        );
3091        assert!(buf.is_empty());
3092    }
3093
3094    #[test]
3095    #[should_panic(expected = "2 GiB protobuf limit")]
3096    fn pool_encoded_len_over_limit_panics() {
3097        // SizeCachePool::encoded_len documents itself as the pooled
3098        // equivalent of Message::encoded_len — it must share the guard.
3099        let msg = SizedMsg {
3100            reported_size: OVER_LIMIT,
3101        };
3102        let mut pool = crate::SizeCachePool::sequential(1024);
3103        let _ = pool.encoded_len(&msg);
3104    }
3105
3106    #[cfg(debug_assertions)]
3107    #[test]
3108    #[should_panic(expected = "two-pass traversal mismatch")]
3109    fn encode_to_vec_ledger_catches_size_write_disagreement() {
3110        // An under-limit reported size with a no-op write_to: the guard
3111        // passes, then the debug ledger flags the two-pass divergence.
3112        let msg = SizedMsg { reported_size: 3 };
3113        let _ = msg.encode_to_vec();
3114    }
3115
3116    // ── DecodeOptions std::io::Read tests ─────────────────────────────
3117
3118    #[cfg(feature = "std")]
3119    mod reader_tests {
3120        use super::*;
3121
3122        #[test]
3123        fn decode_reader_basic() {
3124            let src = FlatMsg { value: 42 };
3125            let bytes = src.encode_to_vec();
3126            let msg: FlatMsg = DecodeOptions::new()
3127                .decode_reader(&mut bytes.as_slice())
3128                .unwrap();
3129            assert_eq!(msg.value, 42);
3130        }
3131
3132        #[test]
3133        fn decode_reader_rejects_oversize() {
3134            let src = FlatMsg { value: 42 };
3135            let bytes = src.encode_to_vec();
3136            let err = DecodeOptions::new()
3137                .with_max_message_size(1)
3138                .decode_reader::<FlatMsg>(&mut bytes.as_slice())
3139                .unwrap_err();
3140            assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
3141        }
3142
3143        #[test]
3144        fn decode_reader_exact_boundary() {
3145            // max_message_size == encoded length → success.
3146            let src = FlatMsg { value: 42 };
3147            let bytes = src.encode_to_vec();
3148            let msg: FlatMsg = DecodeOptions::new()
3149                .with_max_message_size(bytes.len())
3150                .decode_reader(&mut bytes.as_slice())
3151                .unwrap();
3152            assert_eq!(msg.value, 42);
3153        }
3154
3155        #[test]
3156        fn decode_options_reader_size_unbounded_getter_tracks_builder_order() {
3157            let opts = DecodeOptions::new();
3158            assert!(!opts.is_reader_size_unbounded());
3159
3160            let opts = opts.without_reader_size_limit();
3161            assert!(opts.is_reader_size_unbounded());
3162
3163            let opts = opts.with_max_message_size(1024);
3164            assert!(!opts.is_reader_size_unbounded());
3165        }
3166
3167        #[test]
3168        fn decode_reader_without_size_limit_does_not_overflow() {
3169            let src = FlatMsg { value: 42 };
3170            let bytes = src.encode_to_vec();
3171            let msg: FlatMsg = DecodeOptions::new()
3172                .without_reader_size_limit()
3173                .decode_reader(&mut bytes.as_slice())
3174                .unwrap();
3175            assert_eq!(msg.value, 42);
3176        }
3177
3178        #[test]
3179        fn decode_reader_with_max_message_size_after_without_limit_reenables_limit() {
3180            let src = FlatMsg { value: 42 };
3181            let bytes = src.encode_to_vec();
3182            let opts = DecodeOptions::new()
3183                .without_reader_size_limit()
3184                .with_max_message_size(1);
3185            assert!(!opts.is_reader_size_unbounded());
3186
3187            let err = opts
3188                .decode_reader::<FlatMsg>(&mut bytes.as_slice())
3189                .unwrap_err();
3190            assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
3191        }
3192
3193        #[test]
3194        fn decode_reader_without_size_limit_keeps_slice_limit() {
3195            let src = FlatMsg { value: 42 };
3196            let bytes = src.encode_to_vec();
3197            let opts = DecodeOptions::new()
3198                .with_max_message_size(1)
3199                .without_reader_size_limit();
3200            assert!(opts.is_reader_size_unbounded());
3201
3202            let slice_result: Result<FlatMsg, _> = opts.decode_from_slice(&bytes);
3203            assert_eq!(slice_result, Err(DecodeError::MessageTooLarge));
3204
3205            let msg: FlatMsg = opts.decode_reader(&mut bytes.as_slice()).unwrap();
3206            assert_eq!(msg.value, 42);
3207        }
3208
3209        #[test]
3210        fn decode_reader_propagates_read_error() {
3211            // A reader that errors immediately.
3212            struct ErrReader;
3213            impl std::io::Read for ErrReader {
3214                fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
3215                    Err(std::io::Error::new(std::io::ErrorKind::BrokenPipe, "gone"))
3216                }
3217            }
3218            let err = DecodeOptions::new()
3219                .decode_reader::<FlatMsg>(&mut ErrReader)
3220                .unwrap_err();
3221            assert_eq!(err.kind(), std::io::ErrorKind::BrokenPipe);
3222        }
3223
3224        #[test]
3225        fn decode_length_delimited_reader_basic() {
3226            let src = FlatMsg { value: 99 };
3227            let mut ld = Vec::new();
3228            src.encode_length_delimited(&mut ld);
3229            let msg: FlatMsg = DecodeOptions::new()
3230                .decode_length_delimited_reader(&mut ld.as_slice())
3231                .unwrap();
3232            assert_eq!(msg.value, 99);
3233        }
3234
3235        #[test]
3236        fn decode_length_delimited_reader_rejects_oversize_prefix() {
3237            // Length prefix claims more bytes than max_message_size allows.
3238            let src = FlatMsg { value: 99 };
3239            let mut ld = Vec::new();
3240            src.encode_length_delimited(&mut ld);
3241            let err = DecodeOptions::new()
3242                .with_max_message_size(1)
3243                .decode_length_delimited_reader::<FlatMsg>(&mut ld.as_slice())
3244                .unwrap_err();
3245            assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
3246        }
3247
3248        #[test]
3249        fn decode_length_delimited_reader_zero_length() {
3250            // A zero length prefix decodes to the default message and
3251            // consumes only the prefix byte.
3252            let stream = [0x00u8, 0xFF]; // len=0, then unrelated trailing byte
3253            let mut cursor = std::io::Cursor::new(stream);
3254            let msg: FlatMsg = DecodeOptions::new()
3255                .decode_length_delimited_reader(&mut cursor)
3256                .unwrap();
3257            assert_eq!(msg, FlatMsg::default());
3258            assert_eq!(cursor.position(), 1);
3259        }
3260
3261        #[test]
3262        fn decode_length_delimited_reader_truncated_reports_eof() {
3263            // Length prefix declares more bytes than the stream delivers.
3264            let src = FlatMsg { value: 99 };
3265            let mut ld = Vec::new();
3266            src.encode_length_delimited(&mut ld);
3267            ld.truncate(ld.len() - 1);
3268            let err = DecodeOptions::new()
3269                .decode_length_delimited_reader::<FlatMsg>(&mut ld.as_slice())
3270                .unwrap_err();
3271            assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
3272        }
3273
3274        #[test]
3275        fn decode_length_delimited_reader_huge_claim_without_delivery() {
3276            // A 5-byte prefix declaring ~2 GiB followed by EOF must fail with
3277            // UnexpectedEof without allocating the declared length up front —
3278            // the buffer only grows as bytes are actually delivered. (This
3279            // test completes instantly; before the incremental-read fix it
3280            // zero-filled a ~2 GiB buffer first.)
3281            let mut stream = Vec::new();
3282            encode_varint(0x7FFF_FFF0, &mut stream); // just under the cap
3283            let err = DecodeOptions::new()
3284                .decode_length_delimited_reader::<FlatMsg>(&mut stream.as_slice())
3285                .unwrap_err();
3286            assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
3287        }
3288
3289        #[test]
3290        fn decode_length_delimited_without_reader_size_limit_keeps_protobuf_cap() {
3291            let mut stream = Vec::new();
3292            encode_varint(0x8000_0000, &mut stream);
3293            let result: Result<FlatMsg, _> = DecodeOptions::new()
3294                .without_reader_size_limit()
3295                .decode_length_delimited(&mut stream.as_slice());
3296            assert_eq!(result, Err(DecodeError::MessageTooLarge));
3297        }
3298
3299        #[test]
3300        fn decode_length_delimited_reader_without_size_limit_keeps_protobuf_cap() {
3301            let mut stream = Vec::new();
3302            encode_varint(0x8000_0000, &mut stream);
3303            let err = DecodeOptions::new()
3304                .without_reader_size_limit()
3305                .decode_length_delimited_reader::<FlatMsg>(&mut stream.as_slice())
3306                .unwrap_err();
3307            assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
3308        }
3309
3310        #[test]
3311        fn decode_length_delimited_reader_sequential() {
3312            // Two messages in a stream — typical log-file use case.
3313            let a = FlatMsg { value: 10 };
3314            let b = FlatMsg { value: 20 };
3315            let mut stream = Vec::new();
3316            a.encode_length_delimited(&mut stream);
3317            b.encode_length_delimited(&mut stream);
3318
3319            let mut cursor = std::io::Cursor::new(stream);
3320            let first: FlatMsg = DecodeOptions::new()
3321                .decode_length_delimited_reader(&mut cursor)
3322                .unwrap();
3323            assert_eq!(first.value, 10);
3324            let second: FlatMsg = DecodeOptions::new()
3325                .decode_length_delimited_reader(&mut cursor)
3326                .unwrap();
3327            assert_eq!(second.value, 20);
3328        }
3329
3330        #[test]
3331        fn decode_length_delimited_reader_truncated_body() {
3332            // Length prefix says N bytes but reader EOFs early.
3333            let mut buf = Vec::new();
3334            crate::encoding::encode_varint(100, &mut buf);
3335            buf.push(0x08);
3336            let err = DecodeOptions::new()
3337                .decode_length_delimited_reader::<FlatMsg>(&mut buf.as_slice())
3338                .unwrap_err();
3339            assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
3340        }
3341    }
3342
3343    // ── Contiguous sink routing ────────────────────────────────────────
3344    //
3345    // The `contiguous_sink_` prefix is the filter for the `Miri` CI step
3346    // that covers the pre-sized cursor; a renamed test silently leaves that
3347    // gate.
3348
3349    /// A `BufMut` with room receives a message through `advance_mut`, not
3350    /// through `put_*`, and one with less room is staged and appended once.
3351    /// The length prefix of `encode_length_delimited` goes through `put_*`.
3352    #[test]
3353    fn contiguous_sink_writes_in_place_when_there_is_room() {
3354        let msg = FlatMsg { value: 300 };
3355        let mut probe = crate::test_doubles::Probe::default();
3356        probe.inner.reserve(64);
3357        msg.encode(&mut probe);
3358        assert_eq!((probe.advance_mut_calls, probe.put_slice_calls), (1, 0));
3359        msg.encode_length_delimited(&mut probe);
3360        assert_eq!((probe.advance_mut_calls, probe.put_slice_calls), (2, 1));
3361
3362        let mut short = crate::test_doubles::Probe {
3363            chunk_limit: Some(2),
3364            ..Default::default()
3365        };
3366        msg.encode(&mut short);
3367        assert_eq!((short.advance_mut_calls, short.put_slice_calls), (0, 1));
3368    }
3369
3370    #[test]
3371    fn contiguous_sink_every_sink_receives_the_same_bytes() {
3372        let msg = FlatMsg { value: 300 };
3373        let expected = msg.encode_to_vec();
3374        assert_eq!(expected, [0x08, 0xAC, 0x02]);
3375
3376        // Appends after existing content.
3377        let mut prefixed = b"pre".to_vec();
3378        msg.encode(&mut prefixed);
3379        assert_eq!(&prefixed[..3], b"pre");
3380        assert_eq!(&prefixed[3..], &expected[..]);
3381
3382        let mut roomy = alloc::vec::Vec::with_capacity(64);
3383        msg.encode(&mut roomy);
3384        assert_eq!(roomy, expected);
3385
3386        let mut bytes_mut = bytes::BytesMut::new();
3387        msg.encode(&mut bytes_mut);
3388        assert_eq!(&bytes_mut[..], &expected[..]);
3389
3390        let mut storage = [0u8; 3];
3391        let mut slice: &mut [u8] = &mut storage;
3392        msg.encode(&mut slice);
3393        assert_eq!(storage, [0x08, 0xAC, 0x02]);
3394
3395        let mut rope = crate::Rope::new();
3396        msg.encode(&mut rope);
3397        assert_eq!(&rope.to_contiguous_bytes()[..], &expected[..]);
3398    }
3399
3400    #[test]
3401    fn contiguous_sink_framed_and_bounded_encodes_match() {
3402        let msg = FlatMsg { value: 300 };
3403
3404        let mut framed = alloc::vec::Vec::new();
3405        msg.encode_length_delimited(&mut framed);
3406        assert_eq!(framed, [3, 0x08, 0xAC, 0x02]);
3407
3408        let mut bounded = bytes::BytesMut::new();
3409        assert_eq!(msg.try_encode_bounded(3, &mut bounded), Ok(3));
3410        assert_eq!(&bounded[..], [0x08, 0xAC, 0x02]);
3411
3412        let mut cache = SizeCache::new();
3413        let mut cached = alloc::vec::Vec::new();
3414        msg.encode_with_cache(&mut cache, &mut cached);
3415        assert_eq!(cached, [0x08, 0xAC, 0x02]);
3416    }
3417
3418    #[test]
3419    #[should_panic(expected = "compute_size declared")]
3420    fn contiguous_sink_over_writing_panics() {
3421        let msg = Mismatched {
3422            declared: 1,
3423            written: 2,
3424        };
3425        msg.encode(&mut alloc::vec::Vec::new());
3426    }
3427
3428    #[cfg(debug_assertions)]
3429    #[test]
3430    #[should_panic(expected = "two-pass traversal mismatch")]
3431    fn contiguous_sink_under_writing_is_caught_in_debug_builds() {
3432        let msg = Mismatched {
3433            declared: 4,
3434            written: 2,
3435        };
3436        msg.encode(&mut alloc::vec::Vec::new());
3437    }
3438
3439    #[cfg(not(debug_assertions))]
3440    #[test]
3441    fn contiguous_sink_under_writing_appends_written_bytes() {
3442        let msg = Mismatched {
3443            declared: 4,
3444            written: 2,
3445        };
3446        let mut buf = alloc::vec::Vec::new();
3447        msg.encode(&mut buf);
3448        assert_eq!(buf, [0x55, 0x55]);
3449    }
3450}