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