Skip to main content

buffa/
map_codec.rs

1// Modified by ReallyMe Technologies Limited.
2//! Generic wire codec for `map<K, V>` fields.
3//!
4//! Generated code used to inline ~40 lines of entry encode/size/merge per
5//! map field. The shape only varies by the key/value proto types, so the
6//! variation is captured here as zero-sized **codec** types (one per proto
7//! scalar type — proto types, not Rust types, because e.g. `int32` /
8//! `sint32` / `sfixed32` all map to `i32` with different encodings) plus
9//! generic per-field helpers. Generated call sites name the codecs by
10//! turbofish and let the map's own key/value types drive inference:
11//!
12//! ```ignore
13//! size += ::buffa::map_codec::field_len::<Str, Int32, _>(&self.stock, 1u32);
14//! ::buffa::map_codec::write_field::<Str, Int32, _>(&self.stock, 5u32, buf);
15//! ::buffa::map_codec::merge_entry::<Str, Int32, _>(&mut self.stock, buf, ctx)?;
16//! ```
17//!
18//! The trailing `_` is the container type ([`MapStorage`]); it is inferred from
19//! the map argument but must be written explicitly, because a partial turbofish
20//! on a three-generic function is a hard error.
21//!
22//! Everything monomorphizes to the same code the previous inline expansion
23//! produced; the fixed-width fast path (`len() * const`) is preserved via
24//! [`MapCodec::FIXED_LEN`], which folds at compile time.
25//!
26//! Message-typed values are the one asymmetry: their encoded size is
27//! two-pass (a [`SizeCache`] slot is reserved during `compute_size` and
28//! consumed during `write_to`, in identical iteration order). They get
29//! dedicated [`message_field_len`] / [`write_message_field`] helpers, and
30//! implement only [`MapValueDecode`] (via [`Msg`]) for the merge path.
31//!
32//! Every encoder has an `_omitting_defaults` twin, which generated code calls
33//! under `map_entries_omit_defaults`: it leaves a key or value at its default
34//! out of the entry, as prost does.
35
36use crate::bytes::Buf;
37use crate::encode_sink::EncodeSink;
38use crate::encoding::{check_wire_type, decode_varint, encode_varint, varint_len, Tag, WireType};
39use crate::error::DecodeError;
40use crate::types;
41use crate::{DecodeContext, EnumValue, Enumeration, Message, SizeCache};
42use core::hash::Hash;
43
44/// The default owned `HashMap` type generated `map<K, V>` fields use.
45///
46/// On `std` builds this resolves to `std::collections::HashMap<K, V,
47/// foldhash::fast::RandomState>`; on `no_std` builds it is
48/// `hashbrown::HashMap<K, V>` (which defaults to the same `foldhash` hasher).
49/// This alias is the recommended way to name a generated map field's type in
50/// downstream code, so that the concrete hasher and container stay an
51/// implementation detail.
52///
53/// Re-exported at the crate root as `buffa::Map`, alongside [`MapStorage`]:
54/// `use buffa::Map;`.
55///
56/// # Construction
57///
58/// Use [`Map::default`] to construct an empty map. The inherent
59/// `HashMap::new()` and `HashMap::with_capacity()` are only defined for the
60/// std default hasher, so they are unavailable on `Map` under `std` (and would
61/// be non-portable across the `std`/`no_std` boundary). For literals, use
62/// `[(k, v), ..].into_iter().collect()` rather than `Map::from([...])` —
63/// `From<[_; N]>` is likewise hasher-pinned in std. To preallocate, use
64/// `std::collections::HashMap::with_capacity_and_hasher(n, Default::default())`.
65///
66/// # Hasher and HashDoS
67///
68/// `foldhash::fast` is per-instance seeded — each `Map::default()` derives a
69/// fresh seed from the stack pointer mixed with a thread-local counter,
70/// layered on a process-wide seed. On `std` that process-wide seed mixes
71/// ASLR addresses with the wall clock and an allocator address. The seed is
72/// **not** drawn from a CSPRNG (unlike `std::hash::RandomState`, which seeds
73/// SipHash from `getrandom`), and `foldhash::fast` does not advertise
74/// HashDoS resistance. Treat this default as **not hardened** against
75/// adversarial hash flooding.
76///
77/// On `no_std` it is weaker than that, in a way worth stating plainly.
78/// buffa gates `foldhash/std` behind its own `std` feature, and without it
79/// foldhash drops the clock and allocator contributions: the process-wide
80/// seed is then derived from three pointers alone — a stack address, a
81/// function address, and the address of a static. On a hosted target ASLR
82/// still varies those per process. On a bare-metal target such as
83/// `thumbv7em-none-eabihf`, which buffa supports and CI checks, there is no
84/// ASLR: all three are fixed at link time, so the seed is effectively a
85/// compile-time constant and a colliding key set can be computed once from
86/// the firmware image and reused against every device running it. If you
87/// decode `map` fields with attacker-controlled keys in a `no_std` build,
88/// prefer one of the alternatives below rather than this default.
89///
90/// This is the same trade-off Google's `protobuf-v4`/upb makes (Wyhash).
91/// Consumers decoding `map` fields with attacker-controlled keys who need a
92/// hardened bound should select `MapRepr::BTreeMap` (no hashing, O(log n)
93/// worst case) or supply a SipHash-backed map via `MapRepr::Custom`. The
94/// [`MapStorage`] impl is generic over the hasher, so
95/// `std::collections::HashMap<K, V, std::hash::RandomState>` works without a
96/// newtype — only a foreign *container* type (e.g. `IndexMap`) needs one.
97pub type Map<K, V> = crate::__private::HashMap<K, V>;
98
99/// The owned collection backing a proto `map<K, V>` field.
100///
101/// The default is the `__private::HashMap` alias above; `buffa_build`'s
102/// `map_type` knob can instead select the buffa-provided
103/// [`BTreeMap`](alloc::collections::BTreeMap) (deterministic iteration order,
104/// no extra dependency) or a custom map. The runtime helpers in this
105/// module need only three operations from the container — count entries,
106/// borrow-iterate entries, and insert one entry — so this trait captures that
107/// minimal surface and lets the helpers stay generic over *which* map a field
108/// uses rather than hard-coding `__private::HashMap`.
109///
110/// The wire format is identical regardless of the container; only the in-memory
111/// owned type changes, and view types are unaffected.
112///
113/// It is re-exported at the crate root, so downstream code can write
114/// `use buffa::MapStorage;` (the longer `buffa::map_codec::MapStorage` path also
115/// works).
116///
117/// # Sealing
118///
119/// Unlike [`MapCodec`] / [`MapValueDecode`], this trait is **not** sealed.
120/// Those traits guard wire-format invariants the type system cannot express, so
121/// they must stay closed. `MapStorage` carries no wire invariant: a buggy impl
122/// can at worst iterate in an unusual order (already permitted for proto maps)
123/// or drop the consumer's own entries. Leaving it open lets a downstream crate
124/// wrap a foreign map (e.g. `indexmap::IndexMap`) in a crate-local newtype and
125/// implement `MapStorage` on it, exactly as the orphan rule requires. The
126/// wire-format seal is orthogonal and unaffected.
127///
128/// # Contract
129///
130/// - [`storage_insert`](Self::storage_insert) is **last-write-wins**, matching
131///   proto map-merge semantics (a later entry for an existing key replaces the
132///   earlier value).
133/// - [`storage_iter`](Self::storage_iter) and [`storage_len`](Self::storage_len)
134///   must agree: the iterator yields exactly `storage_len()` entries.
135///
136/// The key/value types are **associated types** ([`Key`](Self::Key) /
137/// [`Value`](Self::Value)), not trait parameters, and the per-collection key
138/// bound (`Eq + Hash` for `HashMap`, `Ord` for `BTreeMap`) lives on each impl.
139/// The generic helpers bound only `C: MapStorage<Key = …, Value = …>` and never
140/// name a key bound themselves. Because the key/value are associated, a type
141/// implements `MapStorage` at most once, so the container — and its key and
142/// value types — resolve unambiguously everywhere the trait is used as a bound.
143///
144/// # Requirements (for a *custom* map)
145///
146/// This is the canonical list of what a custom map must provide. A custom map is
147/// always a **crate-local newtype** (the orphan rule blocks implementing the
148/// buffa-owned reflection / serde traits on a foreign map), and must implement:
149///
150/// - `MapStorage` itself (this trait), naming its `Key` / `Value`.
151/// - `Default` + `Clone` + `PartialEq` + `Debug` — the generated owned message
152///   derives these, so its map field must support them.
153/// - [`FromIterator<(Key, Value)>`] — the view→owned conversion `.collect()`s
154///   entries into the owned map.
155/// - `buffa_descriptor`'s `ReflectMap` under the reflection / vtable path — not
156///   derivable, but a `BTreeMap`/`HashMap`-backed newtype can delegate to the
157///   inner map's impl. This requirement is `std`-only (vtable reflection
158///   requires `std`), so a `no_std` build never needs it.
159/// - `arbitrary::Arbitrary` under the `arbitrary` feature (derivable on a
160///   newtype). Not needed on a map field whose key or value is a custom string
161///   type or whose value is a non-default bytes type: generated code builds
162///   that field through `MapStorage` and `Default`.
163/// - `serde::Serialize` / `Deserialize` under a JSON-enabled build. The proto3
164///   JSON codec drives serialization through this trait, so **every** proto map
165///   key/value type is supported regardless of the container — there is no
166///   string-key or scalar-value restriction. (When a newtype wraps the inner map
167///   in a single field, a derived `Serialize` / `Deserialize` already routes
168///   transparently to the inner map; the with-modules call this trait's methods
169///   directly rather than the newtype's serde, so even that is only needed when
170///   the field type bypasses a with-module.)
171///
172/// The buffa-provided `HashMap` and `BTreeMap` already satisfy all of these, so
173/// selecting `BTreeMap` needs no consumer code.
174///
175/// This trait is used only as a generic bound; it is **not object-safe** (the
176/// [`storage_iter`](Self::storage_iter) RPITIT precludes `dyn MapStorage`).
177#[rustversion::attr(
178    since(1.78),
179    diagnostic::on_unimplemented(
180        message = "`{Self}` cannot be used as a buffa custom map type",
181        note = "buffa owns `MapStorage`, so a foreign type can't implement it directly (orphan rule). \
182                Wrap it in a crate-local newtype and implement `MapStorage` on the newtype. \
183                See the `custom-types` example in the buffa repository for a template."
184    )
185)]
186pub trait MapStorage {
187    /// The map key type.
188    type Key;
189    /// The map value type.
190    type Value;
191    /// Number of entries.
192    fn storage_len(&self) -> usize;
193    /// Insert one entry (last-write-wins, matching proto map-merge semantics).
194    fn storage_insert(&mut self, key: Self::Key, value: Self::Value);
195    /// Remove all entries (the field's cleared / default state), retaining
196    /// capacity where the underlying type allows. Invoked by the generated
197    /// message `clear()`.
198    fn storage_clear(&mut self);
199    /// Erase a key discarded before insertion, including after a later parse error.
200    /// A wipe-owning container overrides this; ordinary containers keep the default.
201    /// Implementations must not panic or allocate.
202    /// Called by binary and JSON map decoders when the `zeroize` feature is
203    /// enabled, including the table codec's partial and discarded entries.
204    /// With that feature disabled, temporary slots use ordinary Rust drop.
205    fn storage_erase_key(_key: &mut Self::Key) {}
206    /// Erase a value discarded before insertion. Implementations must not panic or allocate.
207    /// Like `storage_erase_key`, this hook runs only with the `zeroize` feature.
208    fn storage_erase_value(_value: &mut Self::Value) {}
209    /// Borrow-iterate entries in the container's native order.
210    fn storage_iter<'a>(&'a self) -> impl Iterator<Item = (&'a Self::Key, &'a Self::Value)>
211    where
212        Self::Key: 'a,
213        Self::Value: 'a;
214}
215
216/// Implements [`MapStorage`] for both the `std` and `no_std` `HashMap` types,
217/// generic over the hasher `S`. The buffa default `S` is `foldhash` on both
218/// paths (see [`Map`]); the `S` parameter lets `MapRepr::Custom` users reach
219/// any `BuildHasher` without a newtype. The `S: Default` bound is required so
220/// generated owned messages can `Default`-construct the field — the read-only
221/// `ReflectMap` impl in `buffa-descriptor` relaxes to `S: BuildHasher`.
222macro_rules! map_storage_hashmap {
223    ($($ty:tt)*) => {
224        impl<K: Eq + Hash, V, S: core::hash::BuildHasher + Default> MapStorage for $($ty)*<K, V, S> {
225            type Key = K;
226            type Value = V;
227            #[inline]
228            fn storage_len(&self) -> usize {
229                self.len()
230            }
231            #[inline]
232            fn storage_insert(&mut self, key: K, value: V) {
233                self.insert(key, value);
234            }
235            #[inline]
236            fn storage_clear(&mut self) {
237                self.clear();
238            }
239            #[inline]
240            fn storage_iter<'a>(&'a self) -> impl Iterator<Item = (&'a K, &'a V)>
241            where
242                K: 'a,
243                V: 'a,
244            {
245                self.iter()
246            }
247        }
248    };
249}
250#[cfg(feature = "std")]
251map_storage_hashmap!(std::collections::HashMap);
252#[cfg(not(feature = "std"))]
253map_storage_hashmap!(hashbrown::HashMap);
254
255impl<K: Ord, V> MapStorage for crate::alloc::collections::BTreeMap<K, V> {
256    type Key = K;
257    type Value = V;
258    #[inline]
259    fn storage_len(&self) -> usize {
260        self.len()
261    }
262    #[inline]
263    fn storage_insert(&mut self, key: K, value: V) {
264        self.insert(key, value);
265    }
266    #[inline]
267    fn storage_clear(&mut self) {
268        self.clear();
269    }
270    #[inline]
271    fn storage_iter<'a>(&'a self) -> impl Iterator<Item = (&'a K, &'a V)>
272    where
273        K: 'a,
274        V: 'a,
275    {
276        self.iter()
277    }
278}
279
280mod sealed {
281    /// Seals [`MapValueDecode`](super::MapValueDecode) / [`MapCodec`](super::MapCodec).
282    ///
283    /// The traits carry invariants the type system cannot enforce —
284    /// `WIRE_TYPE` must match the payload `merge` reads and `encode`
285    /// writes, and a wrong `FIXED_LEN` would make [`field_len`](super::field_len)
286    /// disagree with [`write_field`](super::write_field), corrupting output.
287    /// The proto scalar set is closed, so only buffa's own codecs implement
288    /// them.
289    pub trait Sealed {}
290}
291
292/// Decode side of a map key/value codec.
293///
294/// Implemented by every codec, including [`Msg`] for message-typed values
295/// (whose *encode* side is two-pass and lives in [`message_field_len`] /
296/// [`write_message_field`] instead of [`MapCodec`]).
297pub trait MapValueDecode: sealed::Sealed {
298    /// The Rust type this codec reads into.
299    type Value: Default;
300    /// The wire type every payload of this codec carries.
301    const WIRE_TYPE: WireType;
302    /// Whether [`merge`](Self::merge) can report
303    /// [`MapValueDecodeStatus::Unknown`].
304    ///
305    /// This is false for ordinary scalar/message codecs and true for closed
306    /// enum codecs. [`merge_entry_with_unknowns`] uses it to avoid buffering
307    /// map-entry payloads unless a value can actually force whole-entry
308    /// unknown-field preservation.
309    const MAY_RETURN_UNKNOWN: bool = false;
310
311    /// Merge one payload from `buf` into `value`.
312    ///
313    /// Returns [`MapValueDecodeStatus::Known`] in the normal case, or
314    /// [`MapValueDecodeStatus::Unknown`] when this codec is a closed enum and
315    /// the payload's numeric value is not a declared variant — letting the
316    /// caller route the whole map entry to unknown fields instead of inserting
317    /// it.
318    ///
319    /// `ctx` carries the remaining recursion and unknown-field budgets
320    /// (used by message values; scalar codecs ignore it).
321    ///
322    /// # Errors
323    ///
324    /// Returns a [`DecodeError`] on malformed payloads.
325    fn merge(
326        value: &mut Self::Value,
327        buf: &mut impl Buf,
328        ctx: DecodeContext<'_>,
329    ) -> Result<MapValueDecodeStatus, DecodeError>;
330}
331
332/// Result of decoding one map-entry key/value payload.
333#[derive(Clone, Copy, Debug, PartialEq, Eq)]
334#[non_exhaustive]
335pub enum MapValueDecodeStatus {
336    /// The payload decoded to a normal map key/value.
337    Known,
338    /// The payload was an unknown value for a closed enum.
339    ///
340    /// Proto2 map semantics require the whole outer map-entry record to be
341    /// treated as unknown in this case, not inserted with a default value.
342    Unknown,
343}
344
345/// Full (encode + size + decode) map key/value codec for non-message types.
346pub trait MapCodec: MapValueDecode {
347    /// `Some(n)` when every payload encodes to exactly `n` bytes
348    /// (fixed-width scalars and `bool`). Lets [`field_len`] fold the whole
349    /// field to `len() * entry_size` at compile time.
350    ///
351    /// Must equal the length [`encode`](Self::encode) actually writes for
352    /// every value — [`field_len`] sizes the buffer with it. (One reason the
353    /// traits are sealed.)
354    const FIXED_LEN: Option<u64> = None;
355
356    /// Encoded payload length in bytes (no tag).
357    ///
358    /// `u64`, like all size arithmetic feeding `compute_size` accumulators:
359    /// a huge `bytes`/`string` payload must surface as an exact over-limit
360    /// total at the encode entry points' 2 GiB check, never wrap.
361    fn encoded_len(value: &Self::Value) -> u64;
362
363    /// Write the payload (no tag) to `buf`.
364    fn encode(value: &Self::Value, buf: &mut impl EncodeSink);
365
366    /// Whether `value` is what a missing key or value field decodes to, which
367    /// the `*_omitting_defaults` encoders leave out of an entry: zero, `false`,
368    /// empty, an open enum's 0, or a closed enum's default (its first value).
369    /// Compared with `==`, as prost does, so `-0.0` counts as a float's default
370    /// and decodes back as `0.0`.
371    fn is_default(value: &Self::Value) -> bool;
372}
373
374/// Stamp a varint/fixed scalar codec from the existing `types::` functions.
375macro_rules! scalar_codec {
376    ($(#[$doc:meta])* $name:ident, $value:ty, $wire:expr, $fixed:expr,
377     len: $len:expr, encode: $encode:expr, decode: $decode:expr) => {
378        $(#[$doc])*
379        pub struct $name;
380
381        impl sealed::Sealed for $name {}
382
383        impl MapValueDecode for $name {
384            type Value = $value;
385            const WIRE_TYPE: WireType = $wire;
386
387            #[inline]
388            fn merge(
389                value: &mut Self::Value,
390                buf: &mut impl Buf,
391                _ctx: DecodeContext<'_>,
392            ) -> Result<MapValueDecodeStatus, DecodeError> {
393                *value = $decode(buf)?;
394                Ok(MapValueDecodeStatus::Known)
395            }
396        }
397
398        impl MapCodec for $name {
399            const FIXED_LEN: Option<u64> = $fixed;
400
401            #[inline]
402            #[allow(clippy::redundant_closure_call)]
403            fn encoded_len(value: &Self::Value) -> u64 {
404                ($len)(value) as u64
405            }
406
407            #[inline]
408            #[allow(clippy::redundant_closure_call)]
409            fn encode(value: &Self::Value, buf: &mut impl EncodeSink) {
410                ($encode)(value, buf)
411            }
412
413            #[inline]
414            #[allow(clippy::float_cmp)]
415            fn is_default(value: &Self::Value) -> bool {
416                *value == <$value as Default>::default()
417            }
418        }
419    };
420}
421
422scalar_codec!(
423    /// `int32` codec.
424    Int32, i32, WireType::Varint, None,
425    len: |v: &i32| types::int32_encoded_len(*v),
426    encode: |v: &i32, buf: &mut _| types::encode_int32(*v, buf),
427    decode: types::decode_int32
428);
429scalar_codec!(
430    /// `int64` codec.
431    Int64, i64, WireType::Varint, None,
432    len: |v: &i64| types::int64_encoded_len(*v),
433    encode: |v: &i64, buf: &mut _| types::encode_int64(*v, buf),
434    decode: types::decode_int64
435);
436scalar_codec!(
437    /// `uint32` codec.
438    Uint32, u32, WireType::Varint, None,
439    len: |v: &u32| types::uint32_encoded_len(*v),
440    encode: |v: &u32, buf: &mut _| types::encode_uint32(*v, buf),
441    decode: types::decode_uint32
442);
443scalar_codec!(
444    /// `uint64` codec.
445    Uint64, u64, WireType::Varint, None,
446    len: |v: &u64| types::uint64_encoded_len(*v),
447    encode: |v: &u64, buf: &mut _| types::encode_uint64(*v, buf),
448    decode: types::decode_uint64
449);
450scalar_codec!(
451    /// `sint32` (zigzag) codec.
452    Sint32, i32, WireType::Varint, None,
453    len: |v: &i32| types::sint32_encoded_len(*v),
454    encode: |v: &i32, buf: &mut _| types::encode_sint32(*v, buf),
455    decode: types::decode_sint32
456);
457scalar_codec!(
458    /// `sint64` (zigzag) codec.
459    Sint64, i64, WireType::Varint, None,
460    len: |v: &i64| types::sint64_encoded_len(*v),
461    encode: |v: &i64, buf: &mut _| types::encode_sint64(*v, buf),
462    decode: types::decode_sint64
463);
464scalar_codec!(
465    /// `bool` codec.
466    Bool, bool, WireType::Varint, Some(types::BOOL_ENCODED_LEN as u64),
467    len: |_: &bool| types::BOOL_ENCODED_LEN,
468    encode: |v: &bool, buf: &mut _| types::encode_bool(*v, buf),
469    decode: types::decode_bool
470);
471scalar_codec!(
472    /// `fixed32` codec.
473    Fixed32, u32, WireType::Fixed32, Some(types::FIXED32_ENCODED_LEN as u64),
474    len: |_: &u32| types::FIXED32_ENCODED_LEN,
475    encode: |v: &u32, buf: &mut _| types::encode_fixed32(*v, buf),
476    decode: types::decode_fixed32
477);
478scalar_codec!(
479    /// `fixed64` codec.
480    Fixed64, u64, WireType::Fixed64, Some(types::FIXED64_ENCODED_LEN as u64),
481    len: |_: &u64| types::FIXED64_ENCODED_LEN,
482    encode: |v: &u64, buf: &mut _| types::encode_fixed64(*v, buf),
483    decode: types::decode_fixed64
484);
485scalar_codec!(
486    /// `sfixed32` codec.
487    Sfixed32, i32, WireType::Fixed32, Some(types::FIXED32_ENCODED_LEN as u64),
488    len: |_: &i32| types::FIXED32_ENCODED_LEN,
489    encode: |v: &i32, buf: &mut _| types::encode_sfixed32(*v, buf),
490    decode: types::decode_sfixed32
491);
492scalar_codec!(
493    /// `sfixed64` codec.
494    Sfixed64, i64, WireType::Fixed64, Some(types::FIXED64_ENCODED_LEN as u64),
495    len: |_: &i64| types::FIXED64_ENCODED_LEN,
496    encode: |v: &i64, buf: &mut _| types::encode_sfixed64(*v, buf),
497    decode: types::decode_sfixed64
498);
499scalar_codec!(
500    /// `float` codec.
501    Float, f32, WireType::Fixed32, Some(types::FIXED32_ENCODED_LEN as u64),
502    len: |_: &f32| types::FIXED32_ENCODED_LEN,
503    encode: |v: &f32, buf: &mut _| types::encode_float(*v, buf),
504    decode: types::decode_float
505);
506scalar_codec!(
507    /// `double` codec.
508    Double, f64, WireType::Fixed64, Some(types::FIXED64_ENCODED_LEN as u64),
509    len: |_: &f64| types::FIXED64_ENCODED_LEN,
510    encode: |v: &f64, buf: &mut _| types::encode_double(*v, buf),
511    decode: types::decode_double
512);
513scalar_codec!(
514    /// `string` codec.
515    Str, crate::alloc::string::String, WireType::LengthDelimited, None,
516    len: |v: &crate::alloc::string::String| types::string_encoded_len(v),
517    encode: |v: &crate::alloc::string::String, buf: &mut _| types::encode_string(v, buf),
518    decode: types::decode_string
519);
520scalar_codec!(
521    /// `bytes` codec (`Vec<u8>` representation).
522    BytesVec, crate::alloc::vec::Vec<u8>, WireType::LengthDelimited, None,
523    len: |v: &crate::alloc::vec::Vec<u8>| types::bytes_encoded_len(v),
524    encode: |v: &crate::alloc::vec::Vec<u8>, buf: &mut _| types::encode_bytes(v, buf),
525    decode: types::decode_bytes
526);
527scalar_codec!(
528    /// `bytes` codec (`bytes::Bytes` representation, via the `bytes_fields`
529    /// codegen option; zero-copy when the source buffer is `Bytes`-backed).
530    BytesBuf, crate::bytes::Bytes, WireType::LengthDelimited, None,
531    len: |v: &crate::bytes::Bytes| types::bytes_encoded_len(v),
532    // Shared-aware: splices into segmented sinks by refcount.
533    encode: |v: &crate::bytes::Bytes, buf: &mut _| types::encode_shared_bytes(v, buf),
534    decode: types::decode_bytes_to_bytes
535);
536
537/// `bytes` codec for a custom [`ProtoBytes`](crate::types::ProtoBytes) map-value
538/// representation (via `bytes_type_custom`). Decodes through
539/// [`decode_length_delimited`](crate::types::ProtoBytes::decode_length_delimited),
540/// whose default delegates to `from_wire`; encodes the borrowed
541/// `&[u8]`. Generic over the value type, so the codec itself stays sealed in
542/// buffa while the concrete representation is a downstream (crate-local) type.
543pub struct ProtoBytesMap<B>(core::marker::PhantomData<B>);
544
545impl<B: crate::types::ProtoBytes> sealed::Sealed for ProtoBytesMap<B> {}
546
547impl<B: crate::types::ProtoBytes> MapValueDecode for ProtoBytesMap<B> {
548    type Value = B;
549    const WIRE_TYPE: WireType = WireType::LengthDelimited;
550
551    #[inline]
552    fn merge(
553        value: &mut Self::Value,
554        buf: &mut impl Buf,
555        ctx: DecodeContext<'_>,
556    ) -> Result<MapValueDecodeStatus, DecodeError> {
557        *value = crate::types::decode_bytes_to_ctx::<B>(buf, ctx)?;
558        Ok(MapValueDecodeStatus::Known)
559    }
560}
561
562impl<B: crate::types::ProtoBytes> MapCodec for ProtoBytesMap<B> {
563    #[inline]
564    fn encoded_len(value: &Self::Value) -> u64 {
565        types::bytes_encoded_len(value.as_ref()) as u64
566    }
567
568    #[inline]
569    fn encode(value: &Self::Value, buf: &mut impl EncodeSink) {
570        // Shared-aware: a `Bytes`-backed map value splices into segmented
571        // sinks by refcount, like top-level bytes fields.
572        types::encode_shared_bytes(value, buf);
573    }
574
575    #[inline]
576    fn is_default(value: &Self::Value) -> bool {
577        value.as_ref().is_empty()
578    }
579}
580
581/// `string` codec for a custom [`ProtoString`](crate::types::ProtoString)
582/// map key or value representation (via `string_type_custom`). Decodes through
583/// [`decode_length_delimited`](crate::types::ProtoString::decode_length_delimited)
584/// (UTF-8 validation included), whose default delegates to `from_wire`.
585/// Encodes the borrowed `&str`. Generic over the type, so the codec
586/// itself stays sealed in buffa while the concrete representation is a
587/// downstream (crate-local) type.
588///
589/// Unlike [`ProtoBytesMap`], which is value-only (proto forbids `bytes` map
590/// keys), this codec serves **both** map slots — `string` is a legal key and
591/// value type. Used as a *key*, the type additionally needs the container's
592/// `Eq + Hash` (`HashMap`) or `Ord` (`BTreeMap`) bound; that is enforced at the
593/// generated map field type via the [`MapStorage`] impls, not here.
594pub struct ProtoStringMap<S>(core::marker::PhantomData<S>);
595
596impl<S: crate::types::ProtoString> sealed::Sealed for ProtoStringMap<S> {}
597
598impl<S: crate::types::ProtoString> MapValueDecode for ProtoStringMap<S> {
599    type Value = S;
600    const WIRE_TYPE: WireType = WireType::LengthDelimited;
601
602    #[inline]
603    fn merge(
604        value: &mut Self::Value,
605        buf: &mut impl Buf,
606        ctx: DecodeContext<'_>,
607    ) -> Result<MapValueDecodeStatus, DecodeError> {
608        *value = crate::types::decode_string_to_ctx::<S>(buf, ctx)?;
609        Ok(MapValueDecodeStatus::Known)
610    }
611}
612
613impl<S: crate::types::ProtoString> MapCodec for ProtoStringMap<S> {
614    #[inline]
615    fn encoded_len(value: &Self::Value) -> u64 {
616        types::string_encoded_len(value.as_ref()) as u64
617    }
618
619    #[inline]
620    fn encode(value: &Self::Value, buf: &mut impl EncodeSink) {
621        types::encode_string(value.as_ref(), buf);
622    }
623
624    #[inline]
625    fn is_default(value: &Self::Value) -> bool {
626        value.as_ref().is_empty()
627    }
628}
629
630/// Open-enum codec: values decode into [`EnumValue<E>`], preserving unknown
631/// numbers.
632pub struct OpenEnum<E>(core::marker::PhantomData<E>);
633
634impl<E: Enumeration> sealed::Sealed for OpenEnum<E> {}
635
636impl<E: Enumeration> MapValueDecode for OpenEnum<E> {
637    type Value = EnumValue<E>;
638    const WIRE_TYPE: WireType = WireType::Varint;
639
640    #[inline]
641    fn merge(
642        value: &mut Self::Value,
643        buf: &mut impl Buf,
644        _ctx: DecodeContext<'_>,
645    ) -> Result<MapValueDecodeStatus, DecodeError> {
646        *value = EnumValue::from(types::decode_int32(buf)?);
647        Ok(MapValueDecodeStatus::Known)
648    }
649}
650
651impl<E: Enumeration> MapCodec for OpenEnum<E> {
652    #[inline]
653    fn encoded_len(value: &Self::Value) -> u64 {
654        types::int32_encoded_len(value.to_i32()) as u64
655    }
656
657    #[inline]
658    fn encode(value: &Self::Value, buf: &mut impl EncodeSink) {
659        types::encode_int32(value.to_i32(), buf);
660    }
661
662    #[inline]
663    fn is_default(value: &Self::Value) -> bool {
664        value.to_i32() == 0
665    }
666}
667
668/// Closed-enum codec: values decode into the bare enum `E`.
669///
670/// Unknown numeric values report [`MapValueDecodeStatus::Unknown`], letting
671/// [`merge_entry_with_unknowns`] route the whole map-entry record to unknown
672/// fields instead of inserting a default-valued entry.
673pub struct ClosedEnum<E>(core::marker::PhantomData<E>);
674
675impl<E: Enumeration + Default> sealed::Sealed for ClosedEnum<E> {}
676
677impl<E: Enumeration + Default> MapValueDecode for ClosedEnum<E> {
678    type Value = E;
679    const WIRE_TYPE: WireType = WireType::Varint;
680    const MAY_RETURN_UNKNOWN: bool = true;
681
682    #[inline]
683    fn merge(
684        value: &mut Self::Value,
685        buf: &mut impl Buf,
686        _ctx: DecodeContext<'_>,
687    ) -> Result<MapValueDecodeStatus, DecodeError> {
688        let raw = types::decode_int32(buf)?;
689        if let Some(v) = E::from_i32(raw) {
690            *value = v;
691            Ok(MapValueDecodeStatus::Known)
692        } else {
693            Ok(MapValueDecodeStatus::Unknown)
694        }
695    }
696}
697
698impl<E: Enumeration + Default> MapCodec for ClosedEnum<E> {
699    #[inline]
700    fn encoded_len(value: &Self::Value) -> u64 {
701        types::int32_encoded_len(value.to_i32()) as u64
702    }
703
704    #[inline]
705    fn encode(value: &Self::Value, buf: &mut impl EncodeSink) {
706        types::encode_int32(value.to_i32(), buf);
707    }
708
709    #[inline]
710    fn is_default(value: &Self::Value) -> bool {
711        *value == E::default()
712    }
713}
714
715/// Message-value codec (decode side only — encode is two-pass via
716/// [`message_field_len`] / [`write_message_field`]).
717pub struct Msg<M>(core::marker::PhantomData<M>);
718
719impl<M: Message + Default> sealed::Sealed for Msg<M> {}
720
721impl<M: Message + Default> MapValueDecode for Msg<M> {
722    type Value = M;
723    const WIRE_TYPE: WireType = WireType::LengthDelimited;
724
725    #[inline]
726    fn merge(
727        value: &mut Self::Value,
728        buf: &mut impl Buf,
729        ctx: DecodeContext<'_>,
730    ) -> Result<MapValueDecodeStatus, DecodeError> {
731        Message::merge_length_delimited(value, buf, ctx)?;
732        Ok(MapValueDecodeStatus::Known)
733    }
734}
735
736/// Key tag (field 1) and value tag (field 2) are both single-byte for every
737/// wire type, so each entry carries exactly two tag bytes.
738const ENTRY_TAG_LEN: u64 = 2;
739
740#[inline]
741fn entry_len<KC: MapCodec, VC: MapCodec>(k: &KC::Value, v: &VC::Value) -> u64 {
742    ENTRY_TAG_LEN + KC::encoded_len(k) + VC::encoded_len(v)
743}
744
745/// Total encoded length of a scalar-valued map field, including each entry's
746/// outer tag and length prefix.
747///
748/// `outer_tag_len` is the encoded length of the field's outer tag (a codegen
749/// constant). When both codecs are fixed-width the per-entry size is a
750/// compile-time constant and the loop folds to `len() * entry`.
751pub fn field_len<KC: MapCodec, VC: MapCodec, C>(map: &C, outer_tag_len: u64) -> u64
752where
753    C: MapStorage<Key = KC::Value, Value = VC::Value>,
754{
755    if let (Some(kf), Some(vf)) = (KC::FIXED_LEN, VC::FIXED_LEN) {
756        let entry = ENTRY_TAG_LEN + kf + vf;
757        return map.storage_len() as u64 * (outer_tag_len + varint_len(entry) as u64 + entry);
758    }
759    let mut size = 0u64;
760    for (k, v) in map.storage_iter() {
761        let entry = entry_len::<KC, VC>(k, v);
762        size += outer_tag_len + varint_len(entry) as u64 + entry;
763    }
764    size
765}
766
767/// Write a scalar-valued map field: one `field_number`-tagged,
768/// length-prefixed entry per element.
769pub fn write_field<KC: MapCodec, VC: MapCodec, C>(
770    map: &C,
771    field_number: u32,
772    buf: &mut impl EncodeSink,
773) where
774    C: MapStorage<Key = KC::Value, Value = VC::Value>,
775{
776    for (k, v) in map.storage_iter() {
777        let entry = entry_len::<KC, VC>(k, v);
778        Tag::new(field_number, WireType::LengthDelimited).encode(buf);
779        encode_varint(entry, buf);
780        Tag::new(1, KC::WIRE_TYPE).encode(buf);
781        KC::encode(k, buf);
782        Tag::new(2, VC::WIRE_TYPE).encode(buf);
783        VC::encode(v, buf);
784    }
785}
786
787/// Total encoded length of a message-valued map field.
788///
789/// Reserves one [`SizeCache`] slot per entry (in map iteration order);
790/// [`write_message_field`] consumes the slots in the same order — both
791/// helpers iterate the same map, so the orders match by construction.
792pub fn message_field_len<KC: MapCodec, M: Message, C>(
793    map: &C,
794    outer_tag_len: u64,
795    cache: &mut SizeCache,
796) -> u64
797where
798    C: MapStorage<Key = KC::Value, Value = M>,
799{
800    let mut size = 0u64;
801    for (k, v) in map.storage_iter() {
802        let slot = cache.reserve();
803        let inner = v.compute_size(cache);
804        cache.set(slot, inner);
805        let entry =
806            ENTRY_TAG_LEN + KC::encoded_len(k) + varint_len(inner as u64) as u64 + inner as u64;
807        size += outer_tag_len + varint_len(entry) as u64 + entry;
808    }
809    size
810}
811
812/// Write a message-valued map field, consuming the [`SizeCache`] slots
813/// reserved by [`message_field_len`].
814pub fn write_message_field<KC: MapCodec, M: Message, C>(
815    map: &C,
816    field_number: u32,
817    cache: &mut SizeCache,
818    buf: &mut impl EncodeSink,
819) where
820    C: MapStorage<Key = KC::Value, Value = M>,
821{
822    for (k, v) in map.storage_iter() {
823        let inner = cache.consume_next();
824        let entry =
825            ENTRY_TAG_LEN + KC::encoded_len(k) + varint_len(inner as u64) as u64 + inner as u64;
826        Tag::new(field_number, WireType::LengthDelimited).encode(buf);
827        encode_varint(entry, buf);
828        Tag::new(1, KC::WIRE_TYPE).encode(buf);
829        KC::encode(k, buf);
830        Tag::new(2, WireType::LengthDelimited).encode(buf);
831        encode_varint(inner as u64, buf);
832        v.write_to(cache, buf);
833    }
834}
835
836/// Tag length of an entry's key (field 1) or value (field 2), one byte for
837/// every wire type.
838const ENTRY_FIELD_TAG_LEN: u64 = 1;
839
840/// Which of an entry's fields the `_omitting_defaults` encoders leave out,
841/// decided once for the size and the write of the entry.
842struct Omitted {
843    key: bool,
844    value: bool,
845}
846
847impl Omitted {
848    #[inline]
849    fn of<KC: MapCodec, VC: MapCodec>(k: &KC::Value, v: &VC::Value) -> Self {
850        Self {
851            key: KC::is_default(k),
852            value: VC::is_default(v),
853        }
854    }
855
856    /// Encoded length of the entry's fields, the length prefix excluded.
857    #[inline]
858    fn entry_len<KC: MapCodec, VC: MapCodec>(&self, k: &KC::Value, v: &VC::Value) -> u64 {
859        let value = if self.value {
860            0
861        } else {
862            ENTRY_FIELD_TAG_LEN + VC::encoded_len(v)
863        };
864        sparse_key_len::<KC>(self.key, k) + value
865    }
866}
867
868/// Encoded length of an entry's key field, nothing when it is left out.
869#[inline]
870fn sparse_key_len<KC: MapCodec>(omitted: bool, k: &KC::Value) -> u64 {
871    if omitted {
872        0
873    } else {
874        ENTRY_FIELD_TAG_LEN + KC::encoded_len(k)
875    }
876}
877
878/// Encoded length of an entry's message value field, nothing for a value that
879/// encodes to nothing.
880#[inline]
881fn sparse_message_len(inner: u32) -> u64 {
882    if inner == 0 {
883        0
884    } else {
885        ENTRY_FIELD_TAG_LEN + varint_len(inner as u64) as u64 + inner as u64
886    }
887}
888
889/// [`field_len`] for entries that leave a default key or value out, as
890/// [`write_field_omitting_defaults`] writes them.
891pub fn field_len_omitting_defaults<KC: MapCodec, VC: MapCodec, C>(
892    map: &C,
893    outer_tag_len: u64,
894) -> u64
895where
896    C: MapStorage<Key = KC::Value, Value = VC::Value>,
897{
898    let mut size = 0u64;
899    for (k, v) in map.storage_iter() {
900        let entry = Omitted::of::<KC, VC>(k, v).entry_len::<KC, VC>(k, v);
901        size += outer_tag_len + varint_len(entry) as u64 + entry;
902    }
903    size
904}
905
906/// [`write_field`], leaving a key or value at its default out of its entry, as
907/// prost does. The entry decodes to the same key and value, except that a
908/// `-0.0` float decodes as `0.0`.
909pub fn write_field_omitting_defaults<KC: MapCodec, VC: MapCodec, C>(
910    map: &C,
911    field_number: u32,
912    buf: &mut impl EncodeSink,
913) where
914    C: MapStorage<Key = KC::Value, Value = VC::Value>,
915{
916    for (k, v) in map.storage_iter() {
917        let omitted = Omitted::of::<KC, VC>(k, v);
918        Tag::new(field_number, WireType::LengthDelimited).encode(buf);
919        encode_varint(omitted.entry_len::<KC, VC>(k, v), buf);
920        if !omitted.key {
921            Tag::new(1, KC::WIRE_TYPE).encode(buf);
922            KC::encode(k, buf);
923        }
924        if !omitted.value {
925            Tag::new(2, VC::WIRE_TYPE).encode(buf);
926            VC::encode(v, buf);
927        }
928    }
929}
930
931/// [`message_field_len`] for entries that leave a default key or a message
932/// that encodes to nothing out, as [`write_message_field_omitting_defaults`]
933/// writes them.
934pub fn message_field_len_omitting_defaults<KC: MapCodec, M: Message, C>(
935    map: &C,
936    outer_tag_len: u64,
937    cache: &mut SizeCache,
938) -> u64
939where
940    C: MapStorage<Key = KC::Value, Value = M>,
941{
942    let mut size = 0u64;
943    for (k, v) in map.storage_iter() {
944        let slot = cache.reserve();
945        let inner = v.compute_size(cache);
946        cache.set(slot, inner);
947        let entry = sparse_key_len::<KC>(KC::is_default(k), k) + sparse_message_len(inner);
948        size += outer_tag_len + varint_len(entry) as u64 + entry;
949    }
950    size
951}
952
953/// [`write_message_field`], leaving a default key or a message that encodes to
954/// nothing out of its entry. prost leaves out a message equal to its default
955/// instead, which can still encode a field, such as a `required` one.
956pub fn write_message_field_omitting_defaults<KC: MapCodec, M: Message, C>(
957    map: &C,
958    field_number: u32,
959    cache: &mut SizeCache,
960    buf: &mut impl EncodeSink,
961) where
962    C: MapStorage<Key = KC::Value, Value = M>,
963{
964    for (k, v) in map.storage_iter() {
965        let inner = cache.consume_next();
966        let key_omitted = KC::is_default(k);
967        Tag::new(field_number, WireType::LengthDelimited).encode(buf);
968        encode_varint(
969            sparse_key_len::<KC>(key_omitted, k) + sparse_message_len(inner),
970            buf,
971        );
972        if !key_omitted {
973            Tag::new(1, KC::WIRE_TYPE).encode(buf);
974            KC::encode(k, buf);
975        }
976        if inner != 0 {
977            Tag::new(2, WireType::LengthDelimited).encode(buf);
978            encode_varint(inner as u64, buf);
979        }
980        // Writes nothing for an empty value, but consumes the slots its
981        // `compute_size` reserved.
982        v.write_to(cache, buf);
983    }
984}
985
986fn merge_entry_contents<KC, VC>(
987    key: &mut KC::Value,
988    val: &mut VC::Value,
989    buf: &mut impl Buf,
990    ctx: DecodeContext<'_>,
991) -> Result<MapValueDecodeStatus, DecodeError>
992where
993    KC: MapValueDecode,
994    VC: MapValueDecode,
995{
996    // Track the *value* field's status with last-wins semantics: only the
997    // final field-2 occurrence decides whether the entry is unknown, matching
998    // the protobuf reference implementation. Map keys are never closed enums,
999    // so the key codec always returns `Known` and is ignored here.
1000    let mut val_status = MapValueDecodeStatus::Known;
1001    while buf.has_remaining() {
1002        let entry_tag = Tag::decode(buf)?;
1003        match entry_tag.field_number() {
1004            1 => {
1005                check_wire_type(entry_tag, KC::WIRE_TYPE)?;
1006                KC::merge(key, buf, ctx)?;
1007            }
1008            2 => {
1009                check_wire_type(entry_tag, VC::WIRE_TYPE)?;
1010                val_status = VC::merge(val, buf, ctx)?;
1011                if matches!(val_status, MapValueDecodeStatus::Unknown) {
1012                    ctx.check_unknown_field()?;
1013                }
1014            }
1015            _ => {
1016                crate::encoding::skip_unknown_field(entry_tag, buf, ctx)?;
1017            }
1018        }
1019    }
1020    Ok(val_status)
1021}
1022
1023/// Decode one length-prefixed map entry from `buf`.
1024///
1025/// Closed-enum entries with unknown values are skipped. Use
1026/// [`merge_entry_with_unknowns`] when generated code has a parent
1027/// `UnknownFields` set available and needs to preserve those skipped entries.
1028///
1029/// # Errors
1030///
1031/// As [`merge_entry_with_unknowns`], including
1032/// [`DecodeError::UnexpectedEof`] for an entry that runs past the message `ctx`
1033/// is decoding.
1034pub fn merge_entry<KC, VC, C>(
1035    map: &mut C,
1036    buf: &mut impl Buf,
1037    ctx: DecodeContext<'_>,
1038) -> Result<(), DecodeError>
1039where
1040    KC: MapValueDecode,
1041    VC: MapValueDecode,
1042    C: MapStorage<Key = KC::Value, Value = VC::Value>,
1043{
1044    merge_entry_with_unknowns::<KC, VC, C>(map, buf, ctx, None)
1045}
1046
1047/// Decode one length-prefixed map entry from `buf`, inserting it unless the
1048/// value is an unknown closed-enum number — in which case the whole entry is
1049/// optionally preserved as an unknown-field record.
1050///
1051/// Implements proto map-entry semantics: missing key/value fields take
1052/// their type defaults, repeated occurrences of a scalar key or value within
1053/// one entry last-win while repeated occurrences of a message value merge,
1054/// and unknown entry fields are skipped.
1055///
1056/// If the *final* value-field occurrence in the entry is an unknown
1057/// closed-enum number, the entry is not inserted. When `unknown_fields` is
1058/// `Some((field_number, fields))`, the whole original map-entry payload is
1059/// preserved verbatim as a length-delimited unknown field with the outer map
1060/// field number.
1061///
1062/// The entry must end within the message `ctx` is decoding (see
1063/// [`DecodeContext`]), and each key or value within the entry.
1064///
1065/// # Errors
1066///
1067/// Returns a [`DecodeError`] on malformed lengths, payloads, or wire-type
1068/// mismatches inside the entry, and [`DecodeError::UnexpectedEof`] if the entry
1069/// runs past the end of the buffer or of the enclosing message.
1070pub fn merge_entry_with_unknowns<KC, VC, C>(
1071    map: &mut C,
1072    buf: &mut impl Buf,
1073    ctx: DecodeContext<'_>,
1074    unknown_fields: Option<(u32, &mut crate::UnknownFields)>,
1075) -> Result<(), DecodeError>
1076where
1077    KC: MapValueDecode,
1078    VC: MapValueDecode,
1079    C: MapStorage<Key = KC::Value, Value = VC::Value>,
1080{
1081    let entry_len = decode_varint(buf)?;
1082    let entry_len = usize::try_from(entry_len).map_err(|_| DecodeError::MessageTooLarge)?;
1083    // The entry must also end within the message that holds the map.
1084    ctx.check_len(buf.remaining(), entry_len)?;
1085    // An entry amplifies exactly as a repeated element does, and by the same
1086    // route: a message value omitted from the wire still materializes a whole
1087    // `VC::Value` in the map, and a few bytes of key buy a distinct slot. Charge
1088    // both halves before decoding either, so a doomed entry costs the check
1089    // rather than the work.
1090    ctx.register_element_memory(
1091        core::mem::size_of::<KC::Value>() + core::mem::size_of::<VC::Value>(),
1092    )?;
1093    let mut key = crate::erasing::Erasing::new(KC::Value::default(), C::storage_erase_key);
1094    let mut val = crate::erasing::Erasing::new(VC::Value::default(), C::storage_erase_value);
1095
1096    if unknown_fields.is_some() && (KC::MAY_RETURN_UNKNOWN || VC::MAY_RETURN_UNKNOWN) {
1097        // Fast path for contiguous bufs (the common `&[u8]` / `Bytes` case):
1098        // decode from a borrowed slice and only allocate when the entry
1099        // actually turns out to be unknown.
1100        if buf.chunk().len() >= entry_len {
1101            let preserved = {
1102                let entry_slice = &buf.chunk()[..entry_len];
1103                let mut entry_cur = entry_slice;
1104                // `entry_cur` holds exactly the entry.
1105                let ctx = ctx.with_message_end(0);
1106                let status =
1107                    merge_entry_contents::<KC, VC>(&mut key, &mut val, &mut entry_cur, ctx)?;
1108                matches!(status, MapValueDecodeStatus::Unknown).then(|| entry_slice.to_vec())
1109            };
1110            buf.advance(entry_len);
1111            match preserved {
1112                None => map.storage_insert(key.into_inner(), val.into_inner()),
1113                Some(payload) => {
1114                    if let Some((field_number, unknown_fields)) = unknown_fields {
1115                        ctx.register_unknown_field()?;
1116                        unknown_fields.push(crate::UnknownField {
1117                            number: field_number,
1118                            data: crate::UnknownFieldData::LengthDelimited(payload),
1119                        });
1120                    }
1121                }
1122            }
1123            return Ok(());
1124        }
1125        // Non-contiguous fallback: buffer the payload up front so it can be
1126        // preserved verbatim if decoding reports `Unknown`.
1127        let entry_payload = buf.copy_to_bytes(entry_len);
1128        let mut entry_cur = entry_payload.clone();
1129        let status = merge_entry_contents::<KC, VC>(
1130            &mut key,
1131            &mut val,
1132            &mut entry_cur,
1133            ctx.with_message_end(0),
1134        )?;
1135        if matches!(status, MapValueDecodeStatus::Known) {
1136            map.storage_insert(key.into_inner(), val.into_inner());
1137        } else if let Some((field_number, unknown_fields)) = unknown_fields {
1138            ctx.register_unknown_field()?;
1139            unknown_fields.push(crate::UnknownField {
1140                number: field_number,
1141                data: crate::UnknownFieldData::LengthDelimited(entry_payload.to_vec()),
1142            });
1143        }
1144        return Ok(());
1145    }
1146
1147    let entry_limit = buf.remaining() - entry_len;
1148    let ctx = ctx.with_message_end(entry_limit);
1149    let mut val_status = MapValueDecodeStatus::Known;
1150    while buf.remaining() > entry_limit {
1151        let entry_tag = Tag::decode(buf)?;
1152        match entry_tag.field_number() {
1153            1 => {
1154                check_wire_type(entry_tag, KC::WIRE_TYPE)?;
1155                KC::merge(&mut key, buf, ctx)?;
1156            }
1157            2 => {
1158                check_wire_type(entry_tag, VC::WIRE_TYPE)?;
1159                val_status = VC::merge(&mut val, buf, ctx)?;
1160                if matches!(val_status, MapValueDecodeStatus::Unknown) {
1161                    ctx.check_unknown_field()?;
1162                }
1163            }
1164            _ => {
1165                crate::encoding::skip_unknown_field(entry_tag, buf, ctx)?;
1166            }
1167        }
1168    }
1169    if buf.remaining() != entry_limit {
1170        let remaining = buf.remaining();
1171        if remaining > entry_limit {
1172            buf.advance(remaining - entry_limit);
1173        } else {
1174            return Err(DecodeError::UnexpectedEof);
1175        }
1176    }
1177    if matches!(val_status, MapValueDecodeStatus::Known) {
1178        map.storage_insert(key.into_inner(), val.into_inner());
1179    }
1180    Ok(())
1181}
1182
1183#[cfg(test)]
1184mod tests {
1185    use super::*;
1186    use crate::alloc::string::String;
1187    use crate::alloc::vec::Vec;
1188    use crate::encoding::skip_field_depth;
1189
1190    fn encode_field<KC: MapCodec, VC: MapCodec>(
1191        map: &Map<KC::Value, VC::Value>,
1192        field_number: u32,
1193        outer_tag_len: u64,
1194    ) -> Vec<u8>
1195    where
1196        KC::Value: Eq + Hash,
1197    {
1198        let len = field_len::<KC, VC, _>(map, outer_tag_len);
1199        let mut buf = Vec::new();
1200        write_field::<KC, VC, _>(map, field_number, &mut buf);
1201        assert_eq!(buf.len() as u64, len, "field_len must match written bytes");
1202        buf
1203    }
1204
1205    fn decode_field<KC, VC>(mut wire: &[u8]) -> Map<KC::Value, VC::Value>
1206    where
1207        KC: MapValueDecode,
1208        KC::Value: Eq + Hash,
1209        VC: MapValueDecode,
1210    {
1211        let mut map = Map::default();
1212        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1213        while !wire.is_empty() {
1214            let tag = Tag::decode(&mut wire).unwrap();
1215            assert_eq!(tag.wire_type(), WireType::LengthDelimited);
1216            let ctx = DecodeContext::new(crate::RECURSION_LIMIT, &limit);
1217            merge_entry::<KC, VC, _>(&mut map, &mut wire, ctx).unwrap();
1218        }
1219        map
1220    }
1221
1222    /// A closed enum whose default, its first value `A`, is not 0. protoc
1223    /// rejects it as a map value; a descriptor built another way can have it.
1224    #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default)]
1225    #[repr(i32)]
1226    enum FirstIsOne {
1227        #[default]
1228        A = 1,
1229        B = 0,
1230    }
1231
1232    impl Enumeration for FirstIsOne {
1233        fn from_i32(value: i32) -> Option<Self> {
1234            match value {
1235                1 => Some(Self::A),
1236                0 => Some(Self::B),
1237                _ => None,
1238            }
1239        }
1240        fn to_i32(&self) -> i32 {
1241            *self as i32
1242        }
1243        fn proto_name(&self) -> &'static str {
1244            match self {
1245                Self::A => "A",
1246                Self::B => "B",
1247            }
1248        }
1249    }
1250
1251    #[test]
1252    fn entries_end_within_the_enclosing_message() {
1253        type K = ProtoStringMap<String>;
1254        type V = ProtoStringMap<String>;
1255        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1256        let ctx = DecodeContext::new(crate::RECURSION_LIMIT, &limit);
1257        // A six-byte entry `k` -> `v`, then one byte of something else.
1258        let wire = [6, 0x0a, 1, b'k', 0x12, 1, b'v', 0xff];
1259
1260        let mut map: Map<String, String> = Map::default();
1261        let mut input = &wire[..];
1262        merge_entry::<K, V, _>(&mut map, &mut input, ctx.with_message_end(1)).unwrap();
1263        assert_eq!(map.get("k").map(String::as_str), Some("v"));
1264        assert_eq!(input, [0xff]);
1265
1266        // The message holding the map ends before the entry does.
1267        let mut map: Map<String, String> = Map::default();
1268        assert_eq!(
1269            merge_entry::<K, V, _>(&mut map, &mut &wire[..], ctx.with_message_end(2)),
1270            Err(DecodeError::UnexpectedEof)
1271        );
1272        assert!(map.is_empty());
1273
1274        // A three-byte entry whose key declares three bytes reaches past it.
1275        let wire = [3, 0x0a, 3, b'k', b'x', b'y'];
1276        let mut map: Map<String, String> = Map::default();
1277        assert_eq!(
1278            merge_entry::<K, V, _>(&mut map, &mut &wire[..], ctx),
1279            Err(DecodeError::UnexpectedEof)
1280        );
1281        assert!(map.is_empty());
1282    }
1283
1284    #[test]
1285    fn an_empty_entry_cannot_read_its_length_prefix_from_the_following_frame() {
1286        type K = ProtoStringMap<String>;
1287        type V = ProtoStringMap<String>;
1288        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1289        let ctx = DecodeContext::new(crate::RECURSION_LIMIT, &limit).with_message_end(1);
1290        for split in 0..=2 {
1291            let (head, tail) = b"\x80\x00".split_at(split);
1292            let mut map: Map<String, String> = Map::default();
1293            assert_eq!(
1294                merge_entry::<K, V, _>(&mut map, &mut head.chain(tail), ctx),
1295                Err(DecodeError::UnexpectedEof)
1296            );
1297            assert!(map.is_empty());
1298        }
1299        // Omitting both key and value is a valid empty entry when its prefix
1300        // is wholly inside the message, including a noncanonical zero varint.
1301        for split in 0..=3 {
1302            let (head, tail) = b"\x80\x00\xff".split_at(split);
1303            let mut input = head.chain(tail);
1304            let mut map: Map<String, String> = Map::default();
1305            merge_entry::<K, V, _>(&mut map, &mut input, ctx).unwrap();
1306            assert_eq!(map.get("").map(String::as_str), Some(""));
1307            assert_eq!(input.get_u8(), 0xff);
1308        }
1309    }
1310
1311    #[test]
1312    fn buffered_entries_are_bounded_by_themselves() {
1313        // An entry that may turn out unknown is decoded from a copy of its
1314        // own bytes, so the end of the enclosing message recorded for the
1315        // outer buffer does not apply to it.
1316        type K = ProtoStringMap<String>;
1317        type V = ClosedEnum<FirstIsOne>;
1318        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1319        let ctx = DecodeContext::new(crate::RECURSION_LIMIT, &limit).with_message_end(1);
1320        let wire = [5, 0x0a, 1, b'k', 0x10, 0, 0xff];
1321        for split in 0..=wire.len() {
1322            let (head, tail) = wire.split_at(split);
1323            let mut input = head.chain(tail);
1324            let mut map: Map<String, FirstIsOne> = Map::default();
1325            let mut unknown = crate::UnknownFields::default();
1326            merge_entry_with_unknowns::<K, V, _>(
1327                &mut map,
1328                &mut input,
1329                ctx,
1330                Some((5, &mut unknown)),
1331            )
1332            .unwrap();
1333            assert_eq!(map.get("k"), Some(&FirstIsOne::B), "split {split}");
1334            assert_eq!(input.remaining(), 1, "split {split}");
1335        }
1336    }
1337
1338    #[test]
1339    fn string_int32_round_trip() {
1340        let mut map: Map<String, i32> = Map::default();
1341        map.insert("a".into(), 1);
1342        map.insert("bee".into(), -7);
1343        let wire = encode_field::<Str, Int32>(&map, 5, 1);
1344        let back = decode_field::<Str, Int32>(&wire);
1345        assert_eq!(back, map);
1346    }
1347
1348    #[test]
1349    fn proto_string_map_codec_matches_str() {
1350        // `ProtoStringMap<String>` (the custom-string codec, monomorphized on the
1351        // built-in `String`) must produce byte-identical output to the canonical
1352        // `Str` codec and round-trip through it — proving the custom-string map
1353        // key/value path is wire-compatible with the default.
1354        let mut map: Map<String, i32> = Map::default();
1355        map.insert("a".into(), 1);
1356        map.insert("bee".into(), -7);
1357
1358        let str_wire = encode_field::<Str, Int32>(&map, 5, 1);
1359        let custom_wire = encode_field::<ProtoStringMap<String>, Int32>(&map, 5, 1);
1360        // Map iteration order is unspecified, so compare via decode, not bytes.
1361        assert_eq!(
1362            decode_field::<ProtoStringMap<String>, Int32>(&str_wire),
1363            map
1364        );
1365        assert_eq!(decode_field::<Str, Int32>(&custom_wire), map);
1366
1367        // As a value codec too: `map<int32, string>`.
1368        let mut vmap: Map<i32, String> = Map::default();
1369        vmap.insert(1, "x".into());
1370        let vwire = encode_field::<Int32, ProtoStringMap<String>>(&vmap, 3, 1);
1371        assert_eq!(decode_field::<Int32, ProtoStringMap<String>>(&vwire), vmap);
1372    }
1373
1374    #[test]
1375    fn fixed_fixed_len_fold_matches_written_bytes() {
1376        let mut map: Map<u32, f64> = Map::default();
1377        map.insert(1, 0.5);
1378        map.insert(9, -2.25);
1379        map.insert(1000, 0.0);
1380        // Both codecs fixed-width → field_len takes the folded path; the
1381        // assert inside encode_field proves it equals the written bytes.
1382        let wire = encode_field::<Fixed32, Double>(&map, 3, 1);
1383        let back = decode_field::<Fixed32, Double>(&wire);
1384        assert_eq!(back, map);
1385    }
1386
1387    /// Entries that leave the default key and value out, against the bytes
1388    /// prost writes for them, decoding back to the same map.
1389    #[test]
1390    fn omitting_defaults_leaves_default_fields_out() {
1391        let encode = |key: &str, value: i32| {
1392            let mut map: Map<String, i32> = Map::default();
1393            map.insert(key.into(), value);
1394            let len = field_len_omitting_defaults::<Str, Int32, _>(&map, 1);
1395            let mut buf = Vec::new();
1396            write_field_omitting_defaults::<Str, Int32, _>(&map, 5, &mut buf);
1397            assert_eq!(buf.len() as u64, len, "the size matches the written bytes");
1398            assert_eq!(decode_field::<Str, Int32>(&buf), map);
1399            buf
1400        };
1401        // tag 5, length 0: neither field
1402        assert_eq!(encode("", 0), [0x2a, 0x00]);
1403        // the key only
1404        assert_eq!(encode("a", 0), [0x2a, 0x03, 0x0a, 0x01, b'a']);
1405        // the value only
1406        assert_eq!(encode("", 7), [0x2a, 0x02, 0x10, 0x07]);
1407        assert_eq!(
1408            encode("a", 7),
1409            encode_field::<Str, Int32>(
1410                &{
1411                    let mut map = Map::default();
1412                    map.insert(String::from("a"), 7);
1413                    map
1414                },
1415                5,
1416                1
1417            )
1418        );
1419        // `-0.0` is a float's default to `==`, as to prost
1420        let mut floats: Map<u32, f64> = Map::default();
1421        floats.insert(1, -0.0);
1422        let mut buf = Vec::new();
1423        write_field_omitting_defaults::<Uint32, Double, _>(&floats, 2, &mut buf);
1424        assert_eq!(buf, [0x12, 0x02, 0x08, 0x01]);
1425    }
1426
1427    /// A closed enum value is left out when it is the enum's default, which
1428    /// need not be 0, as prost leaves it out.
1429    #[test]
1430    fn omitting_defaults_compares_a_closed_enum_with_its_default() {
1431        type Codec = ClosedEnum<FirstIsOne>;
1432        let encode = |value: FirstIsOne| {
1433            let mut map: Map<u32, FirstIsOne> = Map::default();
1434            map.insert(1, value);
1435            let len = field_len_omitting_defaults::<Uint32, Codec, _>(&map, 1);
1436            let mut buf = Vec::new();
1437            write_field_omitting_defaults::<Uint32, Codec, _>(&map, 2, &mut buf);
1438            assert_eq!(buf.len() as u64, len, "the size matches the written bytes");
1439            assert_eq!(decode_field::<Uint32, Codec>(&buf), map);
1440            buf
1441        };
1442        // key 1, the default `A` left out
1443        assert_eq!(encode(FirstIsOne::A), [0x12, 0x02, 0x08, 0x01]);
1444        // key 1, `B` written although it is 0
1445        assert_eq!(encode(FirstIsOne::B), [0x12, 0x04, 0x08, 0x01, 0x10, 0x00]);
1446    }
1447
1448    /// `is_default` holds for exactly the value a missing entry field decodes
1449    /// to, for every codec.
1450    #[test]
1451    fn is_default_is_the_decoded_default() {
1452        fn check<C: MapCodec>(default: C::Value, others: &[C::Value]) {
1453            // An entry with neither field: key 0, the value's default.
1454            let decoded = decode_field::<Int32, C>(&[0x0a, 0x00]);
1455            assert!(C::is_default(&decoded[&0]));
1456            assert!(C::is_default(&default));
1457            for other in others {
1458                assert!(!C::is_default(other));
1459            }
1460        }
1461        #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default)]
1462        #[repr(i32)]
1463        enum E {
1464            #[default]
1465            A = 0,
1466            B = 1,
1467        }
1468        impl Enumeration for E {
1469            fn from_i32(value: i32) -> Option<Self> {
1470                match value {
1471                    0 => Some(E::A),
1472                    1 => Some(E::B),
1473                    _ => None,
1474                }
1475            }
1476            fn to_i32(&self) -> i32 {
1477                *self as i32
1478            }
1479            fn proto_name(&self) -> &'static str {
1480                match self {
1481                    E::A => "A",
1482                    E::B => "B",
1483                }
1484            }
1485        }
1486        check::<Int32>(0, &[1, -1]);
1487        check::<Int64>(0, &[1, i64::MIN]);
1488        check::<Uint32>(0, &[1]);
1489        check::<Uint64>(0, &[u64::MAX]);
1490        check::<Sint32>(0, &[-1]);
1491        check::<Sint64>(0, &[-1]);
1492        check::<Fixed32>(0, &[1]);
1493        check::<Fixed64>(0, &[1]);
1494        check::<Sfixed32>(0, &[-1]);
1495        check::<Sfixed64>(0, &[-1]);
1496        check::<Bool>(false, &[true]);
1497        check::<Float>(0.0, &[1.0, f32::NAN, f32::MIN_POSITIVE]);
1498        check::<Float>(-0.0, &[]);
1499        check::<Double>(0.0, &[1.0, f64::NAN, f64::MIN_POSITIVE]);
1500        check::<Double>(-0.0, &[]);
1501        check::<Str>(String::new(), &["a".into()]);
1502        check::<BytesVec>(Vec::new(), &[vec![0]]);
1503        check::<BytesBuf>(
1504            crate::bytes::Bytes::new(),
1505            &[crate::bytes::Bytes::from_static(&[0])],
1506        );
1507        check::<ProtoStringMap<String>>(String::new(), &[" ".into()]);
1508        check::<ProtoBytesMap<Vec<u8>>>(Vec::new(), &[vec![0]]);
1509        check::<OpenEnum<E>>(
1510            EnumValue::from(0),
1511            &[EnumValue::from(1), EnumValue::Unknown(7)],
1512        );
1513        check::<ClosedEnum<E>>(E::A, &[E::B]);
1514        // A missing closed enum decodes as its first value, an open one as 0.
1515        check::<ClosedEnum<FirstIsOne>>(FirstIsOne::A, &[FirstIsOne::B]);
1516        check::<OpenEnum<FirstIsOne>>(EnumValue::from(0), &[EnumValue::from(1)]);
1517    }
1518
1519    #[test]
1520    fn missing_key_and_value_take_defaults() {
1521        // Entry with no fields at all: length prefix 0.
1522        let wire = [0x00u8];
1523        let mut map: Map<String, i32> = Map::default();
1524        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1525        merge_entry::<Str, Int32, _>(&mut map, &mut &wire[..], DecodeContext::new(10, &limit))
1526            .unwrap();
1527        assert_eq!(map.get(""), Some(&0));
1528    }
1529
1530    #[test]
1531    fn unknown_entry_field_is_skipped() {
1532        // key "a" (field 1), unknown varint field 3, value 7 (field 2).
1533        let mut entry = Vec::new();
1534        Tag::new(1, WireType::LengthDelimited).encode(&mut entry);
1535        types::encode_string("a", &mut entry);
1536        Tag::new(3, WireType::Varint).encode(&mut entry);
1537        encode_varint(99, &mut entry);
1538        Tag::new(2, WireType::Varint).encode(&mut entry);
1539        types::encode_int32(7, &mut entry);
1540        let mut wire = Vec::new();
1541        encode_varint(entry.len() as u64, &mut wire);
1542        wire.extend_from_slice(&entry);
1543
1544        let mut map: Map<String, i32> = Map::default();
1545        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1546        merge_entry::<Str, Int32, _>(
1547            &mut map,
1548            &mut wire.as_slice(),
1549            DecodeContext::new(10, &limit),
1550        )
1551        .unwrap();
1552        assert_eq!(map.get("a"), Some(&7));
1553    }
1554
1555    #[test]
1556    fn entry_wire_type_mismatch_errors() {
1557        // Field 1 claims Fixed64 for a string key.
1558        let mut entry = Vec::new();
1559        Tag::new(1, WireType::Fixed64).encode(&mut entry);
1560        entry.extend_from_slice(&[0u8; 8]);
1561        let mut wire = Vec::new();
1562        encode_varint(entry.len() as u64, &mut wire);
1563        wire.extend_from_slice(&entry);
1564
1565        let mut map: Map<String, i32> = Map::default();
1566        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1567        let err = merge_entry::<Str, Int32, _>(
1568            &mut map,
1569            &mut wire.as_slice(),
1570            DecodeContext::new(10, &limit),
1571        )
1572        .unwrap_err();
1573        assert!(matches!(err, DecodeError::WireTypeMismatch { .. }));
1574    }
1575
1576    #[test]
1577    fn truncated_entry_errors() {
1578        // Length prefix promises 5 bytes; only 1 available.
1579        let wire = [0x05u8, 0x08];
1580        let mut map: Map<String, i32> = Map::default();
1581        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1582        let err =
1583            merge_entry::<Str, Int32, _>(&mut map, &mut &wire[..], DecodeContext::new(10, &limit))
1584                .unwrap_err();
1585        assert!(matches!(err, DecodeError::UnexpectedEof));
1586    }
1587
1588    #[test]
1589    fn message_map_two_pass_round_trip() {
1590        use crate::{DefaultInstance, SizeCache};
1591
1592        #[derive(Clone, PartialEq, Eq, Debug, Default)]
1593        struct FlatMsg {
1594            value: i32,
1595        }
1596
1597        impl DefaultInstance for FlatMsg {
1598            fn default_instance() -> &'static Self {
1599                static INST: crate::__private::OnceBox<FlatMsg> = crate::__private::OnceBox::new();
1600                INST.get_or_init(|| crate::alloc::boxed::Box::new(FlatMsg::default()))
1601            }
1602        }
1603
1604        impl Message for FlatMsg {
1605            fn compute_size(&self, _cache: &mut SizeCache) -> u32 {
1606                if self.value != 0 {
1607                    1 + types::int32_encoded_len(self.value) as u32
1608                } else {
1609                    0
1610                }
1611            }
1612            fn write_to(&self, _cache: &mut SizeCache, buf: &mut impl EncodeSink) {
1613                if self.value != 0 {
1614                    Tag::new(1, WireType::Varint).encode(buf);
1615                    types::encode_int32(self.value, buf);
1616                }
1617            }
1618            fn merge_field(
1619                &mut self,
1620                tag: Tag,
1621                buf: &mut impl Buf,
1622                ctx: DecodeContext<'_>,
1623            ) -> Result<(), DecodeError> {
1624                match tag.field_number() {
1625                    1 => self.value = types::decode_int32(buf)?,
1626                    _ => skip_field_depth(tag, buf, ctx.depth())?,
1627                }
1628                Ok(())
1629            }
1630            fn clear(&mut self) {
1631                *self = Self::default();
1632            }
1633        }
1634
1635        let mut map: Map<i32, FlatMsg> = Map::default();
1636        map.insert(1, FlatMsg { value: 0 }); // empty payload entry
1637        map.insert(2, FlatMsg { value: -3 }); // multi-byte varint payload
1638        map.insert(9, FlatMsg { value: 7 });
1639
1640        // Two-pass: message_field_len reserves SizeCache slots in map
1641        // iteration order; write_message_field consumes them in the same
1642        // order. The size must equal the written bytes exactly.
1643        let mut cache = SizeCache::default();
1644        let len = message_field_len::<Int32, FlatMsg, _>(&map, 1, &mut cache);
1645        let mut wire = Vec::new();
1646        write_message_field::<Int32, FlatMsg, _>(&map, 4, &mut cache, &mut wire);
1647        assert_eq!(wire.len() as u64, len, "size pass must match write pass");
1648
1649        let back = decode_field::<Int32, Msg<FlatMsg>>(&wire);
1650        assert_eq!(back, map);
1651
1652        // Omitting defaults: the empty message and the zero key go, the
1653        // slots stay in step.
1654        let mut cache = SizeCache::default();
1655        let mut sparse: Map<i32, FlatMsg> = Map::default();
1656        sparse.insert(0, FlatMsg { value: 5 });
1657        sparse.insert(1, FlatMsg { value: 0 });
1658        sparse.insert(2, FlatMsg { value: -3 });
1659        let len = message_field_len_omitting_defaults::<Int32, FlatMsg, _>(&sparse, 1, &mut cache);
1660        let mut wire = Vec::new();
1661        write_message_field_omitting_defaults::<Int32, FlatMsg, _>(
1662            &sparse, 4, &mut cache, &mut wire,
1663        );
1664        assert_eq!(wire.len() as u64, len, "size pass must match write pass");
1665        assert_eq!(decode_field::<Int32, Msg<FlatMsg>>(&wire), sparse);
1666        let entries: Vec<Vec<u8>> = {
1667            let mut rest = wire.as_slice();
1668            let mut out = Vec::new();
1669            while !rest.is_empty() {
1670                Tag::decode(&mut rest).unwrap();
1671                let len = decode_varint(&mut rest).unwrap() as usize;
1672                out.push(rest[..len].to_vec());
1673                rest = &rest[len..];
1674            }
1675            out
1676        };
1677        // key 0 left out, value 5; key 1, the empty value left out
1678        assert!(
1679            entries.contains(&vec![0x12, 0x02, 0x08, 0x05]),
1680            "{entries:?}"
1681        );
1682        assert!(entries.contains(&vec![0x08, 0x01]), "{entries:?}");
1683
1684        // A value that reserves a slot of its own, after an empty one: the
1685        // slots stay in step.
1686        #[derive(Clone, PartialEq, Eq, Debug, Default)]
1687        struct Outer {
1688            inner: Option<FlatMsg>,
1689        }
1690
1691        impl DefaultInstance for Outer {
1692            fn default_instance() -> &'static Self {
1693                static INST: crate::__private::OnceBox<Outer> = crate::__private::OnceBox::new();
1694                INST.get_or_init(|| crate::alloc::boxed::Box::new(Outer::default()))
1695            }
1696        }
1697
1698        impl Message for Outer {
1699            fn compute_size(&self, cache: &mut SizeCache) -> u32 {
1700                let Some(inner) = &self.inner else {
1701                    return 0;
1702                };
1703                let slot = cache.reserve();
1704                let len = inner.compute_size(cache);
1705                cache.set(slot, len);
1706                1 + varint_len(len as u64) as u32 + len
1707            }
1708            fn write_to(&self, cache: &mut SizeCache, buf: &mut impl EncodeSink) {
1709                if let Some(inner) = &self.inner {
1710                    let len = cache.consume_next();
1711                    Tag::new(1, WireType::LengthDelimited).encode(buf);
1712                    encode_varint(len as u64, buf);
1713                    inner.write_to(cache, buf);
1714                }
1715            }
1716            fn merge_field(
1717                &mut self,
1718                tag: Tag,
1719                buf: &mut impl Buf,
1720                ctx: DecodeContext<'_>,
1721            ) -> Result<(), DecodeError> {
1722                match tag.field_number() {
1723                    1 => Message::merge_length_delimited(
1724                        self.inner.get_or_insert_with(FlatMsg::default),
1725                        buf,
1726                        ctx,
1727                    )?,
1728                    _ => skip_field_depth(tag, buf, ctx.depth())?,
1729                }
1730                Ok(())
1731            }
1732            fn clear(&mut self) {
1733                *self = Self::default();
1734            }
1735        }
1736
1737        let mut nested = crate::alloc::collections::BTreeMap::new();
1738        nested.insert(1, Outer::default());
1739        nested.insert(
1740            2,
1741            Outer {
1742                inner: Some(FlatMsg { value: 7 }),
1743            },
1744        );
1745        let mut cache = SizeCache::default();
1746        let len = message_field_len_omitting_defaults::<Int32, Outer, _>(&nested, 1, &mut cache);
1747        let mut wire = Vec::new();
1748        write_message_field_omitting_defaults::<Int32, Outer, _>(&nested, 4, &mut cache, &mut wire);
1749        assert_eq!(wire.len() as u64, len, "size pass must match write pass");
1750        #[rustfmt::skip]
1751        assert_eq!(wire, [
1752            0x22, 0x02, 0x08, 0x01, // key 1, the empty value left out
1753            0x22, 0x08, 0x08, 0x02, 0x12, 0x04, 0x0a, 0x02, 0x08, 0x07, // key 2
1754        ]);
1755    }
1756
1757    #[test]
1758    fn open_enum_value_preserves_unknown() {
1759        #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default)]
1760        #[repr(i32)]
1761        enum E {
1762            #[default]
1763            A = 0,
1764        }
1765        impl Enumeration for E {
1766            fn from_i32(value: i32) -> Option<Self> {
1767                (value == 0).then_some(E::A)
1768            }
1769            fn to_i32(&self) -> i32 {
1770                *self as i32
1771            }
1772            fn proto_name(&self) -> &'static str {
1773                "A"
1774            }
1775            fn from_proto_name(name: &str) -> Option<Self> {
1776                (name == "A").then_some(E::A)
1777            }
1778        }
1779
1780        let mut map: Map<i32, EnumValue<E>> = Map::default();
1781        map.insert(1, EnumValue::Unknown(42));
1782        let wire = encode_field::<Int32, OpenEnum<E>>(&map, 2, 1);
1783        let back = decode_field::<Int32, OpenEnum<E>>(&wire);
1784        assert_eq!(back.get(&1), Some(&EnumValue::Unknown(42)));
1785
1786        // Closed codec drops the whole map entry instead of inserting the
1787        // default enum value.
1788        let back = decode_field::<Int32, ClosedEnum<E>>(&wire);
1789        assert!(!back.contains_key(&1));
1790    }
1791
1792    #[test]
1793    fn closed_enum_unknown_preserves_whole_entry_when_requested() {
1794        #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default)]
1795        #[repr(i32)]
1796        enum E {
1797            #[default]
1798            A = 0,
1799            B = 1,
1800        }
1801        impl Enumeration for E {
1802            fn from_i32(value: i32) -> Option<Self> {
1803                match value {
1804                    0 => Some(E::A),
1805                    1 => Some(E::B),
1806                    _ => None,
1807                }
1808            }
1809            fn to_i32(&self) -> i32 {
1810                *self as i32
1811            }
1812            fn proto_name(&self) -> &'static str {
1813                match self {
1814                    E::A => "A",
1815                    E::B => "B",
1816                }
1817            }
1818        }
1819
1820        let mut entry = Vec::new();
1821        Tag::new(1, WireType::Varint).encode(&mut entry);
1822        types::encode_int32(7, &mut entry);
1823        Tag::new(2, WireType::Varint).encode(&mut entry);
1824        types::encode_int32(99, &mut entry);
1825
1826        let mut wire = Vec::new();
1827        encode_varint(entry.len() as u64, &mut wire);
1828        wire.extend_from_slice(&entry);
1829
1830        let mut map: Map<i32, E> = Map::default();
1831        let mut unknown_fields = crate::UnknownFields::new();
1832        let limit = core::cell::Cell::new(crate::DEFAULT_UNKNOWN_FIELD_LIMIT);
1833        merge_entry_with_unknowns::<Int32, ClosedEnum<E>, _>(
1834            &mut map,
1835            &mut wire.as_slice(),
1836            DecodeContext::new(10, &limit),
1837            Some((5, &mut unknown_fields)),
1838        )
1839        .unwrap();
1840
1841        assert!(map.is_empty());
1842        let unknowns: Vec<_> = unknown_fields.iter().collect();
1843        assert_eq!(unknowns.len(), 1);
1844        assert_eq!(unknowns[0].number, 5);
1845        assert!(matches!(
1846            &unknowns[0].data,
1847            crate::UnknownFieldData::LengthDelimited(payload) if payload == &entry
1848        ));
1849
1850        // Non-contiguous Buf takes the buffering fallback and produces the
1851        // same outcome. Split *inside* the entry payload so that after the
1852        // length prefix is consumed, the first chunk is shorter than
1853        // `entry_len` and the contiguous fast path is bypassed.
1854        let mut map: Map<i32, E> = Map::default();
1855        let mut unknown_fields = crate::UnknownFields::new();
1856        let (a, b) = wire.split_at(3);
1857        let mut chained = bytes::Buf::chain(a, b);
1858        merge_entry_with_unknowns::<Int32, ClosedEnum<E>, _>(
1859            &mut map,
1860            &mut chained,
1861            DecodeContext::new(10, &limit),
1862            Some((5, &mut unknown_fields)),
1863        )
1864        .unwrap();
1865        assert!(map.is_empty());
1866        let unknowns: Vec<_> = unknown_fields.iter().collect();
1867        assert_eq!(unknowns.len(), 1);
1868        assert!(matches!(
1869            &unknowns[0].data,
1870            crate::UnknownFieldData::LengthDelimited(payload) if payload == &entry
1871        ));
1872
1873        // Last-wins: an unknown value followed by a known one inserts the
1874        // known value and records nothing in unknown fields.
1875        let mut entry = Vec::new();
1876        Tag::new(1, WireType::Varint).encode(&mut entry);
1877        types::encode_int32(7, &mut entry);
1878        Tag::new(2, WireType::Varint).encode(&mut entry);
1879        types::encode_int32(99, &mut entry);
1880        Tag::new(2, WireType::Varint).encode(&mut entry);
1881        types::encode_int32(1, &mut entry);
1882
1883        let mut wire = Vec::new();
1884        encode_varint(entry.len() as u64, &mut wire);
1885        wire.extend_from_slice(&entry);
1886
1887        let mut map: Map<i32, E> = Map::default();
1888        let mut unknown_fields = crate::UnknownFields::new();
1889        merge_entry_with_unknowns::<Int32, ClosedEnum<E>, _>(
1890            &mut map,
1891            &mut wire.as_slice(),
1892            DecodeContext::new(10, &limit),
1893            Some((5, &mut unknown_fields)),
1894        )
1895        .unwrap();
1896        assert_eq!(map.get(&7), Some(&E::B));
1897        assert_eq!(unknown_fields.iter().count(), 0);
1898    }
1899}