Skip to main content

buffa/
lib.rs

1// Modified by ReallyMe Technologies Limited.
2//! A pure-Rust Protocol Buffers runtime with first-class **editions** support,
3//! zero-copy views, and `no_std` compatibility.
4//!
5//! This is the runtime crate. For code generation, see `buffa-build` (for
6//! `build.rs` integration) or `protoc-gen-reallyme-buffa` (for use as a `protoc` plugin).
7//!
8//! # Quick start
9//!
10//! Generated message types implement [`Message`]. Encode and decode:
11//!
12//! ```no_run
13//! # use buffa::__doctest_fixtures::Person;
14//! use buffa::Message;
15//!
16//! # fn example(bytes: &[u8]) -> Result<(), buffa::DecodeError> {
17//! # let person = Person::default();
18//! # let mut existing = Person::default();
19//! // Encode to a Vec<u8> or bytes::Bytes
20//! let bytes: Vec<u8> = person.encode_to_vec();
21//! let bytes: buffa::bytes::Bytes = person.encode_to_bytes();  // re-export of `bytes` crate
22//!
23//! // Decode from a byte slice
24//! let decoded = Person::decode_from_slice(&bytes)?;
25//!
26//! // Merge into an existing message (proto3 last-wins / proto2 merge semantics)
27//! existing.merge_from_slice(&bytes)?;
28//! # Ok(())
29//! # }
30//! ```
31//!
32//! For untrusted input, use [`DecodeOptions`] to tighten limits:
33//!
34//! ```no_run
35//! # use buffa::__doctest_fixtures::Person;
36//! use buffa::DecodeOptions;
37//!
38//! # fn example(bytes: &[u8]) -> Result<(), buffa::DecodeError> {
39//! let msg: Person = DecodeOptions::new()
40//!     .with_recursion_limit(50)
41//!     .with_max_message_size(1024 * 1024)     // 1 MiB
42//!     .with_unknown_field_limit(10_000)        // unknown fields per decode
43//!     .decode_from_slice(&bytes)?;
44//! # Ok(())
45//! # }
46//! ```
47//!
48//! The trait-level convenience methods (`decode_from_slice`, `merge_from_slice`)
49//! use a fixed recursion limit of [`RECURSION_LIMIT`] (100), a fixed
50//! [`DEFAULT_UNKNOWN_FIELD_LIMIT`] (1,000,000) bounding how many unknown
51//! fields the decoder will materialize, and no explicit size cap — a
52//! `&[u8]` is already bounded by whatever allocated it. Use `DecodeOptions`
53//! to tune these, e.g. to reject oversized inputs at the decode entry point
54//! rather than at the allocator.
55//!
56//! # Where is `#[derive(Message)]`?
57//!
58//! There isn't one: message types are generated from `.proto` files, so the
59//! portable schema stays the source of truth for every language and for
60//! tooling such as schema registries and breaking-change checks. To give a
61//! generated field an existing Rust type, see the guide's
62//! [custom-type support][custom-types].
63//!
64//! [custom-types]: https://github.com/reallyme/buffa/blob/reallyme-v0.1.1/docs/guide.md#custom-type-implementations
65//!
66//! # Zero-copy views
67//!
68//! Every owned message type `Foo` has a corresponding `FooView<'a>` that
69//! borrows `string` and `bytes` fields directly from the input buffer — no
70//! allocation on the read path. See the [`view`] module.
71//!
72//! ```no_run
73//! # use buffa::__doctest_fixtures::PersonView;
74//! # use buffa::view::MessageView;
75//! # fn example(wire_bytes: &[u8]) -> Result<(), buffa::DecodeError> {
76//! let req = PersonView::decode_view(&wire_bytes)?;
77//! println!("name: {}", req.name);  // &'a str, zero-copy
78//! # Ok(())
79//! # }
80//! ```
81//!
82//! # Feature flags
83//!
84//! | Flag | Default | Enables |
85//! |------|:-------:|---------|
86//! | `std` | ✓ | `std::io::Read` decoders, `std::collections::HashMap` for map fields, thread-local JSON parse options (the `json` module) |
87//! | `json` |  | Proto3 JSON via `serde` (the `json_helpers` and `any_registry` modules) |
88//! | `text` |  | Textproto (human-readable) encoding and decoding |
89//! | `arbitrary` |  | `arbitrary::Arbitrary` impls for fuzzing |
90//!
91//! Generated `string` / `bytes` fields can use a custom owned type (any type
92//! satisfying [`ProtoString`] / [`ProtoBytes`]) selected at code-generation
93//! time through `buffa_build`'s `string_type` / `bytes_type` knobs. The chosen
94//! crate is an ordinary dependency of the consuming crate — buffa does not
95//! re-export it (see [`ProtoString`]).
96//!
97//! With `default-features = false` the crate is `#![no_std]` (requires
98//! `alloc`). Proto3 JSON serialization still works without `std` via
99//! `serde` + `serde_json` with their own `alloc` features.
100//!
101//! # Key types
102//!
103//! | Type | Purpose |
104//! |------|---------|
105//! | [`Message`] | Core trait for encode / decode / merge |
106//! | [`MessageName`] | Compile-time `FULL_NAME` const (`"pkg.Msg"`) for generic dispatch |
107//! | [`DecodeOptions`] | Configurable recursion and size limits |
108//! | [`MessageField<T>`](MessageField) | Optional sub-message with transparent `Deref` to default |
109//! | [`EnumValue<E>`](EnumValue) | Open enum wrapper (`Known(E)` / `Unknown(i32)`) |
110//! | [`UnknownFields`] | Unknown-field preservation for round-trip fidelity |
111//! | [`Extension<C>`](Extension) | Typed extension descriptor (codegen-emitted `pub const`) |
112//! | [`ExtensionSet`] | Get/set extensions via unknown-field storage |
113//! | [`view::MessageView`] | Zero-copy borrowed view trait |
114//! | [`view::OwnedView<V>`](view::OwnedView) | Self-contained `'static` view backed by `Bytes` |
115//! | [`view::ViewReborrow`] | Expose real borrow lifetime from `OwnedView` via [`reborrow`](view::OwnedView::reborrow) |
116//! | [`view::ViewLifetimeParametric`] | `unsafe` marker required by every `OwnedView` constructor — the view keeps no buffer borrow past itself |
117//!
118//! # `no_std`
119//!
120//! ```sh
121//! cargo add reallyme-buffa@=0.1.1 --rename buffa --no-default-features
122//! ```
123//!
124//! Generated code uses `::buffa::alloc::string::String` etc. rather than
125//! relying on the prelude, so it compiles unchanged on bare-metal targets.
126//! Map fields use `std::collections::HashMap` (`hashbrown::HashMap` under
127//! `no_std`) with the [`foldhash`] hasher on both paths — see [`Map`] for
128//! the rationale and the opt-out.
129
130#![cfg_attr(not(feature = "std"), no_std)]
131#![cfg_attr(docsrs, feature(doc_cfg))]
132#![deny(rustdoc::broken_intra_doc_links)]
133// Crate-level examples above use the `__doctest_fixtures` stubs (Person,
134// PersonView) and compile as `no_run`. Examples in module/item docs that
135// reference types specific to a user's schema (Address, Inner, etc.)
136// remain `ignore` — the fixture boilerplate would exceed the example.
137
138// Re-exported for use in generated code so that downstream crates only need
139// to depend on `buffa`, not on `alloc`, `bytes`, or `serde_json` directly.
140#[doc(hidden)]
141pub extern crate alloc;
142#[doc(hidden)]
143pub use ::bytes;
144// The JSON converters that codegen emits for an extension take and return a
145// `::buffa::serde_json::Value`. Re-export so that path resolves without the
146// consumer adding `serde_json` to its own `Cargo.toml`.
147//
148// `serde` is *not* re-exported: the `#[derive(::serde::Serialize)]` macro
149// emits `extern crate serde as _serde;` by default, so the consumer crate
150// must depend on `serde` directly. Routing it through a re-export would
151// require stamping `#[serde(crate = "::buffa::serde")]` on every generated
152// derive (and rewriting every other emitted `::serde::` path) — feasible,
153// but not done. Keep `serde` in the documented consumer requirements.
154#[cfg(feature = "json")]
155#[doc(hidden)]
156pub use ::serde_json;
157
158/// Include the generated stitcher for a proto **package** from `OUT_DIR`.
159///
160/// Codegen emits one `<pkg>.mod.rs` per package which `include!`s the
161/// per-proto content files and authors the `__buffa::{view, oneof, ext}`
162/// ancillary tree, so a single macro call brings in everything.
163///
164/// `$pkg` is the **dotted proto package literal** exactly as it appears
165/// in the `.proto`'s `package` declaration (e.g. `"google.protobuf"`,
166/// not a Rust path or the `.proto` file path). For protos with no
167/// `package` declaration, pass `"__buffa"` (the reserved sentinel; no
168/// real package can use it).
169///
170/// ```ignore
171/// pub mod my_pkg {
172///     buffa::include_proto!("my.pkg");
173/// }
174/// ```
175///
176/// For checked-in generated code (no `OUT_DIR`), use
177/// [`include_proto_relative!`].
178#[macro_export]
179macro_rules! include_proto {
180    ($pkg:literal) => {
181        include!(concat!(env!("OUT_DIR"), "/", $pkg, ".mod.rs"));
182    };
183}
184
185/// Like [`include_proto!`] but takes a relative directory instead of
186/// reading `OUT_DIR` — for crates that check generated code into the
187/// source tree (e.g. `buffa-types`, `buffa-descriptor`).
188///
189/// `$pkg` is the dotted proto package literal exactly as in the
190/// `.proto`'s `package` declaration; for the unnamed package pass
191/// `"__buffa"`. `$dir` is relative to the calling source file.
192///
193/// ```ignore
194/// pub mod protobuf {
195///     buffa::include_proto_relative!("generated", "google.protobuf");
196/// }
197/// ```
198#[macro_export]
199macro_rules! include_proto_relative {
200    ($dir:literal, $pkg:literal) => {
201        include!(concat!($dir, "/", $pkg, ".mod.rs"));
202    };
203}
204
205/// Test helper: a [`DecodeContext`] at `depth` with a fresh default-size
206/// unknown-field allowance. Leaks the limit cell (tests only) so the
207/// context can be passed around without scope gymnastics.
208#[cfg(test)]
209pub(crate) fn test_ctx(depth: u32) -> DecodeContext<'static> {
210    let limit = alloc::boxed::Box::leak(alloc::boxed::Box::new(core::cell::Cell::new(
211        DEFAULT_UNKNOWN_FIELD_LIMIT,
212    )));
213    DecodeContext::new(depth, limit)
214}
215
216#[cfg(feature = "json")]
217pub mod any_registry;
218pub mod editions;
219pub mod encode_sink;
220pub mod encoding;
221pub mod enumeration;
222pub mod error;
223pub mod extension;
224#[cfg(feature = "json")]
225pub mod extension_registry;
226#[cfg(feature = "json")]
227pub mod json;
228#[cfg(feature = "json")]
229pub mod json_helpers;
230// Generated-code plumbing: codecs are named via turbofish by `write_to` /
231// `merge_field` emission, never by hand-written code. Hidden so the codec
232// ZSTs and their sealed traits don't surface as consumer API on docs.rs.
233#[doc(hidden)]
234pub mod map_codec;
235pub mod message;
236pub mod message_field;
237pub mod message_set;
238pub mod oneof;
239mod size_cache;
240// Runtime for table-driven message codecs, called by generated code; see the
241// module docs.
242#[doc(hidden)]
243pub mod table;
244#[cfg(test)]
245pub(crate) mod test_doubles;
246#[cfg(feature = "text")]
247pub mod text;
248#[cfg(any(feature = "json", feature = "text"))]
249pub mod type_registry;
250pub mod types;
251pub mod unknown_fields;
252pub mod view;
253
254// ── User-facing re-exports ─────────────────────────────────────────────────────
255// Types that appear in user code: trait bounds, field types, return types,
256// and things users explicitly construct or call methods on.
257
258pub use encode_sink::{EncodeSink, Rope, RopeBuf, DEFAULT_MIN_SEGMENT};
259pub use enumeration::{EnumValue, Enumeration};
260pub use error::{DecodeError, EncodeError};
261pub use extension::{Extension, ExtensionCodec, ExtensionSet};
262/// Re-exported so downstream code that needs to name the hasher type behind
263/// [`Map`] (in an explicit signature, or to `with_capacity_and_hasher` without
264/// inference) does so against buffa's `foldhash` version rather than a
265/// separately-resolved one. This couples buffa's public-API semver to
266/// `foldhash`'s major version. Most callers should not need this — `Map` and
267/// `Default::default()` keep the hasher fully inferred.
268pub use foldhash;
269pub use map_codec::{Map, MapStorage};
270pub use message::{
271    checked_encode_size, saturate_size, DecodeContext, DecodeOptions, Message, MessageName,
272    DEFAULT_ELEMENT_MEMORY_LIMIT, DEFAULT_UNKNOWN_FIELD_LIMIT, MAX_MESSAGE_BYTES, RECURSION_LIMIT,
273};
274#[doc(hidden)]
275pub use message::{debug_assert_two_pass, encode_size_overflow};
276pub use message_field::{DefaultInstance, Inline, MessageField, ProtoBox};
277pub use oneof::Oneof;
278pub use size_cache::{SizeCache, SizeCachePool};
279pub use types::{AsSharedBytes, FieldPayload, ProtoBytes, ProtoList, ProtoString, WirePayload};
280pub use unknown_fields::{UnknownField, UnknownFieldData, UnknownFields};
281
282#[cfg(feature = "text")]
283pub use text::TextFormat;
284pub use view::{
285    DefaultViewInstance, HasMessageView, LazyMessageFieldView, LazyMessageView, LazyRepeatedView,
286    MapView, MessageFieldView, MessageView, OwnedView, RepeatedView, UnknownFieldsView, ViewEncode,
287    ViewLifetimeParametric, ViewReborrow,
288};
289
290/// Private re-exports used exclusively by generated code.
291///
292/// Not part of the public API. These items may change or disappear in any
293/// release. Do not use them directly.
294#[doc(hidden)]
295pub mod __private {
296    /// Whether the active JSON parse options reject a `google.protobuf.Any`
297    /// `@type` without a `/`. The `Any` deserializer in `buffa-types` reads
298    /// it.
299    #[cfg(feature = "json")]
300    #[must_use]
301    pub fn strict_any_type_urls() -> bool {
302        crate::json::strict_any_type_urls()
303    }
304
305    /// The memory one element of a repeated field occupies in the collection
306    /// holding it, for charging against
307    /// [`DecodeContext::register_element_memory`](crate::DecodeContext::register_element_memory).
308    ///
309    /// Takes the element by reference and reports `size_of::<T>()` — for a view
310    /// element that is the borrowed pointer's own width, not the length of what
311    /// it points at, which is what the collection actually grows by. Generated
312    /// code calls this rather than `size_of_val` so the distinction is named
313    /// rather than left to a reader to infer from a double reference.
314    #[inline(always)]
315    #[must_use]
316    pub fn element_footprint<T>(_element: &T) -> usize {
317        core::mem::size_of::<T>()
318    }
319
320    /// Re-exported for use in generated `DefaultInstance` implementations.
321    ///
322    /// Generated code refers to this as `::buffa::__private::OnceBox<T>` so
323    /// that downstream crates do not need a direct `once_cell` dependency.
324    pub use once_cell::race::OnceBox;
325
326    /// The concrete `map<K, V>` field type generated code uses by default.
327    ///
328    /// Generated code refers to this as `::buffa::__private::HashMap<K, V>`
329    /// so that downstream crates do not need a direct dependency on the
330    /// hasher or container crate.
331    ///
332    /// On `std` builds this is `std::collections::HashMap` parameterized with
333    /// [`foldhash::fast::RandomState`] as the hasher; on `no_std` builds it is
334    /// `hashbrown::HashMap` (which defaults to the same `foldhash` hasher).
335    /// The table implementation is identical either way — `std::collections::HashMap`
336    /// is itself a thin wrapper around hashbrown's SwissTable — so the only
337    /// load-bearing choice here is the hasher.
338    ///
339    /// See [`Map`](crate::Map) for the hasher rationale and construction
340    /// guidance.
341    #[cfg(not(feature = "std"))]
342    pub type HashMap<K, V> = hashbrown::HashMap<K, V>;
343    #[cfg(feature = "std")]
344    pub type HashMap<K, V> = std::collections::HashMap<K, V, foldhash::fast::RandomState>;
345
346    // ── Type-agnostic `Arbitrary` builders for configurable owned types ──────
347    //
348    // Codegen attaches them to any field whose representation is non-default,
349    // selecting by *kind* (string vs bytes, singular vs optional vs repeated)
350    // rather than by the concrete type. They build the canonical `String` /
351    // `Vec<u8>` first and convert through the `From` bound, so a substituted
352    // type needs no native `Arbitrary` impl and codegen carries no knowledge of
353    // any specific type. Materializing the canonical type first also keeps
354    // byte-consumption order identical to the default-representation impl,
355    // which the parity tests assert.
356
357    /// Build a [`ProtoString`](crate::ProtoString) from `Arbitrary` bytes.
358    #[cfg(feature = "arbitrary")]
359    pub fn arbitrary_proto_string<S: crate::ProtoString>(
360        u: &mut ::arbitrary::Unstructured<'_>,
361    ) -> ::arbitrary::Result<S> {
362        let s: ::alloc::string::String = ::arbitrary::Arbitrary::arbitrary(u)?;
363        Ok(S::from(s))
364    }
365
366    /// Build an `Option<S>` for an explicit-presence `string` field.
367    #[cfg(feature = "arbitrary")]
368    pub fn arbitrary_proto_string_opt<S: crate::ProtoString>(
369        u: &mut ::arbitrary::Unstructured<'_>,
370    ) -> ::arbitrary::Result<::core::option::Option<S>> {
371        let opt: ::core::option::Option<::alloc::string::String> =
372            ::arbitrary::Arbitrary::arbitrary(u)?;
373        Ok(opt.map(S::from))
374    }
375
376    /// Build the collection of a repeated `string` field: `Vec<S>`, or a
377    /// custom [`ProtoList<S>`](crate::ProtoList). The `Deref` bound names the
378    /// element type, so `S` is inferred from the field type.
379    #[cfg(feature = "arbitrary")]
380    pub fn arbitrary_proto_string_vec<S, L>(
381        u: &mut ::arbitrary::Unstructured<'_>,
382    ) -> ::arbitrary::Result<L>
383    where
384        S: crate::ProtoString,
385        L: ::core::ops::Deref<Target = [S]> + ::core::convert::From<::alloc::vec::Vec<S>>,
386    {
387        let vv: ::alloc::vec::Vec<::alloc::string::String> = ::arbitrary::Arbitrary::arbitrary(u)?;
388        Ok(L::from(vv.into_iter().map(S::from).collect()))
389    }
390
391    /// Build a [`ProtoBytes`](crate::ProtoBytes) from `Arbitrary` bytes.
392    #[cfg(feature = "arbitrary")]
393    pub fn arbitrary_proto_bytes<B: crate::ProtoBytes>(
394        u: &mut ::arbitrary::Unstructured<'_>,
395    ) -> ::arbitrary::Result<B> {
396        let v: ::alloc::vec::Vec<u8> = ::arbitrary::Arbitrary::arbitrary(u)?;
397        Ok(B::from(v))
398    }
399
400    /// Build an `Option<B>` for an explicit-presence `bytes` field.
401    #[cfg(feature = "arbitrary")]
402    pub fn arbitrary_proto_bytes_opt<B: crate::ProtoBytes>(
403        u: &mut ::arbitrary::Unstructured<'_>,
404    ) -> ::arbitrary::Result<::core::option::Option<B>> {
405        let opt: ::core::option::Option<::alloc::vec::Vec<u8>> =
406            ::arbitrary::Arbitrary::arbitrary(u)?;
407        Ok(opt.map(B::from))
408    }
409
410    /// Build the collection of a repeated `bytes` field: `Vec<B>`, or a
411    /// custom [`ProtoList<B>`](crate::ProtoList). The `Deref` bound names the
412    /// element type, so `B` is inferred from the field type.
413    #[cfg(feature = "arbitrary")]
414    pub fn arbitrary_proto_bytes_vec<B, L>(
415        u: &mut ::arbitrary::Unstructured<'_>,
416    ) -> ::arbitrary::Result<L>
417    where
418        B: crate::ProtoBytes,
419        L: ::core::ops::Deref<Target = [B]> + ::core::convert::From<::alloc::vec::Vec<B>>,
420    {
421        let vv: ::alloc::vec::Vec<::alloc::vec::Vec<u8>> = ::arbitrary::Arbitrary::arbitrary(u)?;
422        Ok(L::from(vv.into_iter().map(B::from).collect()))
423    }
424
425    // `map` fields: one builder per combination of slots that need converting.
426    // A slot converts when its type is a custom `string` type or a non-default
427    // `bytes` type; any other slot uses its own `Arbitrary` impl. All of them are
428    // generic over the container (any `MapStorage`), so a `HashMap`, `BTreeMap`
429    // or custom map field uses the same builder, and a custom container needs
430    // no `Arbitrary` impl on these fields.
431
432    /// Build a map from entries of the source types `K` and `V`, converting
433    /// each slot through `From`. A slot that needs no conversion passes its
434    /// own type (`From<T> for T`). Consumes the same bytes as
435    /// `HashMap<K, V>`'s `Arbitrary` impl.
436    #[cfg(feature = "arbitrary")]
437    fn arbitrary_map_from<'a, C, K, V>(
438        u: &mut ::arbitrary::Unstructured<'a>,
439    ) -> ::arbitrary::Result<C>
440    where
441        C: crate::map_codec::MapStorage + Default,
442        C::Key: ::core::convert::From<K>,
443        C::Value: ::core::convert::From<V>,
444        K: ::arbitrary::Arbitrary<'a>,
445        V: ::arbitrary::Arbitrary<'a>,
446    {
447        let mut out = C::default();
448        for entry in u.arbitrary_iter::<(K, V)>()? {
449            let (key, value) = entry?;
450            out.storage_insert(key.into(), value.into());
451        }
452        Ok(out)
453    }
454
455    /// Build a `map<K, bytes>` field whose value is a non-default `bytes` type
456    /// (`bytes::Bytes` or a custom one) and whose key is not a custom string.
457    #[cfg(feature = "arbitrary")]
458    pub fn arbitrary_proto_bytes_map<'a, C>(
459        u: &mut ::arbitrary::Unstructured<'a>,
460    ) -> ::arbitrary::Result<C>
461    where
462        C: crate::map_codec::MapStorage + Default,
463        C::Key: ::arbitrary::Arbitrary<'a>,
464        C::Value: crate::ProtoBytes,
465    {
466        arbitrary_map_from::<C, C::Key, ::alloc::vec::Vec<u8>>(u)
467    }
468
469    /// Build a `map<string, V>` field whose key is a custom string type and
470    /// whose value is neither a custom string nor a non-default `bytes` type.
471    #[cfg(feature = "arbitrary")]
472    pub fn arbitrary_proto_string_map_key<'a, C>(
473        u: &mut ::arbitrary::Unstructured<'a>,
474    ) -> ::arbitrary::Result<C>
475    where
476        C: crate::map_codec::MapStorage + Default,
477        C::Key: crate::ProtoString,
478        C::Value: ::arbitrary::Arbitrary<'a>,
479    {
480        arbitrary_map_from::<C, ::alloc::string::String, C::Value>(u)
481    }
482
483    /// Build a `map<K, string>` field whose value is a custom string type and
484    /// whose key is not a `string`.
485    #[cfg(feature = "arbitrary")]
486    pub fn arbitrary_proto_string_map_value<'a, C>(
487        u: &mut ::arbitrary::Unstructured<'a>,
488    ) -> ::arbitrary::Result<C>
489    where
490        C: crate::map_codec::MapStorage + Default,
491        C::Key: ::arbitrary::Arbitrary<'a>,
492        C::Value: crate::ProtoString,
493    {
494        arbitrary_map_from::<C, C::Key, ::alloc::string::String>(u)
495    }
496
497    /// Build a `map<string, string>` field whose key and value are a custom
498    /// string type.
499    #[cfg(feature = "arbitrary")]
500    pub fn arbitrary_proto_string_map<'a, C>(
501        u: &mut ::arbitrary::Unstructured<'a>,
502    ) -> ::arbitrary::Result<C>
503    where
504        C: crate::map_codec::MapStorage + Default,
505        C::Key: crate::ProtoString,
506        C::Value: crate::ProtoString,
507    {
508        arbitrary_map_from::<C, ::alloc::string::String, ::alloc::string::String>(u)
509    }
510
511    /// Build a `map<string, bytes>` field whose key is a custom string type
512    /// and whose value is a non-default `bytes` type.
513    #[cfg(feature = "arbitrary")]
514    pub fn arbitrary_proto_string_bytes_map<'a, C>(
515        u: &mut ::arbitrary::Unstructured<'a>,
516    ) -> ::arbitrary::Result<C>
517    where
518        C: crate::map_codec::MapStorage + Default,
519        C::Key: crate::ProtoString,
520        C::Value: crate::ProtoBytes,
521    {
522        arbitrary_map_from::<C, ::alloc::string::String, ::alloc::vec::Vec<u8>>(u)
523    }
524}
525
526#[cfg(all(test, feature = "arbitrary"))]
527mod arbitrary_tests {
528    use super::__private::{
529        arbitrary_proto_bytes, arbitrary_proto_bytes_map, arbitrary_proto_bytes_opt,
530        arbitrary_proto_bytes_vec, arbitrary_proto_string_bytes_map, arbitrary_proto_string_map,
531        arbitrary_proto_string_map_key, arbitrary_proto_string_map_value, HashMap,
532    };
533    use ::bytes::Bytes;
534    use alloc::{string::String, vec::Vec};
535    use arbitrary::{Arbitrary, Unstructured};
536
537    /// Non-zero seed so the helper has data to consume — an all-zero buffer
538    /// deterministically produces empty vectors regardless of whether the
539    /// helper's inner `Arbitrary` call is wired correctly. The exact lengths
540    /// that arise depend on the `arbitrary` crate's internal byte-consumption
541    /// strategy (and may change between versions), so the tests below assert
542    /// equivalence against the underlying `Vec<u8>` impl from an identical
543    /// `Unstructured` rather than a hard-coded non-empty length.
544    const SEED: [u8; 128] = {
545        let mut a = [0u8; 128];
546        let mut i = 0;
547        while i < 128 {
548            a[i] = (i as u8).wrapping_mul(31).wrapping_add(7);
549            i += 1;
550        }
551        a
552    };
553
554    // The generic `arbitrary_proto_bytes*` builders construct the canonical
555    // `Vec<u8>` and convert via `From`, so for any `ProtoBytes` type they must
556    // mirror the underlying `Vec<u8>` / `Option<Vec<u8>>` / `Vec<Vec<u8>>`
557    // impls byte-for-byte. Exercised here against `bytes::Bytes`.
558    #[test]
559    fn arbitrary_proto_bytes_matches_vec_u8() {
560        let b: Bytes = arbitrary_proto_bytes(&mut Unstructured::new(&SEED)).unwrap();
561        let v: Vec<u8> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
562        assert_eq!(b.as_ref(), v.as_slice());
563        assert!(b.len() <= SEED.len());
564    }
565
566    #[test]
567    fn arbitrary_proto_bytes_opt_matches_option_vec_u8() {
568        let b: Option<Bytes> = arbitrary_proto_bytes_opt(&mut Unstructured::new(&SEED)).unwrap();
569        let v: Option<Vec<u8>> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
570        assert_eq!(b.is_some(), v.is_some());
571        assert_eq!(
572            b.as_ref().map(|x| x.to_vec()),
573            v,
574            "Option<Bytes> builder must mirror Option<Vec<u8>>"
575        );
576    }
577
578    #[test]
579    fn arbitrary_proto_bytes_vec_matches_vec_vec_u8() {
580        let bs: Vec<Bytes> = arbitrary_proto_bytes_vec(&mut Unstructured::new(&SEED)).unwrap();
581        let vs: Vec<Vec<u8>> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
582        assert_eq!(bs.len(), vs.len());
583        for (b, v) in bs.iter().zip(&vs) {
584            assert_eq!(b.as_ref(), v.as_slice());
585        }
586    }
587
588    /// A custom repeated collection with no `Arbitrary` impl.
589    #[derive(Debug, PartialEq)]
590    struct List<T>(Vec<T>);
591
592    impl<T> core::ops::Deref for List<T> {
593        type Target = [T];
594        fn deref(&self) -> &[T] {
595            &self.0
596        }
597    }
598
599    impl<T> From<Vec<T>> for List<T> {
600        fn from(v: Vec<T>) -> Self {
601            List(v)
602        }
603    }
604
605    // The repeated builders return whatever collection the field uses; the
606    // element type is inferred from the collection.
607    #[test]
608    fn arbitrary_proto_vec_builders_fill_a_custom_collection() {
609        use super::__private::arbitrary_proto_string_vec;
610
611        let bs: List<Bytes> = arbitrary_proto_bytes_vec(&mut Unstructured::new(&SEED)).unwrap();
612        let vs: Vec<Vec<u8>> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
613        assert!(!vs.is_empty(), "the seed must produce elements");
614        assert_eq!(bs.iter().map(|b| b.to_vec()).collect::<Vec<_>>(), vs);
615
616        let ss: List<String> = arbitrary_proto_string_vec(&mut Unstructured::new(&SEED)).unwrap();
617        let vs: Vec<String> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
618        assert!(!vs.is_empty(), "the seed must produce elements");
619        assert_eq!(ss, List(vs));
620    }
621
622    // The generic `arbitrary_proto_string` builder is the identity for `String`;
623    // confirm it consumes bytes identically to the native `String` impl.
624    #[test]
625    fn arbitrary_proto_string_matches_string() {
626        use super::__private::arbitrary_proto_string;
627
628        let s: String = arbitrary_proto_string(&mut Unstructured::new(&SEED)).unwrap();
629        let v: String = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
630        assert_eq!(s, v);
631    }
632
633    // The map builders consume the same bytes as the native `HashMap<K, V>`
634    // impl of the source types. `String` and `Bytes` stand in for the custom
635    // types; the `string_map` fixture in `buffa-test` covers a real newtype.
636    fn native_map<K, V>() -> HashMap<K, V>
637    where
638        K: for<'a> Arbitrary<'a> + Eq + core::hash::Hash,
639        V: for<'a> Arbitrary<'a>,
640    {
641        let native: HashMap<K, V> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
642        assert!(!native.is_empty(), "the seed must produce map entries");
643        native
644    }
645
646    #[test]
647    fn arbitrary_proto_string_map_key_matches_native_map() {
648        let mapped: HashMap<String, u32> =
649            arbitrary_proto_string_map_key(&mut Unstructured::new(&SEED)).unwrap();
650        assert_eq!(mapped, native_map::<String, u32>());
651    }
652
653    #[test]
654    fn arbitrary_proto_string_map_value_matches_native_map() {
655        let mapped: HashMap<u32, String> =
656            arbitrary_proto_string_map_value(&mut Unstructured::new(&SEED)).unwrap();
657        assert_eq!(mapped, native_map::<u32, String>());
658    }
659
660    #[test]
661    fn arbitrary_proto_string_map_matches_native_map() {
662        let mapped: HashMap<String, String> =
663            arbitrary_proto_string_map(&mut Unstructured::new(&SEED)).unwrap();
664        assert_eq!(mapped, native_map::<String, String>());
665    }
666
667    #[test]
668    fn arbitrary_proto_string_map_key_fills_a_btree_map() {
669        use alloc::collections::BTreeMap;
670
671        let mapped: BTreeMap<String, u32> =
672            arbitrary_proto_string_map_key(&mut Unstructured::new(&SEED)).unwrap();
673        let native = native_map::<String, u32>();
674        assert_eq!(mapped, native.into_iter().collect());
675    }
676
677    /// A custom map container with no `Arbitrary` impl.
678    #[derive(Default)]
679    struct PairList(Vec<(String, u32)>);
680
681    impl crate::map_codec::MapStorage for PairList {
682        type Key = String;
683        type Value = u32;
684        fn storage_len(&self) -> usize {
685            self.0.len()
686        }
687        fn storage_insert(&mut self, key: String, value: u32) {
688            self.0.retain(|(k, _)| *k != key);
689            self.0.push((key, value));
690        }
691        fn storage_clear(&mut self) {
692            self.0.clear();
693        }
694        fn storage_iter<'a>(&'a self) -> impl Iterator<Item = (&'a String, &'a u32)>
695        where
696            String: 'a,
697            u32: 'a,
698        {
699            self.0.iter().map(|(k, v)| (k, v))
700        }
701    }
702
703    #[test]
704    fn arbitrary_proto_string_map_key_fills_a_container_without_arbitrary() {
705        let mapped: PairList =
706            arbitrary_proto_string_map_key(&mut Unstructured::new(&SEED)).unwrap();
707        let mapped: HashMap<String, u32> = mapped.0.into_iter().collect();
708        assert_eq!(mapped, native_map::<String, u32>());
709    }
710
711    fn to_vec_values<K: Eq + core::hash::Hash>(map: HashMap<K, Bytes>) -> HashMap<K, Vec<u8>> {
712        map.into_iter().map(|(k, v)| (k, v.to_vec())).collect()
713    }
714
715    #[test]
716    fn arbitrary_proto_bytes_map_matches_native_map() {
717        let mapped: HashMap<u32, Bytes> =
718            arbitrary_proto_bytes_map(&mut Unstructured::new(&SEED)).unwrap();
719        assert_eq!(to_vec_values(mapped), native_map::<u32, Vec<u8>>());
720    }
721
722    #[test]
723    fn arbitrary_proto_string_bytes_map_matches_native_map() {
724        let mapped: HashMap<String, Bytes> =
725            arbitrary_proto_string_bytes_map(&mut Unstructured::new(&SEED)).unwrap();
726        assert_eq!(to_vec_values(mapped), native_map::<String, Vec<u8>>());
727    }
728}
729
730/// Minimal fixture types for compile-checking doc examples.
731///
732/// These stand in for generated message types (`Person`, `PersonView`, etc.)
733/// so that crate-level `//!` examples can be `no_run` instead of `ignore`.
734/// The module is `#[doc(hidden)]` — it appears in neither rendered docs
735/// nor IDE autocomplete — and its contents are stripped by LTO in release
736/// builds if unused. Not part of the public API; may change at any time.
737///
738/// README.md examples remain `ignore` because GitHub/crates.io Markdown
739/// rendering would show hidden `#` lines.
740#[doc(hidden)]
741pub mod __doctest_fixtures {
742    use crate::*;
743
744    #[derive(Clone, Default, PartialEq)]
745    pub struct Person {
746        pub name: alloc::string::String,
747        pub id: i32,
748    }
749
750    impl DefaultInstance for Person {
751        fn default_instance() -> &'static Self {
752            static INST: __private::OnceBox<Person> = __private::OnceBox::new();
753            INST.get_or_init(|| alloc::boxed::Box::new(Self::default()))
754        }
755    }
756
757    impl Message for Person {
758        fn compute_size(&self, _cache: &mut SizeCache) -> u32 {
759            0
760        }
761        fn write_to(&self, _cache: &mut SizeCache, _buf: &mut impl crate::EncodeSink) {}
762        fn merge_field(
763            &mut self,
764            tag: crate::encoding::Tag,
765            buf: &mut impl bytes::Buf,
766            _ctx: DecodeContext<'_>,
767        ) -> Result<(), DecodeError> {
768            crate::encoding::skip_field(tag, buf)
769        }
770        fn clear(&mut self) {
771            *self = Self::default();
772        }
773    }
774
775    #[derive(Clone, Debug, Default)]
776    pub struct PersonView<'a> {
777        pub name: &'a str,
778        pub id: i32,
779    }
780
781    impl<'a> view::MessageView<'a> for PersonView<'a> {
782        type Owned = Person;
783        fn decode_view(_buf: &'a [u8]) -> Result<Self, DecodeError> {
784            // Stub: examples are `no_run`, so this never executes.
785            Ok(PersonView::default())
786        }
787        fn merge_view_field(
788            &mut self,
789            _tag: encoding::Tag,
790            cur: &'a [u8],
791            _before_tag: &'a [u8],
792            _ctx: DecodeContext<'_>,
793        ) -> Result<&'a [u8], DecodeError> {
794            // Stub for the doc-example view; never executes.
795            Ok(cur)
796        }
797        fn to_owned_message(&self) -> Result<Person, DecodeError> {
798            Ok(Person {
799                name: self.name.into(),
800                id: self.id,
801            })
802        }
803    }
804
805    impl view::ViewReborrow for PersonView<'static> {
806        type Reborrowed<'b> = PersonView<'b>;
807        fn reborrow<'b>(this: &'b Self) -> &'b Self::Reborrowed<'b> {
808            this
809        }
810    }
811
812    // SAFETY: `PersonView<'a>` is generic over `'a`; every impl on it other
813    // than the canonical `ViewReborrow` shape above is parametric in `'a`, so
814    // none can retain a buffer borrow past `Self`.
815    unsafe impl view::ViewLifetimeParametric for PersonView<'static> {}
816}
817
818/// Wipe-owning collections and support for opt-in generated cleanup.
819#[cfg(feature = "zeroize")]
820pub mod sensitive;
821
822mod erasing;