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