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}
1245
1246/// Default maximum message size: 2 GiB - 1 (matches the sub-message limit
1247/// in `merge_length_delimited` and the encode-side limit — see
1248/// [`MAX_MESSAGE_BYTES`]).
1249const DEFAULT_MAX_MESSAGE_SIZE: usize = MAX_MESSAGE_BYTES as usize;
1250
1251impl Default for DecodeOptions {
1252 fn default() -> Self {
1253 Self::new()
1254 }
1255}
1256
1257impl DecodeOptions {
1258 /// Create new decode options with defaults.
1259 ///
1260 /// Defaults:
1261 /// - `recursion_limit`: 100 (same as [`RECURSION_LIMIT`])
1262 /// - `max_message_size`: 2 GiB - 1
1263 /// - `unknown_field_limit`: 1,000,000 (same as [`DEFAULT_UNKNOWN_FIELD_LIMIT`])
1264 /// - `element_memory_limit`: 32 MiB (same as [`DEFAULT_ELEMENT_MEMORY_LIMIT`])
1265 pub fn new() -> Self {
1266 Self {
1267 recursion_limit: RECURSION_LIMIT,
1268 max_message_size: DEFAULT_MAX_MESSAGE_SIZE,
1269 unbounded_reader_size: false,
1270 unknown_field_limit: DEFAULT_UNKNOWN_FIELD_LIMIT,
1271 element_memory_limit: DEFAULT_ELEMENT_MEMORY_LIMIT,
1272 }
1273 }
1274
1275 /// Set the maximum recursion depth for nested messages.
1276 ///
1277 /// Each nested sub-message consumes one level of depth budget. When
1278 /// the budget reaches zero, decoding returns
1279 /// [`DecodeError::RecursionLimitExceeded`].
1280 ///
1281 /// Default: 100.
1282 #[must_use]
1283 pub fn with_recursion_limit(mut self, limit: u32) -> Self {
1284 self.recursion_limit = limit;
1285 self
1286 }
1287
1288 /// Set the maximum total message size in bytes.
1289 ///
1290 /// If the input buffer or length-delimited payload exceeds this size,
1291 /// decoding returns [`DecodeError::MessageTooLarge`].
1292 ///
1293 /// Values above the protobuf message-size limit (2 GiB - 1) are clamped to
1294 /// that limit. Debug builds assert on out-of-range values so accidental
1295 /// `usize::MAX` sentinels are caught during development. On `std` builds,
1296 /// use `without_reader_size_limit` when EOF-bounded `decode_reader` input
1297 /// intentionally has no byte cap.
1298 ///
1299 /// Calling this re-enables the reader byte cap, overriding any prior
1300 /// `without_reader_size_limit`.
1301 ///
1302 /// This is checked at the top-level decode entry point. Individual
1303 /// sub-messages are still bounded by the internal 2 GiB limit
1304 /// regardless of this setting.
1305 ///
1306 /// Default: 2 GiB - 1 (0x7FFF_FFFF).
1307 #[must_use]
1308 pub fn with_max_message_size(mut self, max_bytes: usize) -> Self {
1309 debug_assert!(
1310 max_bytes <= DEFAULT_MAX_MESSAGE_SIZE,
1311 "DecodeOptions::with_max_message_size clamps values above the protobuf 2 GiB limit; \
1312 on std builds, use DecodeOptions::without_reader_size_limit for intentionally \
1313 unbounded reader input — there is no unbounded slice/Buf path"
1314 );
1315 self.max_message_size = max_bytes.min(DEFAULT_MAX_MESSAGE_SIZE);
1316 self.unbounded_reader_size = false;
1317 self
1318 }
1319
1320 /// Remove the byte cap for EOF-bounded [`decode_reader`](Self::decode_reader)
1321 /// input.
1322 ///
1323 /// This is only used by the `std::io::Read` entry point that reads until
1324 /// EOF. Slice-, [`Buf`]-, and view-based entry points remain bounded by
1325 /// the configured [`with_max_message_size`](Self::with_max_message_size)
1326 /// (itself capped at the protobuf 2 GiB - 1 maximum), and length-delimited
1327 /// paths keep the same hard cap because their declared length is
1328 /// attacker-controlled.
1329 ///
1330 /// An unbounded reader can exhaust memory if the source does not end or is
1331 /// larger than available allocation capacity. Prefer
1332 /// [`with_max_message_size`](Self::with_max_message_size) for untrusted
1333 /// input.
1334 #[cfg(feature = "std")]
1335 #[must_use]
1336 pub fn without_reader_size_limit(mut self) -> Self {
1337 self.unbounded_reader_size = true;
1338 self
1339 }
1340
1341 /// Set the maximum number of unknown fields decoded per decode call.
1342 ///
1343 /// Preserved unknown fields consume this allowance. A zero allowance also
1344 /// rejects discarded unknown wire fields regardless of storage configuration.
1345 /// Positive limits retain their storage-budget semantics.
1346 ///
1347 /// Each preserved unknown field occupies a ~40-byte
1348 /// [`UnknownField`](crate::UnknownField) slot regardless of its wire
1349 /// size (a minimal field is 2 wire bytes — a ~20× amplification), so an
1350 /// input-size cap alone does not bound decoder memory; this limit does,
1351 /// at roughly `limit × 40` bytes of slot overhead. Unknown
1352 /// length-delimited *payload* bytes are not counted — they are bounded
1353 /// by the input size, which
1354 /// [`with_max_message_size`](Self::with_max_message_size) governs. When
1355 /// the limit is exceeded, decoding returns
1356 /// [`DecodeError::UnknownFieldLimitExceeded`].
1357 ///
1358 /// Zero-copy view decoding ([`decode_view`](Self::decode_view)) charges
1359 /// one slot per unknown field — including fields nested inside unknown
1360 /// groups — even though views store unknown fields as coalesced spans
1361 /// (~16 bytes per contiguous run): coalescing bounds view memory, while
1362 /// this limit bounds what converting the view to an owned message would
1363 /// materialize. Conversion replays under exactly the budget decoding
1364 /// charged, so a view that decodes within this limit always converts.
1365 ///
1366 /// Default: 1,000,000 ([`DEFAULT_UNKNOWN_FIELD_LIMIT`]).
1367 #[must_use]
1368 pub fn with_unknown_field_limit(mut self, count: usize) -> Self {
1369 self.unknown_field_limit = count;
1370 self
1371 }
1372
1373 /// Reject unknown wire fields independently of generated storage settings.
1374 /// Equivalent to a zero unknown-field allowance. Unknown closed-enum values
1375 /// are included; open-enum numbers remain valid values of known fields.
1376 /// Generated static messages retain extensions, MessageSet items and custom
1377 /// descriptor options as unknown fields, so they are rejected too. A dynamic
1378 /// message can recognize extensions registered in its descriptor pool.
1379 ///
1380 /// Deferred lazy children are checked only when materialized: constructing a
1381 /// lazy view alone does not establish rejection throughout its subtree.
1382 #[must_use]
1383 pub fn reject_unknown_fields(self) -> Self {
1384 self.with_unknown_field_limit(0)
1385 }
1386
1387 /// Set the memory this decode may materialize in the elements of
1388 /// length-delimited containers — repeated message, string and bytes fields,
1389 /// and map entries — shared across the whole decode tree rather than per
1390 /// field or per message.
1391 ///
1392 /// The lazy view family is the exception: there the budget is replayed
1393 /// per deferred subtree rather than shared, so a full traversal can
1394 /// spend it more than once. See
1395 /// [`decode_lazy_view`](Self::decode_lazy_view).
1396 ///
1397 /// This is not [`with_max_message_size`](Self::with_max_message_size) by
1398 /// another name: that bounds the bytes going *in*, this bounds what they
1399 /// expand *into*. They are not redundant, because the two are not
1400 /// proportional — an empty repeated message element is 2 wire bytes and
1401 /// `size_of::<T>()` of `Vec` footprint (measured at 256 bytes for a message
1402 /// of a few `Vec`/`String` fields), so a payload well inside any input
1403 /// bound can still materialize 128x its own size. Charging is by element
1404 /// footprint, so a budget means the same amount of memory whatever the
1405 /// element size — which a count limit could not offer.
1406 ///
1407 /// Packed scalar fields are not charged by the generated or view
1408 /// decoders, but are by the reflective `DynamicMessage` codec; see
1409 /// [`DEFAULT_ELEMENT_MEMORY_LIMIT`] for why, and for the `Vec`-doubling
1410 /// caveat on peak memory.
1411 ///
1412 /// Like every option on [`DecodeOptions`], this bounds the binary decoders
1413 /// only. The textproto parser applies the same default through its own
1414 /// knob,
1415 /// [`TextDecoder::with_element_memory_limit`](crate::text::TextDecoder::with_element_memory_limit).
1416 /// The same message decoded from JSON into a generated type is not
1417 /// charged against this budget, and the amplification it guards against
1418 /// is very nearly as large there — `{}` is three JSON bytes for the same
1419 /// element footprint. The reflective JSON parser in `buffa_descriptor`
1420 /// applies the same default, changed with
1421 /// `buffa_descriptor::DynamicMessageSeed::with_element_memory_limit`.
1422 ///
1423 /// Default: 32 MiB ([`DEFAULT_ELEMENT_MEMORY_LIMIT`]).
1424 #[must_use]
1425 pub fn with_element_memory_limit(mut self, bytes: usize) -> Self {
1426 self.element_memory_limit = bytes;
1427 self
1428 }
1429
1430 /// Returns the configured element-memory budget.
1431 #[must_use]
1432 pub fn element_memory_limit(&self) -> usize {
1433 self.element_memory_limit
1434 }
1435
1436 /// Returns the configured recursion depth limit.
1437 pub fn recursion_limit(&self) -> u32 {
1438 self.recursion_limit
1439 }
1440
1441 /// Returns the configured unknown-field limit.
1442 pub fn unknown_field_limit(&self) -> usize {
1443 self.unknown_field_limit
1444 }
1445
1446 /// Returns the configured maximum message size in bytes for bounded decode
1447 /// entry points.
1448 ///
1449 /// This returns the configured (clamped) value even when
1450 /// `without_reader_size_limit` is enabled for EOF-bounded reader input —
1451 /// the slice/`Buf`/view paths still honor it. Use
1452 /// `is_reader_size_unbounded` (std only) to inspect the reader flag.
1453 pub fn max_message_size(&self) -> usize {
1454 self.max_message_size
1455 }
1456
1457 /// Returns whether EOF-bounded reader input has no byte cap.
1458 #[cfg(feature = "std")]
1459 pub fn is_reader_size_unbounded(&self) -> bool {
1460 self.unbounded_reader_size
1461 }
1462
1463 /// Decode a message from a buffer.
1464 pub fn decode<M: Message>(&self, buf: &mut impl Buf) -> Result<M, DecodeError> {
1465 if buf.remaining() > self.max_message_size {
1466 return Err(DecodeError::MessageTooLarge);
1467 }
1468 let limit = core::cell::Cell::new(self.unknown_field_limit);
1469 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1470 let mut msg = M::default();
1471 msg.merge(
1472 buf,
1473 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1474 )?;
1475 Ok(msg)
1476 }
1477
1478 /// Decode a message from a byte slice.
1479 pub fn decode_from_slice<M: Message>(&self, data: &[u8]) -> Result<M, DecodeError> {
1480 if data.len() > self.max_message_size {
1481 return Err(DecodeError::MessageTooLarge);
1482 }
1483 self.decode_from_slice_unchecked_size(data)
1484 }
1485
1486 fn decode_from_slice_unchecked_size<M: Message>(&self, data: &[u8]) -> Result<M, DecodeError> {
1487 let limit = core::cell::Cell::new(self.unknown_field_limit);
1488 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1489 let mut msg = M::default();
1490 msg.merge(
1491 &mut &*data,
1492 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1493 )?;
1494 Ok(msg)
1495 }
1496
1497 /// Decode a length-delimited message from a buffer.
1498 pub fn decode_length_delimited<M: Message>(
1499 &self,
1500 buf: &mut impl Buf,
1501 ) -> Result<M, DecodeError> {
1502 // Enforce the 2 GiB internal safety cap even if the user sets a
1503 // larger max_message_size, to prevent allocating attacker-controlled
1504 // amounts of memory from a crafted length prefix.
1505 let max = core::cmp::min(
1506 self.max_message_size as u64,
1507 DEFAULT_MAX_MESSAGE_SIZE as u64,
1508 );
1509 let len_u64 = crate::encoding::decode_varint(buf)?;
1510 if len_u64 > max {
1511 return Err(DecodeError::MessageTooLarge);
1512 }
1513 let len = usize::try_from(len_u64).map_err(|_| DecodeError::MessageTooLarge)?;
1514 if buf.remaining() < len {
1515 return Err(DecodeError::UnexpectedEof);
1516 }
1517 let limit = buf.remaining() - len;
1518 let field_limit = core::cell::Cell::new(self.unknown_field_limit);
1519 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1520 let mut msg = M::default();
1521 msg.merge_to_limit(
1522 buf,
1523 DecodeContext::new(self.recursion_limit, &field_limit)
1524 .with_element_memory(&elem_budget),
1525 limit,
1526 )?;
1527 if buf.remaining() != limit {
1528 let remaining = buf.remaining();
1529 if remaining > limit {
1530 buf.advance(remaining - limit);
1531 } else {
1532 return Err(DecodeError::UnexpectedEof);
1533 }
1534 }
1535 Ok(msg)
1536 }
1537
1538 /// Merge fields from a buffer into an existing message.
1539 pub fn merge<M: Message>(&self, msg: &mut M, buf: &mut impl Buf) -> Result<(), DecodeError> {
1540 if buf.remaining() > self.max_message_size {
1541 return Err(DecodeError::MessageTooLarge);
1542 }
1543 let limit = core::cell::Cell::new(self.unknown_field_limit);
1544 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1545 msg.merge(
1546 buf,
1547 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1548 )
1549 }
1550
1551 /// Merge fields from a byte slice into an existing message.
1552 pub fn merge_from_slice<M: Message>(
1553 &self,
1554 msg: &mut M,
1555 data: &[u8],
1556 ) -> Result<(), DecodeError> {
1557 if data.len() > self.max_message_size {
1558 return Err(DecodeError::MessageTooLarge);
1559 }
1560 let limit = core::cell::Cell::new(self.unknown_field_limit);
1561 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1562 msg.merge(
1563 &mut &*data,
1564 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1565 )
1566 }
1567
1568 /// Decode a zero-copy view from a byte slice.
1569 ///
1570 /// Enforces `max_message_size` on the input, and passes the recursion
1571 /// limit, unknown-field limit, and element-memory budget to the view
1572 /// decoder (views charge the unknown-field limit per field, including
1573 /// fields nested in unknown groups — see
1574 /// [`with_unknown_field_limit`](Self::with_unknown_field_limit)).
1575 ///
1576 /// # Errors
1577 ///
1578 /// Returns [`DecodeError::MessageTooLarge`] for oversized input, or any
1579 /// error from the view decoder (malformed wire data,
1580 /// [`DecodeError::RecursionLimitExceeded`],
1581 /// [`DecodeError::UnknownFieldLimitExceeded`], or
1582 /// [`DecodeError::ElementMemoryLimitExceeded`]).
1583 pub fn decode_view<'a, V: crate::view::MessageView<'a>>(
1584 &self,
1585 buf: &'a [u8],
1586 ) -> Result<V, DecodeError> {
1587 if buf.len() > self.max_message_size {
1588 return Err(DecodeError::MessageTooLarge);
1589 }
1590 let limit = core::cell::Cell::new(self.unknown_field_limit);
1591 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1592 V::decode_view_with_ctx(
1593 buf,
1594 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1595 )
1596 }
1597
1598 /// Decode a lazy view from a byte slice (see
1599 /// [`LazyMessageView`](crate::view::LazyMessageView)).
1600 ///
1601 /// The budgets remaining at each deferred field's position are recorded
1602 /// and charged when that field is accessed, so the configured limits
1603 /// flow through deferred decoding. Unlike
1604 /// [`decode_view`](Self::decode_view), the unknown-field and
1605 /// element-memory limits are not enforced globally across the message
1606 /// tree at decode time: each deferred subtree independently replays the
1607 /// budgets recorded at its position, so a full traversal can materialize
1608 /// records proportional to input size. Prefer `decode_view` for
1609 /// untrusted input if the global bound matters.
1610 ///
1611 /// # Errors
1612 ///
1613 /// Returns [`DecodeError::MessageTooLarge`] for oversized input, or any
1614 /// error from decoding the message's own fields — including
1615 /// [`DecodeError::RecursionLimitExceeded`],
1616 /// [`DecodeError::UnknownFieldLimitExceeded`], or
1617 /// [`DecodeError::ElementMemoryLimitExceeded`] when the configured limits
1618 /// are exhausted by them. Deferred sub-message bytes surface errors on
1619 /// access instead.
1620 pub fn decode_lazy_view<'a, L: crate::view::LazyMessageView<'a>>(
1621 &self,
1622 buf: &'a [u8],
1623 ) -> Result<L, DecodeError> {
1624 if buf.len() > self.max_message_size {
1625 return Err(DecodeError::MessageTooLarge);
1626 }
1627 let limit = core::cell::Cell::new(self.unknown_field_limit);
1628 let elem_budget = core::cell::Cell::new(self.element_memory_limit);
1629 L::decode_lazy_with_ctx(
1630 buf,
1631 DecodeContext::new(self.recursion_limit, &limit).with_element_memory(&elem_budget),
1632 )
1633 }
1634
1635 /// Decode a message by reading all bytes from a [`std::io::Read`] source.
1636 ///
1637 /// Reads until EOF, enforces the configured reader size limit unless
1638 /// [`without_reader_size_limit`](Self::without_reader_size_limit) was
1639 /// selected, then decodes the buffered bytes. Returns `std::io::Error` to
1640 /// be compatible with `Read`-based error handling.
1641 #[cfg(feature = "std")]
1642 pub fn decode_reader<M: Message>(
1643 &self,
1644 reader: &mut impl std::io::Read,
1645 ) -> Result<M, std::io::Error> {
1646 let bytes = self.read_limited(reader)?;
1647 self.decode_from_slice_unchecked_size::<M>(&bytes)
1648 .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))
1649 }
1650
1651 /// Decode a length-delimited message from a [`std::io::Read`] source.
1652 ///
1653 /// Reads a varint length prefix, enforces `max_message_size`, reads
1654 /// exactly that many bytes, then decodes. Useful for reading sequential
1655 /// length-delimited messages from a file or stream.
1656 ///
1657 /// The declared length is treated as untrusted: the read buffer grows
1658 /// as bytes actually arrive rather than being allocated up front, so a
1659 /// source that declares a large length but never delivers the bytes
1660 /// cannot force a large allocation.
1661 #[cfg(feature = "std")]
1662 pub fn decode_length_delimited_reader<M: Message>(
1663 &self,
1664 reader: &mut impl std::io::Read,
1665 ) -> Result<M, std::io::Error> {
1666 use std::io::Read as _;
1667 let len = read_varint(reader)?;
1668 let max = core::cmp::min(
1669 self.max_message_size as u64,
1670 DEFAULT_MAX_MESSAGE_SIZE as u64,
1671 );
1672 if len > max {
1673 return Err(std::io::Error::new(
1674 std::io::ErrorKind::InvalidData,
1675 DecodeError::MessageTooLarge,
1676 ));
1677 }
1678 let len = usize::try_from(len).map_err(|_| {
1679 std::io::Error::new(
1680 std::io::ErrorKind::InvalidData,
1681 DecodeError::MessageTooLarge,
1682 )
1683 })?;
1684 // Pre-size only up to a small bound; `read_to_end` grows the buffer
1685 // geometrically as data is actually delivered, so peak allocation
1686 // tracks delivered bytes, not the wire-declared length.
1687 const INITIAL_CAPACITY_CAP: usize = 64 * 1024;
1688 let mut buf = alloc::vec::Vec::with_capacity(len.min(INITIAL_CAPACITY_CAP));
1689 reader.take(len as u64).read_to_end(&mut buf)?;
1690 if buf.len() < len {
1691 return Err(std::io::Error::new(
1692 std::io::ErrorKind::UnexpectedEof,
1693 DecodeError::UnexpectedEof,
1694 ));
1695 }
1696 self.decode_from_slice::<M>(&buf)
1697 .map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))
1698 }
1699
1700 /// Read all bytes from a reader up to the configured reader limit.
1701 #[cfg(feature = "std")]
1702 fn read_limited(
1703 &self,
1704 reader: &mut impl std::io::Read,
1705 ) -> Result<alloc::vec::Vec<u8>, std::io::Error> {
1706 use std::io::Read as _;
1707 let mut buf = alloc::vec::Vec::new();
1708 if self.unbounded_reader_size {
1709 reader.read_to_end(&mut buf)?;
1710 return Ok(buf);
1711 }
1712 reader
1713 .take((self.max_message_size as u64).saturating_add(1))
1714 .read_to_end(&mut buf)?;
1715 if buf.len() > self.max_message_size {
1716 return Err(std::io::Error::new(
1717 std::io::ErrorKind::InvalidData,
1718 DecodeError::MessageTooLarge,
1719 ));
1720 }
1721 Ok(buf)
1722 }
1723}
1724
1725/// Read a varint from a `std::io::Read` source, one byte at a time.
1726///
1727/// Mirrors the validation in [`decode_varint_slow`](crate::encoding): a
1728/// 10th byte > `0x01` (overflow bits set, or continuation bit implying an
1729/// 11th byte) is rejected.
1730#[cfg(feature = "std")]
1731fn read_varint(reader: &mut impl std::io::Read) -> Result<u64, std::io::Error> {
1732 let mut value: u64 = 0;
1733 let mut shift: u32 = 0;
1734 loop {
1735 let mut byte = [0u8; 1];
1736 reader.read_exact(&mut byte)?;
1737 let b = byte[0];
1738 if shift < 63 {
1739 value |= ((b & 0x7F) as u64) << shift;
1740 if b < 0x80 {
1741 return Ok(value);
1742 }
1743 shift += 7;
1744 } else {
1745 // 10th byte: only bit 0 maps to bit 63 of the result. A byte
1746 // > 0x01 means either data overflow (bits 1-6 set) or an 11th
1747 // byte (continuation bit 0x80 set).
1748 if b > 0x01 {
1749 return Err(std::io::Error::new(
1750 std::io::ErrorKind::InvalidData,
1751 DecodeError::VarintTooLong,
1752 ));
1753 }
1754 value |= (b as u64) << 63;
1755 return Ok(value);
1756 }
1757 }
1758}
1759
1760#[cfg(test)]
1761mod tests {
1762 use super::*;
1763 use crate::encoding::encode_varint;
1764 use crate::error::DecodeError;
1765 use crate::message_field::DefaultInstance;
1766 use crate::SizeCache;
1767
1768 // Minimal hand-written Message for testing merge_length_delimited.
1769 #[derive(Clone, Debug, Default, PartialEq)]
1770 struct FlatMsg {
1771 value: i32,
1772 }
1773
1774 impl DefaultInstance for FlatMsg {
1775 fn default_instance() -> &'static Self {
1776 static INST: crate::__private::OnceBox<FlatMsg> = crate::__private::OnceBox::new();
1777 INST.get_or_init(|| alloc::boxed::Box::new(FlatMsg::default()))
1778 }
1779 }
1780
1781 impl Message for FlatMsg {
1782 fn compute_size(&self, _cache: &mut SizeCache) -> u32 {
1783 if self.value != 0 {
1784 1 + crate::types::int32_encoded_len(self.value) as u32
1785 } else {
1786 0
1787 }
1788 }
1789
1790 fn write_to(&self, _cache: &mut SizeCache, buf: &mut impl EncodeSink) {
1791 if self.value != 0 {
1792 crate::encoding::Tag::new(1, crate::encoding::WireType::Varint).encode(buf);
1793 crate::types::encode_int32(self.value, buf);
1794 }
1795 }
1796
1797 fn merge_field(
1798 &mut self,
1799 tag: crate::encoding::Tag,
1800 buf: &mut impl Buf,
1801 _ctx: DecodeContext<'_>,
1802 ) -> Result<(), DecodeError> {
1803 match tag.field_number() {
1804 1 => {
1805 self.value = crate::types::decode_int32(buf)?;
1806 }
1807 _ => {
1808 crate::encoding::skip_field(tag, buf)?;
1809 }
1810 }
1811 Ok(())
1812 }
1813
1814 fn clear(&mut self) {
1815 *self = Self::default();
1816 }
1817 }
1818
1819 fn wire_bytes(msg: &FlatMsg) -> alloc::vec::Vec<u8> {
1820 let mut buf = alloc::vec::Vec::new();
1821 msg.encode_length_delimited(&mut buf);
1822 buf
1823 }
1824
1825 #[test]
1826 fn test_merge_length_delimited_basic() {
1827 let src = FlatMsg { value: 42 };
1828 let mut dst = FlatMsg::default();
1829 dst.merge_length_delimited(
1830 &mut wire_bytes(&src).as_slice(),
1831 crate::test_ctx(RECURSION_LIMIT),
1832 )
1833 .unwrap();
1834 assert_eq!(dst.value, 42);
1835 }
1836
1837 #[test]
1838 fn test_merge_length_delimited_merges_into_existing() {
1839 // Second merge overwrites (proto3 last-wins for scalar fields).
1840 let mut dst = FlatMsg::default();
1841 dst.merge_length_delimited(
1842 &mut wire_bytes(&FlatMsg { value: 1 }).as_slice(),
1843 crate::test_ctx(RECURSION_LIMIT),
1844 )
1845 .unwrap();
1846 assert_eq!(dst.value, 1);
1847 dst.merge_length_delimited(
1848 &mut wire_bytes(&FlatMsg { value: 2 }).as_slice(),
1849 crate::test_ctx(RECURSION_LIMIT),
1850 )
1851 .unwrap();
1852 assert_eq!(dst.value, 2);
1853 }
1854
1855 #[test]
1856 fn test_merge_length_delimited_truncated() {
1857 // Length prefix says 10 bytes but buffer contains only 2.
1858 let mut buf = alloc::vec::Vec::new();
1859 encode_varint(10, &mut buf);
1860 buf.extend_from_slice(&[0x01, 0x01]);
1861 let mut dst = FlatMsg::default();
1862 assert_eq!(
1863 dst.merge_length_delimited(&mut buf.as_slice(), crate::test_ctx(RECURSION_LIMIT)),
1864 Err(DecodeError::UnexpectedEof)
1865 );
1866 }
1867
1868 #[test]
1869 fn test_merge_length_delimited_oversized() {
1870 // Length prefix exceeds the 2 GiB safety limit.
1871 let mut buf = alloc::vec::Vec::new();
1872 encode_varint(0x8000_0000u64, &mut buf); // 2 GiB + 1
1873 let mut dst = FlatMsg::default();
1874 assert_eq!(
1875 dst.merge_length_delimited(&mut buf.as_slice(), crate::test_ctx(RECURSION_LIMIT)),
1876 Err(DecodeError::MessageTooLarge)
1877 );
1878 }
1879
1880 #[test]
1881 fn test_merge_length_delimited_recursion_limit() {
1882 // depth=1 means merge_length_delimited will decrement to 0, then any
1883 // nested call would return RecursionLimitExceeded. Passing depth=1
1884 // to merge_length_delimited itself is the boundary: it decrements to
1885 // 0 and calls merge with depth=0, which for FlatMsg (a leaf) succeeds.
1886 // Passing depth=0 directly must return RecursionLimitExceeded.
1887 let src = FlatMsg { value: 7 };
1888 let mut dst = FlatMsg::default();
1889 assert_eq!(
1890 dst.merge_length_delimited(&mut wire_bytes(&src).as_slice(), crate::test_ctx(0)),
1891 Err(DecodeError::RecursionLimitExceeded)
1892 );
1893 // depth=1 succeeds: exactly one level is consumed.
1894 dst.merge_length_delimited(&mut wire_bytes(&src).as_slice(), crate::test_ctx(1))
1895 .unwrap();
1896 assert_eq!(dst.value, 7);
1897 }
1898
1899 #[test]
1900 fn test_decode_from_slice_basic() {
1901 let src = FlatMsg { value: 42 };
1902 let bytes = src.encode_to_vec();
1903 let dst = FlatMsg::decode_from_slice(&bytes).unwrap();
1904 assert_eq!(dst.value, 42);
1905 }
1906
1907 #[test]
1908 fn test_encode_to_bytes_matches_encode_to_vec() {
1909 let src = FlatMsg { value: 42 };
1910 let vec = src.encode_to_vec();
1911 let bytes = src.encode_to_bytes();
1912 assert_eq!(vec.as_slice(), bytes.as_ref());
1913 // Round-trip through the Bytes variant.
1914 let dst = FlatMsg::decode_from_slice(&bytes).unwrap();
1915 assert_eq!(dst.value, 42);
1916 // Empty-message case: zero-length buffer is well-defined.
1917 assert!(FlatMsg::default().encode_to_bytes().is_empty());
1918 }
1919
1920 #[test]
1921 fn test_decode_from_slice_empty() {
1922 let dst = FlatMsg::decode_from_slice(&[]).unwrap();
1923 assert_eq!(dst.value, 0);
1924 }
1925
1926 #[test]
1927 fn test_decode_from_slice_invalid_returns_error() {
1928 // A lone 0xFF byte is not a valid varint tag.
1929 let result = FlatMsg::decode_from_slice(&[0xFF]);
1930 assert!(result.is_err());
1931 }
1932
1933 #[test]
1934 fn test_merge_from_slice_basic() {
1935 let src = FlatMsg { value: 7 };
1936 let bytes = src.encode_to_vec();
1937 let mut dst = FlatMsg::default();
1938 dst.merge_from_slice(&bytes).unwrap();
1939 assert_eq!(dst.value, 7);
1940 }
1941
1942 #[test]
1943 fn test_merge_from_slice_last_wins() {
1944 let src1 = FlatMsg { value: 1 };
1945 let src2 = FlatMsg { value: 2 };
1946 let mut dst = FlatMsg::default();
1947 dst.merge_from_slice(&src1.encode_to_vec()).unwrap();
1948 dst.merge_from_slice(&src2.encode_to_vec()).unwrap();
1949 // Proto3 last-wins semantics for scalar fields.
1950 assert_eq!(dst.value, 2);
1951 }
1952
1953 // ── DecodeOptions tests ──────────────────────────────────────────
1954
1955 #[test]
1956 fn test_decode_options_default_works() {
1957 let src = FlatMsg { value: 99 };
1958 let bytes = src.encode_to_vec();
1959 let msg: FlatMsg = DecodeOptions::new().decode_from_slice(&bytes).unwrap();
1960 assert_eq!(msg.value, 99);
1961 }
1962
1963 #[test]
1964 fn test_decode_options_max_message_size_rejects() {
1965 let src = FlatMsg { value: 42 };
1966 let bytes = src.encode_to_vec();
1967 // Set max size to 1 byte — smaller than the encoded message.
1968 let result: Result<FlatMsg, _> = DecodeOptions::new()
1969 .with_max_message_size(1)
1970 .decode_from_slice(&bytes);
1971 assert_eq!(result, Err(DecodeError::MessageTooLarge));
1972 }
1973
1974 #[test]
1975 fn test_decode_options_max_message_size_exact_boundary() {
1976 let src = FlatMsg { value: 42 };
1977 let bytes = src.encode_to_vec();
1978 // Exact size should succeed.
1979 let msg: FlatMsg = DecodeOptions::new()
1980 .with_max_message_size(bytes.len())
1981 .decode_from_slice(&bytes)
1982 .unwrap();
1983 assert_eq!(msg.value, 42);
1984 // One byte less should fail.
1985 let result: Result<FlatMsg, _> = DecodeOptions::new()
1986 .with_max_message_size(bytes.len() - 1)
1987 .decode_from_slice(&bytes);
1988 assert_eq!(result, Err(DecodeError::MessageTooLarge));
1989 }
1990
1991 #[test]
1992 fn test_decode_options_custom_recursion_limit() {
1993 // FlatMsg has no nested messages, so any recursion limit >= 0 works.
1994 // Just verify the API compiles and runs.
1995 let src = FlatMsg { value: 7 };
1996 let bytes = src.encode_to_vec();
1997 let msg: FlatMsg = DecodeOptions::new()
1998 .with_recursion_limit(1)
1999 .decode_from_slice(&bytes)
2000 .unwrap();
2001 assert_eq!(msg.value, 7);
2002 }
2003
2004 #[test]
2005 fn test_decode_options_merge() {
2006 let src = FlatMsg { value: 55 };
2007 let bytes = src.encode_to_vec();
2008 let mut msg = FlatMsg::default();
2009 DecodeOptions::new()
2010 .merge_from_slice(&mut msg, &bytes)
2011 .unwrap();
2012 assert_eq!(msg.value, 55);
2013 }
2014
2015 #[test]
2016 fn test_decode_options_merge_rejects_oversize() {
2017 let src = FlatMsg { value: 55 };
2018 let bytes = src.encode_to_vec();
2019 let mut msg = FlatMsg::default();
2020 let result = DecodeOptions::new()
2021 .with_max_message_size(1)
2022 .merge_from_slice(&mut msg, &bytes);
2023 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2024 }
2025
2026 #[test]
2027 fn test_decode_options_length_delimited() {
2028 let src = FlatMsg { value: 42 };
2029 let mut ld_bytes = alloc::vec::Vec::new();
2030 src.encode_length_delimited(&mut ld_bytes);
2031 let msg: FlatMsg = DecodeOptions::new()
2032 .decode_length_delimited(&mut ld_bytes.as_slice())
2033 .unwrap();
2034 assert_eq!(msg.value, 42);
2035 }
2036
2037 #[test]
2038 fn test_decode_options_length_delimited_rejects_oversize() {
2039 let src = FlatMsg { value: 42 };
2040 let mut ld_bytes = alloc::vec::Vec::new();
2041 src.encode_length_delimited(&mut ld_bytes);
2042 let result: Result<FlatMsg, _> = DecodeOptions::new()
2043 .with_max_message_size(1)
2044 .decode_length_delimited(&mut ld_bytes.as_slice());
2045 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2046 }
2047
2048 #[test]
2049 fn decode_options_getters_return_defaults() {
2050 let opts = DecodeOptions::new();
2051 assert_eq!(opts.recursion_limit(), RECURSION_LIMIT);
2052 assert_eq!(opts.max_message_size(), 0x7FFF_FFFF);
2053 assert_eq!(opts.unknown_field_limit(), DEFAULT_UNKNOWN_FIELD_LIMIT);
2054 }
2055
2056 #[test]
2057 fn decode_options_getters_return_custom_values() {
2058 let opts = DecodeOptions::new()
2059 .with_recursion_limit(42)
2060 .with_max_message_size(1024)
2061 .with_unknown_field_limit(2048);
2062 assert_eq!(opts.recursion_limit(), 42);
2063 assert_eq!(opts.max_message_size(), 1024);
2064 assert_eq!(opts.unknown_field_limit(), 2048);
2065 }
2066
2067 #[cfg(debug_assertions)]
2068 #[test]
2069 #[should_panic(expected = "protobuf 2 GiB limit")]
2070 fn decode_options_max_message_size_above_protobuf_limit_debug_asserts() {
2071 let _ = DecodeOptions::new().with_max_message_size(DEFAULT_MAX_MESSAGE_SIZE + 1);
2072 }
2073
2074 #[cfg(not(debug_assertions))]
2075 #[test]
2076 fn decode_options_max_message_size_above_protobuf_limit_saturates() {
2077 let opts = DecodeOptions::new().with_max_message_size(DEFAULT_MAX_MESSAGE_SIZE + 1);
2078 assert_eq!(opts.max_message_size(), DEFAULT_MAX_MESSAGE_SIZE);
2079 }
2080
2081 #[test]
2082 fn test_decode_options_default_impl() {
2083 // DecodeOptions::default() ≡ DecodeOptions::new().
2084 let opts = DecodeOptions::default();
2085 assert_eq!(opts.recursion_limit(), RECURSION_LIMIT);
2086 assert_eq!(opts.max_message_size(), 0x7FFF_FFFF);
2087 assert_eq!(opts.unknown_field_limit(), DEFAULT_UNKNOWN_FIELD_LIMIT);
2088 }
2089
2090 #[test]
2091 fn test_decode_options_decode_buf() {
2092 // The Buf-taking decode() variant (vs decode_from_slice).
2093 let src = FlatMsg { value: 123 };
2094 let bytes = src.encode_to_vec();
2095 let msg: FlatMsg = DecodeOptions::new().decode(&mut bytes.as_slice()).unwrap();
2096 assert_eq!(msg.value, 123);
2097 // Oversize check on the Buf variant.
2098 let result: Result<FlatMsg, _> = DecodeOptions::new()
2099 .with_max_message_size(1)
2100 .decode(&mut bytes.as_slice());
2101 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2102 }
2103
2104 #[test]
2105 fn test_decode_options_merge_buf() {
2106 // The Buf-taking merge() variant (vs merge_from_slice).
2107 let src = FlatMsg { value: 77 };
2108 let bytes = src.encode_to_vec();
2109 let mut msg = FlatMsg::default();
2110 DecodeOptions::new()
2111 .merge(&mut msg, &mut bytes.as_slice())
2112 .unwrap();
2113 assert_eq!(msg.value, 77);
2114 // Oversize check.
2115 let mut msg = FlatMsg::default();
2116 let result = DecodeOptions::new()
2117 .with_max_message_size(1)
2118 .merge(&mut msg, &mut bytes.as_slice());
2119 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2120 }
2121
2122 // ── Message trait default methods ─────────────────────────────────
2123
2124 #[test]
2125 fn test_message_encode_trait_default() {
2126 // Message::encode(buf) ≡ compute_size() then write_to(buf).
2127 let src = FlatMsg { value: 42 };
2128 let mut buf = alloc::vec::Vec::new();
2129 src.encode(&mut buf);
2130 assert_eq!(buf, src.encode_to_vec());
2131 }
2132
2133 #[test]
2134 fn test_message_decode_length_delimited_trait_default() {
2135 // The trait-level decode_length_delimited (distinct from
2136 // DecodeOptions::decode_length_delimited).
2137 let src = FlatMsg { value: 42 };
2138 let mut ld = alloc::vec::Vec::new();
2139 src.encode_length_delimited(&mut ld);
2140 let got = FlatMsg::decode_length_delimited(&mut ld.as_slice()).unwrap();
2141 assert_eq!(got.value, 42);
2142 }
2143
2144 #[test]
2145 fn test_message_decode_length_delimited_oversize() {
2146 // Length prefix > 2 GiB → MessageTooLarge.
2147 let mut buf = alloc::vec::Vec::new();
2148 encode_varint(0x8000_0000u64, &mut buf);
2149 let result = FlatMsg::decode_length_delimited(&mut buf.as_slice());
2150 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2151 }
2152
2153 #[test]
2154 fn test_message_decode_length_delimited_truncated() {
2155 // Length prefix says 10 bytes, buffer has 2.
2156 let mut buf = alloc::vec::Vec::new();
2157 encode_varint(10, &mut buf);
2158 buf.push(0x08);
2159 buf.push(0x01);
2160 let result = FlatMsg::decode_length_delimited(&mut buf.as_slice());
2161 assert_eq!(result, Err(DecodeError::UnexpectedEof));
2162 }
2163
2164 #[test]
2165 fn test_message_decode_length_delimited_with_trailing() {
2166 // Buffer has two back-to-back length-delimited messages.
2167 // decode_length_delimited should consume exactly the first one
2168 // and leave the buffer positioned at the second.
2169 let a = FlatMsg { value: 1 };
2170 let b = FlatMsg { value: 2 };
2171 let mut buf = alloc::vec::Vec::new();
2172 a.encode_length_delimited(&mut buf);
2173 b.encode_length_delimited(&mut buf);
2174
2175 let mut cur = buf.as_slice();
2176 let first = FlatMsg::decode_length_delimited(&mut cur).unwrap();
2177 assert_eq!(first.value, 1);
2178 let second = FlatMsg::decode_length_delimited(&mut cur).unwrap();
2179 assert_eq!(second.value, 2);
2180 assert!(cur.is_empty());
2181 }
2182
2183 // ── merge_group tests ─────────────────────────────────────────────
2184
2185 /// Build a group body for FlatMsg (field 1 = value) terminated by
2186 /// EndGroup with the given field number.
2187 fn group_bytes(value: i32, group_field_number: u32) -> alloc::vec::Vec<u8> {
2188 use crate::encoding::{Tag, WireType};
2189 let mut buf = alloc::vec::Vec::new();
2190 if value != 0 {
2191 Tag::new(1, WireType::Varint).encode(&mut buf);
2192 crate::types::encode_int32(value, &mut buf);
2193 }
2194 Tag::new(group_field_number, WireType::EndGroup).encode(&mut buf);
2195 buf
2196 }
2197
2198 #[test]
2199 fn test_merge_group_basic() {
2200 let data = group_bytes(42, 5);
2201 let mut dst = FlatMsg::default();
2202 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2203 .unwrap();
2204 assert_eq!(dst.value, 42);
2205 }
2206
2207 #[test]
2208 fn test_merge_group_empty() {
2209 // Group with no fields — just EndGroup.
2210 let data = group_bytes(0, 3);
2211 let mut dst = FlatMsg::default();
2212 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 3)
2213 .unwrap();
2214 assert_eq!(dst.value, 0);
2215 }
2216
2217 #[test]
2218 fn test_merge_group_merges_into_existing() {
2219 let data1 = group_bytes(1, 5);
2220 let data2 = group_bytes(2, 5);
2221 let mut dst = FlatMsg::default();
2222 dst.merge_group(&mut data1.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2223 .unwrap();
2224 assert_eq!(dst.value, 1);
2225 dst.merge_group(&mut data2.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2226 .unwrap();
2227 assert_eq!(dst.value, 2);
2228 }
2229
2230 #[test]
2231 fn test_merge_group_recursion_limit_zero() {
2232 // depth=0 should immediately fail with RecursionLimitExceeded
2233 // because merge_group decrements before entering the loop.
2234 let data = group_bytes(42, 5);
2235 let mut dst = FlatMsg::default();
2236 assert_eq!(
2237 dst.merge_group(&mut data.as_slice(), crate::test_ctx(0), 5),
2238 Err(DecodeError::RecursionLimitExceeded)
2239 );
2240 }
2241
2242 #[test]
2243 fn test_merge_group_recursion_limit_one_succeeds() {
2244 // depth=1 succeeds: merge_group decrements to 0, but FlatMsg's
2245 // merge_field doesn't recurse further.
2246 let data = group_bytes(7, 5);
2247 let mut dst = FlatMsg::default();
2248 dst.merge_group(&mut data.as_slice(), crate::test_ctx(1), 5)
2249 .unwrap();
2250 assert_eq!(dst.value, 7);
2251 }
2252
2253 #[test]
2254 fn test_merge_group_mismatched_end() {
2255 // EndGroup with wrong field number.
2256 use crate::encoding::{Tag, WireType};
2257 let mut data = alloc::vec::Vec::new();
2258 Tag::new(99, WireType::EndGroup).encode(&mut data);
2259
2260 let mut dst = FlatMsg::default();
2261 assert_eq!(
2262 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5),
2263 Err(DecodeError::InvalidEndGroup(99))
2264 );
2265 }
2266
2267 #[test]
2268 fn test_merge_group_truncated() {
2269 // Buffer ends without EndGroup tag.
2270 use crate::encoding::{Tag, WireType};
2271 let mut data = alloc::vec::Vec::new();
2272 Tag::new(1, WireType::Varint).encode(&mut data);
2273 crate::types::encode_int32(42, &mut data);
2274 // No EndGroup.
2275
2276 let mut dst = FlatMsg::default();
2277 assert_eq!(
2278 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5),
2279 Err(DecodeError::UnexpectedEof)
2280 );
2281 }
2282
2283 #[test]
2284 fn test_merge_group_empty_buffer() {
2285 let mut dst = FlatMsg::default();
2286 assert_eq!(
2287 dst.merge_group(&mut [].as_slice(), crate::test_ctx(RECURSION_LIMIT), 5),
2288 Err(DecodeError::UnexpectedEof)
2289 );
2290 }
2291
2292 #[test]
2293 fn test_merge_group_unknown_fields_skipped() {
2294 // Group body contains an unknown field (field 99) which FlatMsg
2295 // routes to skip_field; the known field (field 1) should still
2296 // be decoded.
2297 use crate::encoding::{Tag, WireType};
2298 let mut data = alloc::vec::Vec::new();
2299 // Unknown varint field 99 = 0
2300 Tag::new(99, WireType::Varint).encode(&mut data);
2301 crate::encoding::encode_varint(0, &mut data);
2302 // Known field 1 = 99
2303 Tag::new(1, WireType::Varint).encode(&mut data);
2304 crate::types::encode_int32(99, &mut data);
2305 // EndGroup(5)
2306 Tag::new(5, WireType::EndGroup).encode(&mut data);
2307
2308 let mut dst = FlatMsg::default();
2309 dst.merge_group(&mut data.as_slice(), crate::test_ctx(RECURSION_LIMIT), 5)
2310 .unwrap();
2311 assert_eq!(dst.value, 99);
2312 }
2313
2314 #[test]
2315 fn test_merge_group_trailing_data_preserved() {
2316 // After the EndGroup tag, trailing data should remain in the buffer.
2317 let mut data = group_bytes(42, 5);
2318 data.extend_from_slice(&[0xDE, 0xAD]);
2319
2320 let mut cur = data.as_slice();
2321 let mut dst = FlatMsg::default();
2322 dst.merge_group(&mut cur, crate::test_ctx(RECURSION_LIMIT), 5)
2323 .unwrap();
2324 assert_eq!(dst.value, 42);
2325 assert_eq!(cur, &[0xDE, 0xAD]);
2326 }
2327
2328 // ── read_varint (std::io::Read) tests ──────────────────────────────
2329
2330 #[cfg(feature = "std")]
2331 mod read_varint_tests {
2332 use super::super::read_varint;
2333 use crate::encoding::encode_varint;
2334
2335 #[test]
2336 fn roundtrip_values() {
2337 let cases: &[u64] = &[0, 1, 127, 128, 300, 1 << 14, 1 << 35, 1 << 63, u64::MAX];
2338 for &v in cases {
2339 let mut buf = Vec::new();
2340 encode_varint(v, &mut buf);
2341 let got = read_varint(&mut buf.as_slice()).unwrap();
2342 assert_eq!(got, v, "roundtrip failed for {v}");
2343 }
2344 }
2345
2346 #[test]
2347 fn rejects_10th_byte_overflow() {
2348 // 9 continuation bytes + 10th byte with overflow bit (0x02).
2349 // Mirrors encoding::tests::test_varint_10th_byte_overflow_rejected.
2350 let mut bad: Vec<u8> = vec![0xFF; 9];
2351 bad.push(0x02);
2352 let err = read_varint(&mut bad.as_slice()).unwrap_err();
2353 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2354 }
2355
2356 #[test]
2357 fn rejects_11th_byte() {
2358 // 10 continuation bytes — implies an 11th byte is needed.
2359 let bad: &[u8] = &[0xFF; 10];
2360 let err = read_varint(&mut &bad[..]).unwrap_err();
2361 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2362 }
2363
2364 #[test]
2365 fn u64_max_roundtrips() {
2366 // u64::MAX requires 10 bytes with the 10th byte == 0x01.
2367 let mut buf = Vec::new();
2368 encode_varint(u64::MAX, &mut buf);
2369 assert_eq!(buf.len(), 10);
2370 assert_eq!(buf[9], 0x01);
2371 let got = read_varint(&mut buf.as_slice()).unwrap();
2372 assert_eq!(got, u64::MAX);
2373 }
2374
2375 #[test]
2376 fn eof_before_terminator_is_error() {
2377 // Single continuation byte with no follow-up.
2378 let bad: &[u8] = &[0x80];
2379 let err = read_varint(&mut &bad[..]).unwrap_err();
2380 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
2381 }
2382
2383 #[test]
2384 fn empty_input_is_error() {
2385 let err = read_varint(&mut &[][..]).unwrap_err();
2386 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
2387 }
2388 }
2389
2390 // ── Encode-side 2 GiB guard tests ──────────────────────────────────
2391
2392 use crate::test_doubles::{Mismatched, SizedMsg};
2393
2394 const OVER_LIMIT: u32 = MAX_MESSAGE_BYTES + 1;
2395
2396 #[test]
2397 fn saturate_size_is_exact_below_u32_max_and_saturates_above() {
2398 assert_eq!(saturate_size(0), 0);
2399 assert_eq!(saturate_size(MAX_MESSAGE_BYTES as u64), MAX_MESSAGE_BYTES);
2400 // 2–4 GiB window: exact (this is what makes the guard byte-precise).
2401 assert_eq!(saturate_size(0x8000_0000), 0x8000_0000u32);
2402 assert_eq!(saturate_size(u32::MAX as u64), u32::MAX);
2403 assert_eq!(saturate_size(u32::MAX as u64 + 1), u32::MAX);
2404 assert_eq!(saturate_size(u64::MAX), u32::MAX);
2405 }
2406
2407 #[test]
2408 fn encode_at_exactly_max_size_is_allowed() {
2409 // The guard is strictly-greater-than: a (fake) message of exactly
2410 // MAX_MESSAGE_BYTES passes. The pre-sized path and its ledger apply
2411 // only to `BufMut` sinks, and `NullSink` lets this no-op write_to
2412 // declare 2 GiB without allocating it.
2413 let msg = SizedMsg {
2414 reported_size: MAX_MESSAGE_BYTES,
2415 };
2416 let mut sink = crate::test_doubles::NullSink;
2417 msg.encode(&mut sink);
2418 assert!(msg.try_encode(&mut sink).is_ok());
2419 }
2420
2421 #[test]
2422 #[should_panic(expected = "2 GiB protobuf limit")]
2423 fn encode_over_limit_panics() {
2424 let msg = SizedMsg {
2425 reported_size: OVER_LIMIT,
2426 };
2427 let mut buf = alloc::vec::Vec::new();
2428 msg.encode(&mut buf);
2429 }
2430
2431 #[test]
2432 #[should_panic(expected = "2 GiB protobuf limit")]
2433 fn encoded_len_over_limit_panics() {
2434 let msg = SizedMsg {
2435 reported_size: OVER_LIMIT,
2436 };
2437 let _ = msg.encoded_len();
2438 }
2439
2440 #[test]
2441 #[should_panic(expected = "2 GiB protobuf limit")]
2442 fn encode_with_cache_over_limit_panics() {
2443 let msg = SizedMsg {
2444 reported_size: OVER_LIMIT,
2445 };
2446 let mut cache = SizeCache::new();
2447 let mut buf = alloc::vec::Vec::new();
2448 msg.encode_with_cache(&mut cache, &mut buf);
2449 }
2450
2451 #[test]
2452 #[should_panic(expected = "2 GiB protobuf limit")]
2453 fn encode_to_vec_over_limit_panics() {
2454 let msg = SizedMsg {
2455 reported_size: OVER_LIMIT,
2456 };
2457 let _ = msg.encode_to_vec();
2458 }
2459
2460 #[test]
2461 #[should_panic(expected = "2 GiB protobuf limit")]
2462 fn encode_to_bytes_over_limit_panics() {
2463 let msg = SizedMsg {
2464 reported_size: OVER_LIMIT,
2465 };
2466 let _ = msg.encode_to_bytes();
2467 }
2468
2469 #[test]
2470 #[should_panic(expected = "2 GiB protobuf limit")]
2471 fn encode_length_delimited_over_limit_panics() {
2472 let msg = SizedMsg {
2473 reported_size: OVER_LIMIT,
2474 };
2475 let mut buf = alloc::vec::Vec::new();
2476 msg.encode_length_delimited(&mut buf);
2477 }
2478
2479 #[test]
2480 fn try_encode_over_limit_errors_and_writes_nothing() {
2481 let msg = SizedMsg {
2482 reported_size: OVER_LIMIT,
2483 };
2484 let mut buf = alloc::vec::Vec::new();
2485 assert_eq!(msg.try_encode(&mut buf), Err(EncodeError::MessageTooLarge));
2486 assert!(buf.is_empty(), "no bytes may reach the buffer on Err");
2487 let mut cache = SizeCache::new();
2488 assert_eq!(
2489 msg.try_encode_with_cache(&mut cache, &mut buf),
2490 Err(EncodeError::MessageTooLarge)
2491 );
2492 assert!(buf.is_empty(), "no bytes may reach the buffer on Err");
2493 assert_eq!(
2494 msg.try_encode_length_delimited(&mut buf),
2495 Err(EncodeError::MessageTooLarge)
2496 );
2497 assert!(buf.is_empty(), "not even the length prefix");
2498 assert_eq!(msg.try_encode_to_vec(), Err(EncodeError::MessageTooLarge));
2499 assert_eq!(msg.try_encode_to_bytes(), Err(EncodeError::MessageTooLarge));
2500 assert_eq!(msg.try_encoded_len(), Err(EncodeError::MessageTooLarge));
2501 }
2502
2503 #[test]
2504 fn try_encode_matches_encode_for_normal_messages() {
2505 let msg = FlatMsg { value: 42 };
2506 let mut expected = alloc::vec::Vec::new();
2507 msg.encode(&mut expected);
2508 let mut actual = alloc::vec::Vec::new();
2509 msg.try_encode(&mut actual).unwrap();
2510 assert_eq!(actual, expected);
2511 let mut cache = SizeCache::new();
2512 let mut cached = alloc::vec::Vec::new();
2513 msg.try_encode_with_cache(&mut cache, &mut cached).unwrap();
2514 assert_eq!(cached, expected);
2515 assert_eq!(msg.try_encode_to_vec().unwrap(), expected);
2516 assert_eq!(msg.try_encode_to_bytes().unwrap(), expected);
2517 assert_eq!(msg.try_encoded_len().unwrap(), expected.len() as u32);
2518
2519 let mut ld_expected = alloc::vec::Vec::new();
2520 msg.encode_length_delimited(&mut ld_expected);
2521 let mut ld_actual = alloc::vec::Vec::new();
2522 msg.try_encode_length_delimited(&mut ld_actual).unwrap();
2523 assert_eq!(ld_actual, ld_expected);
2524 }
2525
2526 #[test]
2527 fn try_encode_bounded_within_budget_encodes_and_returns_len() {
2528 let msg = FlatMsg { value: 42 };
2529 let mut expected = alloc::vec::Vec::new();
2530 msg.encode(&mut expected);
2531 let budget = expected.len() as u32;
2532
2533 let mut buf = alloc::vec::Vec::new();
2534 let len = msg.try_encode_bounded(budget, &mut buf).unwrap();
2535 assert_eq!(buf, expected);
2536 assert_eq!(len, budget);
2537
2538 // with_cache variant agrees
2539 let mut cache = SizeCache::new();
2540 let mut buf2 = alloc::vec::Vec::new();
2541 let len2 = msg
2542 .try_encode_bounded_with_cache(budget, &mut cache, &mut buf2)
2543 .unwrap();
2544 assert_eq!(buf2, expected);
2545 assert_eq!(len2, budget);
2546 }
2547
2548 #[test]
2549 fn try_encode_bounded_at_exact_limit_succeeds() {
2550 let msg = FlatMsg { value: 42 };
2551 let exact = msg.encoded_len();
2552 let mut buf = alloc::vec::Vec::new();
2553 assert!(msg.try_encode_bounded(exact, &mut buf).is_ok());
2554 }
2555
2556 #[test]
2557 fn try_encode_bounded_over_budget_errors_and_writes_nothing() {
2558 let msg = FlatMsg { value: 42 };
2559 let len = msg.encoded_len();
2560 let budget = len - 1; // one byte under
2561
2562 let mut buf = alloc::vec::Vec::new();
2563 assert_eq!(
2564 msg.try_encode_bounded(budget, &mut buf),
2565 Err(EncodeError::ExceedsBudget {
2566 len,
2567 max_bytes: budget
2568 })
2569 );
2570 assert!(buf.is_empty(), "nothing written on budget exceeded");
2571 }
2572
2573 /// "Nothing written on `Err`" has to hold for a sink that already has
2574 /// bytes in it, which is how a caller framing several messages uses one
2575 /// buffer. Every other test starts from an empty `Vec`, so the append
2576 /// case — where a partial write would corrupt the *preceding* message
2577 /// rather than produce an obviously empty one — would go unnoticed.
2578 #[test]
2579 fn try_encode_bounded_over_budget_leaves_a_populated_buffer_untouched() {
2580 let msg = FlatMsg { value: 42 };
2581 let len = msg.encoded_len();
2582 let budget = len - 1;
2583
2584 let prefix = b"already framed".to_vec();
2585 let mut buf = prefix.clone();
2586 assert_eq!(
2587 msg.try_encode_bounded(budget, &mut buf),
2588 Err(EncodeError::ExceedsBudget {
2589 len,
2590 max_bytes: budget
2591 })
2592 );
2593 assert_eq!(buf, prefix, "the bytes already in the sink must survive");
2594 }
2595
2596 #[test]
2597 fn try_encode_bounded_zero_budget_with_empty_message_succeeds() {
2598 // A default FlatMsg with value=0 encodes to 0 bytes (all defaults
2599 // are elided in proto3), so budget=0 is exactly satisfied.
2600 let msg = FlatMsg { value: 0 };
2601 let mut buf = alloc::vec::Vec::new();
2602 let len = msg.try_encode_bounded(0, &mut buf).unwrap();
2603 assert_eq!(len, 0);
2604 assert!(buf.is_empty());
2605 }
2606
2607 #[test]
2608 fn try_encode_bounded_over_protobuf_limit_errors_as_too_large() {
2609 let msg = SizedMsg {
2610 reported_size: OVER_LIMIT,
2611 };
2612 let mut buf = alloc::vec::Vec::new();
2613 assert_eq!(
2614 msg.try_encode_bounded(u32::MAX, &mut buf),
2615 Err(EncodeError::MessageTooLarge)
2616 );
2617 assert!(buf.is_empty());
2618 }
2619
2620 #[test]
2621 fn pool_try_encode_bounded_within_budget_encodes_and_returns_len() {
2622 let msg = FlatMsg { value: 42 };
2623 let mut expected = alloc::vec::Vec::new();
2624 msg.encode(&mut expected);
2625 let budget = expected.len() as u32;
2626
2627 let mut pool = crate::SizeCachePool::sequential(64);
2628 let mut buf = alloc::vec::Vec::new();
2629 let len = pool.try_encode_bounded(&msg, budget, &mut buf).unwrap();
2630 assert_eq!(buf, expected);
2631 assert_eq!(len, budget);
2632 }
2633
2634 #[test]
2635 fn pool_try_encode_bounded_over_budget_errors_and_writes_nothing() {
2636 let msg = FlatMsg { value: 42 };
2637 let len = msg.encoded_len();
2638 let budget = len - 1;
2639
2640 let mut pool = crate::SizeCachePool::sequential(64);
2641 let mut buf = alloc::vec::Vec::new();
2642 assert_eq!(
2643 pool.try_encode_bounded(&msg, budget, &mut buf),
2644 Err(EncodeError::ExceedsBudget {
2645 len,
2646 max_bytes: budget
2647 })
2648 );
2649 assert!(buf.is_empty());
2650 // Pool buffer must be returned even on Err.
2651 assert_eq!(pool.try_encode_bounded(&msg, len, &mut buf).unwrap(), len);
2652 }
2653
2654 #[test]
2655 fn pool_try_encode_bounded_over_protobuf_limit_errors_as_too_large() {
2656 let msg = SizedMsg {
2657 reported_size: OVER_LIMIT,
2658 };
2659 let mut pool = crate::SizeCachePool::sequential(64);
2660 let mut buf = alloc::vec::Vec::new();
2661 assert_eq!(
2662 pool.try_encode_bounded(&msg, u32::MAX, &mut buf),
2663 Err(EncodeError::MessageTooLarge)
2664 );
2665 assert!(buf.is_empty());
2666 }
2667
2668 #[test]
2669 #[should_panic(expected = "2 GiB protobuf limit")]
2670 fn pool_encoded_len_over_limit_panics() {
2671 // SizeCachePool::encoded_len documents itself as the pooled
2672 // equivalent of Message::encoded_len — it must share the guard.
2673 let msg = SizedMsg {
2674 reported_size: OVER_LIMIT,
2675 };
2676 let mut pool = crate::SizeCachePool::sequential(1024);
2677 let _ = pool.encoded_len(&msg);
2678 }
2679
2680 #[cfg(debug_assertions)]
2681 #[test]
2682 #[should_panic(expected = "two-pass traversal mismatch")]
2683 fn encode_to_vec_ledger_catches_size_write_disagreement() {
2684 // An under-limit reported size with a no-op write_to: the guard
2685 // passes, then the debug ledger flags the two-pass divergence.
2686 let msg = SizedMsg { reported_size: 3 };
2687 let _ = msg.encode_to_vec();
2688 }
2689
2690 // ── DecodeOptions std::io::Read tests ─────────────────────────────
2691
2692 #[cfg(feature = "std")]
2693 mod reader_tests {
2694 use super::*;
2695
2696 #[test]
2697 fn decode_reader_basic() {
2698 let src = FlatMsg { value: 42 };
2699 let bytes = src.encode_to_vec();
2700 let msg: FlatMsg = DecodeOptions::new()
2701 .decode_reader(&mut bytes.as_slice())
2702 .unwrap();
2703 assert_eq!(msg.value, 42);
2704 }
2705
2706 #[test]
2707 fn decode_reader_rejects_oversize() {
2708 let src = FlatMsg { value: 42 };
2709 let bytes = src.encode_to_vec();
2710 let err = DecodeOptions::new()
2711 .with_max_message_size(1)
2712 .decode_reader::<FlatMsg>(&mut bytes.as_slice())
2713 .unwrap_err();
2714 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2715 }
2716
2717 #[test]
2718 fn decode_reader_exact_boundary() {
2719 // max_message_size == encoded length → success.
2720 let src = FlatMsg { value: 42 };
2721 let bytes = src.encode_to_vec();
2722 let msg: FlatMsg = DecodeOptions::new()
2723 .with_max_message_size(bytes.len())
2724 .decode_reader(&mut bytes.as_slice())
2725 .unwrap();
2726 assert_eq!(msg.value, 42);
2727 }
2728
2729 #[test]
2730 fn decode_options_reader_size_unbounded_getter_tracks_builder_order() {
2731 let opts = DecodeOptions::new();
2732 assert!(!opts.is_reader_size_unbounded());
2733
2734 let opts = opts.without_reader_size_limit();
2735 assert!(opts.is_reader_size_unbounded());
2736
2737 let opts = opts.with_max_message_size(1024);
2738 assert!(!opts.is_reader_size_unbounded());
2739 }
2740
2741 #[test]
2742 fn decode_reader_without_size_limit_does_not_overflow() {
2743 let src = FlatMsg { value: 42 };
2744 let bytes = src.encode_to_vec();
2745 let msg: FlatMsg = DecodeOptions::new()
2746 .without_reader_size_limit()
2747 .decode_reader(&mut bytes.as_slice())
2748 .unwrap();
2749 assert_eq!(msg.value, 42);
2750 }
2751
2752 #[test]
2753 fn decode_reader_with_max_message_size_after_without_limit_reenables_limit() {
2754 let src = FlatMsg { value: 42 };
2755 let bytes = src.encode_to_vec();
2756 let opts = DecodeOptions::new()
2757 .without_reader_size_limit()
2758 .with_max_message_size(1);
2759 assert!(!opts.is_reader_size_unbounded());
2760
2761 let err = opts
2762 .decode_reader::<FlatMsg>(&mut bytes.as_slice())
2763 .unwrap_err();
2764 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2765 }
2766
2767 #[test]
2768 fn decode_reader_without_size_limit_keeps_slice_limit() {
2769 let src = FlatMsg { value: 42 };
2770 let bytes = src.encode_to_vec();
2771 let opts = DecodeOptions::new()
2772 .with_max_message_size(1)
2773 .without_reader_size_limit();
2774 assert!(opts.is_reader_size_unbounded());
2775
2776 let slice_result: Result<FlatMsg, _> = opts.decode_from_slice(&bytes);
2777 assert_eq!(slice_result, Err(DecodeError::MessageTooLarge));
2778
2779 let msg: FlatMsg = opts.decode_reader(&mut bytes.as_slice()).unwrap();
2780 assert_eq!(msg.value, 42);
2781 }
2782
2783 #[test]
2784 fn decode_reader_propagates_read_error() {
2785 // A reader that errors immediately.
2786 struct ErrReader;
2787 impl std::io::Read for ErrReader {
2788 fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
2789 Err(std::io::Error::new(std::io::ErrorKind::BrokenPipe, "gone"))
2790 }
2791 }
2792 let err = DecodeOptions::new()
2793 .decode_reader::<FlatMsg>(&mut ErrReader)
2794 .unwrap_err();
2795 assert_eq!(err.kind(), std::io::ErrorKind::BrokenPipe);
2796 }
2797
2798 #[test]
2799 fn decode_length_delimited_reader_basic() {
2800 let src = FlatMsg { value: 99 };
2801 let mut ld = Vec::new();
2802 src.encode_length_delimited(&mut ld);
2803 let msg: FlatMsg = DecodeOptions::new()
2804 .decode_length_delimited_reader(&mut ld.as_slice())
2805 .unwrap();
2806 assert_eq!(msg.value, 99);
2807 }
2808
2809 #[test]
2810 fn decode_length_delimited_reader_rejects_oversize_prefix() {
2811 // Length prefix claims more bytes than max_message_size allows.
2812 let src = FlatMsg { value: 99 };
2813 let mut ld = Vec::new();
2814 src.encode_length_delimited(&mut ld);
2815 let err = DecodeOptions::new()
2816 .with_max_message_size(1)
2817 .decode_length_delimited_reader::<FlatMsg>(&mut ld.as_slice())
2818 .unwrap_err();
2819 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2820 }
2821
2822 #[test]
2823 fn decode_length_delimited_reader_zero_length() {
2824 // A zero length prefix decodes to the default message and
2825 // consumes only the prefix byte.
2826 let stream = [0x00u8, 0xFF]; // len=0, then unrelated trailing byte
2827 let mut cursor = std::io::Cursor::new(stream);
2828 let msg: FlatMsg = DecodeOptions::new()
2829 .decode_length_delimited_reader(&mut cursor)
2830 .unwrap();
2831 assert_eq!(msg, FlatMsg::default());
2832 assert_eq!(cursor.position(), 1);
2833 }
2834
2835 #[test]
2836 fn decode_length_delimited_reader_truncated_reports_eof() {
2837 // Length prefix declares more bytes than the stream delivers.
2838 let src = FlatMsg { value: 99 };
2839 let mut ld = Vec::new();
2840 src.encode_length_delimited(&mut ld);
2841 ld.truncate(ld.len() - 1);
2842 let err = DecodeOptions::new()
2843 .decode_length_delimited_reader::<FlatMsg>(&mut ld.as_slice())
2844 .unwrap_err();
2845 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
2846 }
2847
2848 #[test]
2849 fn decode_length_delimited_reader_huge_claim_without_delivery() {
2850 // A 5-byte prefix declaring ~2 GiB followed by EOF must fail with
2851 // UnexpectedEof without allocating the declared length up front —
2852 // the buffer only grows as bytes are actually delivered. (This
2853 // test completes instantly; before the incremental-read fix it
2854 // zero-filled a ~2 GiB buffer first.)
2855 let mut stream = Vec::new();
2856 encode_varint(0x7FFF_FFF0, &mut stream); // just under the cap
2857 let err = DecodeOptions::new()
2858 .decode_length_delimited_reader::<FlatMsg>(&mut stream.as_slice())
2859 .unwrap_err();
2860 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
2861 }
2862
2863 #[test]
2864 fn decode_length_delimited_without_reader_size_limit_keeps_protobuf_cap() {
2865 let mut stream = Vec::new();
2866 encode_varint(0x8000_0000, &mut stream);
2867 let result: Result<FlatMsg, _> = DecodeOptions::new()
2868 .without_reader_size_limit()
2869 .decode_length_delimited(&mut stream.as_slice());
2870 assert_eq!(result, Err(DecodeError::MessageTooLarge));
2871 }
2872
2873 #[test]
2874 fn decode_length_delimited_reader_without_size_limit_keeps_protobuf_cap() {
2875 let mut stream = Vec::new();
2876 encode_varint(0x8000_0000, &mut stream);
2877 let err = DecodeOptions::new()
2878 .without_reader_size_limit()
2879 .decode_length_delimited_reader::<FlatMsg>(&mut stream.as_slice())
2880 .unwrap_err();
2881 assert_eq!(err.kind(), std::io::ErrorKind::InvalidData);
2882 }
2883
2884 #[test]
2885 fn decode_length_delimited_reader_sequential() {
2886 // Two messages in a stream — typical log-file use case.
2887 let a = FlatMsg { value: 10 };
2888 let b = FlatMsg { value: 20 };
2889 let mut stream = Vec::new();
2890 a.encode_length_delimited(&mut stream);
2891 b.encode_length_delimited(&mut stream);
2892
2893 let mut cursor = std::io::Cursor::new(stream);
2894 let first: FlatMsg = DecodeOptions::new()
2895 .decode_length_delimited_reader(&mut cursor)
2896 .unwrap();
2897 assert_eq!(first.value, 10);
2898 let second: FlatMsg = DecodeOptions::new()
2899 .decode_length_delimited_reader(&mut cursor)
2900 .unwrap();
2901 assert_eq!(second.value, 20);
2902 }
2903
2904 #[test]
2905 fn decode_length_delimited_reader_truncated_body() {
2906 // Length prefix says N bytes but reader EOFs early.
2907 let mut buf = Vec::new();
2908 crate::encoding::encode_varint(100, &mut buf);
2909 buf.push(0x08);
2910 let err = DecodeOptions::new()
2911 .decode_length_delimited_reader::<FlatMsg>(&mut buf.as_slice())
2912 .unwrap_err();
2913 assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
2914 }
2915 }
2916
2917 // ── Contiguous sink routing ────────────────────────────────────────
2918 //
2919 // The `contiguous_sink_` prefix is the filter for the `Miri` CI step
2920 // that covers the pre-sized cursor; a renamed test silently leaves that
2921 // gate.
2922
2923 /// A `BufMut` with room receives a message through `advance_mut`, not
2924 /// through `put_*`, and one with less room is staged and appended once.
2925 /// The length prefix of `encode_length_delimited` goes through `put_*`.
2926 #[test]
2927 fn contiguous_sink_writes_in_place_when_there_is_room() {
2928 let msg = FlatMsg { value: 300 };
2929 let mut probe = crate::test_doubles::Probe::default();
2930 probe.inner.reserve(64);
2931 msg.encode(&mut probe);
2932 assert_eq!((probe.advance_mut_calls, probe.put_slice_calls), (1, 0));
2933 msg.encode_length_delimited(&mut probe);
2934 assert_eq!((probe.advance_mut_calls, probe.put_slice_calls), (2, 1));
2935
2936 let mut short = crate::test_doubles::Probe {
2937 chunk_limit: Some(2),
2938 ..Default::default()
2939 };
2940 msg.encode(&mut short);
2941 assert_eq!((short.advance_mut_calls, short.put_slice_calls), (0, 1));
2942 }
2943
2944 #[test]
2945 fn contiguous_sink_every_sink_receives_the_same_bytes() {
2946 let msg = FlatMsg { value: 300 };
2947 let expected = msg.encode_to_vec();
2948 assert_eq!(expected, [0x08, 0xAC, 0x02]);
2949
2950 // Appends after existing content.
2951 let mut prefixed = b"pre".to_vec();
2952 msg.encode(&mut prefixed);
2953 assert_eq!(&prefixed[..3], b"pre");
2954 assert_eq!(&prefixed[3..], &expected[..]);
2955
2956 let mut roomy = alloc::vec::Vec::with_capacity(64);
2957 msg.encode(&mut roomy);
2958 assert_eq!(roomy, expected);
2959
2960 let mut bytes_mut = bytes::BytesMut::new();
2961 msg.encode(&mut bytes_mut);
2962 assert_eq!(&bytes_mut[..], &expected[..]);
2963
2964 let mut storage = [0u8; 3];
2965 let mut slice: &mut [u8] = &mut storage;
2966 msg.encode(&mut slice);
2967 assert_eq!(storage, [0x08, 0xAC, 0x02]);
2968
2969 let mut rope = crate::Rope::new();
2970 msg.encode(&mut rope);
2971 assert_eq!(&rope.to_contiguous_bytes()[..], &expected[..]);
2972 }
2973
2974 #[test]
2975 fn contiguous_sink_framed_and_bounded_encodes_match() {
2976 let msg = FlatMsg { value: 300 };
2977
2978 let mut framed = alloc::vec::Vec::new();
2979 msg.encode_length_delimited(&mut framed);
2980 assert_eq!(framed, [3, 0x08, 0xAC, 0x02]);
2981
2982 let mut bounded = bytes::BytesMut::new();
2983 assert_eq!(msg.try_encode_bounded(3, &mut bounded), Ok(3));
2984 assert_eq!(&bounded[..], [0x08, 0xAC, 0x02]);
2985
2986 let mut cache = SizeCache::new();
2987 let mut cached = alloc::vec::Vec::new();
2988 msg.encode_with_cache(&mut cache, &mut cached);
2989 assert_eq!(cached, [0x08, 0xAC, 0x02]);
2990 }
2991
2992 #[test]
2993 #[should_panic(expected = "compute_size declared")]
2994 fn contiguous_sink_over_writing_panics() {
2995 let msg = Mismatched {
2996 declared: 1,
2997 written: 2,
2998 };
2999 msg.encode(&mut alloc::vec::Vec::new());
3000 }
3001
3002 #[cfg(debug_assertions)]
3003 #[test]
3004 #[should_panic(expected = "two-pass traversal mismatch")]
3005 fn contiguous_sink_under_writing_is_caught_in_debug_builds() {
3006 let msg = Mismatched {
3007 declared: 4,
3008 written: 2,
3009 };
3010 msg.encode(&mut alloc::vec::Vec::new());
3011 }
3012
3013 #[cfg(not(debug_assertions))]
3014 #[test]
3015 fn contiguous_sink_under_writing_appends_written_bytes() {
3016 let msg = Mismatched {
3017 declared: 4,
3018 written: 2,
3019 };
3020 let mut buf = alloc::vec::Vec::new();
3021 msg.encode(&mut buf);
3022 assert_eq!(buf, [0x55, 0x55]);
3023 }
3024}