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.3/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.3 --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// Retain the original hidden root path for already-generated callers.
231#[cfg(feature = "json")]
232#[doc(hidden)]
233pub use json_helpers::reject_other_json_kinds;
234// Generated-code plumbing: codecs are named via turbofish by `write_to` /
235// `merge_field` emission, never by hand-written code. Hidden so the codec
236// ZSTs and their sealed traits don't surface as consumer API on docs.rs.
237#[doc(hidden)]
238pub mod map_codec;
239pub mod message;
240pub mod message_field;
241pub mod message_set;
242pub mod oneof;
243mod size_cache;
244// Runtime for table-driven message codecs, called by generated code; see the
245// module docs.
246#[doc(hidden)]
247pub mod table;
248#[cfg(test)]
249pub(crate) mod test_doubles;
250#[cfg(feature = "text")]
251pub mod text;
252#[cfg(any(feature = "json", feature = "text"))]
253pub mod type_registry;
254pub mod types;
255pub mod unknown_fields;
256pub mod view;
257
258// ── User-facing re-exports ─────────────────────────────────────────────────────
259// Types that appear in user code: trait bounds, field types, return types,
260// and things users explicitly construct or call methods on.
261
262pub use encode_sink::{EncodeSink, Rope, RopeBuf, DEFAULT_MIN_SEGMENT};
263pub use enumeration::{EnumValue, Enumeration};
264pub use error::{DecodeError, EncodeError};
265pub use extension::{Extension, ExtensionCodec, ExtensionSet};
266/// Re-exported so downstream code that needs to name the hasher type behind
267/// [`Map`] (in an explicit signature, or to `with_capacity_and_hasher` without
268/// inference) does so against buffa's `foldhash` version rather than a
269/// separately-resolved one. This couples buffa's public-API semver to
270/// `foldhash`'s major version. Most callers should not need this — `Map` and
271/// `Default::default()` keep the hasher fully inferred.
272pub use foldhash;
273pub use map_codec::{Map, MapStorage};
274pub use message::{
275    checked_encode_size, saturate_size, DecodeContext, DecodeOptions, Message, MessageName,
276    DEFAULT_ELEMENT_MEMORY_LIMIT, DEFAULT_UNKNOWN_FIELD_LIMIT, MAX_MESSAGE_BYTES, RECURSION_LIMIT,
277};
278#[doc(hidden)]
279pub use message::{debug_assert_two_pass, encode_size_overflow};
280pub use message_field::{DefaultInstance, Inline, MessageField, ProtoBox};
281pub use oneof::Oneof;
282pub use size_cache::{SizeCache, SizeCachePool};
283pub use types::{AsSharedBytes, FieldPayload, ProtoBytes, ProtoList, ProtoString, WirePayload};
284pub use unknown_fields::{UnknownField, UnknownFieldData, UnknownFields};
285
286#[cfg(feature = "text")]
287pub use text::TextFormat;
288pub use view::{
289    DefaultViewInstance, HasMessageView, LazyMessageFieldView, LazyMessageView, LazyRepeatedView,
290    MapView, MessageFieldView, MessageView, OwnedView, RepeatedView, UnknownFieldsView, ViewEncode,
291    ViewLifetimeParametric, ViewReborrow,
292};
293
294/// Private re-exports used exclusively by generated code.
295///
296/// Not part of the public API. These items may change or disappear in any
297/// release. Do not use them directly.
298#[doc(hidden)]
299pub mod __private {
300    /// Whether the active JSON parse options reject a `google.protobuf.Any`
301    /// `@type` without a `/`. The `Any` deserializer in `buffa-types` reads
302    /// it.
303    #[cfg(feature = "json")]
304    #[must_use]
305    pub fn strict_any_type_urls() -> bool {
306        crate::json::strict_any_type_urls()
307    }
308
309    /// The memory one element of a repeated field occupies in the collection
310    /// holding it, for charging against
311    /// [`DecodeContext::register_element_memory`](crate::DecodeContext::register_element_memory).
312    ///
313    /// Takes the element by reference and reports `size_of::<T>()` — for a view
314    /// element that is the borrowed pointer's own width, not the length of what
315    /// it points at, which is what the collection actually grows by. Generated
316    /// code calls this rather than `size_of_val` so the distinction is named
317    /// rather than left to a reader to infer from a double reference.
318    #[inline(always)]
319    #[must_use]
320    pub fn element_footprint<T>(_element: &T) -> usize {
321        core::mem::size_of::<T>()
322    }
323
324    /// Re-exported for use in generated `DefaultInstance` implementations.
325    ///
326    /// Generated code refers to this as `::buffa::__private::OnceBox<T>` so
327    /// that downstream crates do not need a direct `once_cell` dependency.
328    pub use once_cell::race::OnceBox;
329
330    /// The concrete `map<K, V>` field type generated code uses by default.
331    ///
332    /// Generated code refers to this as `::buffa::__private::HashMap<K, V>`
333    /// so that downstream crates do not need a direct dependency on the
334    /// hasher or container crate.
335    ///
336    /// On `std` builds this is `std::collections::HashMap` parameterized with
337    /// [`foldhash::fast::RandomState`] as the hasher; on `no_std` builds it is
338    /// `hashbrown::HashMap` (which defaults to the same `foldhash` hasher).
339    /// The table implementation is identical either way — `std::collections::HashMap`
340    /// is itself a thin wrapper around hashbrown's SwissTable — so the only
341    /// load-bearing choice here is the hasher.
342    ///
343    /// See [`Map`](crate::Map) for the hasher rationale and construction
344    /// guidance.
345    #[cfg(not(feature = "std"))]
346    pub type HashMap<K, V> = hashbrown::HashMap<K, V>;
347    #[cfg(feature = "std")]
348    pub type HashMap<K, V> = std::collections::HashMap<K, V, foldhash::fast::RandomState>;
349
350    // ── Type-agnostic `Arbitrary` builders for configurable owned types ──────
351    //
352    // Codegen attaches them to any field whose representation is non-default,
353    // selecting by *kind* (string vs bytes, singular vs optional vs repeated)
354    // rather than by the concrete type. They build the canonical `String` /
355    // `Vec<u8>` first and convert through the `From` bound, so a substituted
356    // type needs no native `Arbitrary` impl and codegen carries no knowledge of
357    // any specific type. Materializing the canonical type first also keeps
358    // byte-consumption order identical to the default-representation impl,
359    // which the parity tests assert.
360
361    /// Build a [`ProtoString`](crate::ProtoString) from `Arbitrary` bytes.
362    #[cfg(feature = "arbitrary")]
363    pub fn arbitrary_proto_string<S: crate::ProtoString>(
364        u: &mut ::arbitrary::Unstructured<'_>,
365    ) -> ::arbitrary::Result<S> {
366        let s: ::alloc::string::String = ::arbitrary::Arbitrary::arbitrary(u)?;
367        Ok(S::from(s))
368    }
369
370    /// Build an `Option<S>` for an explicit-presence `string` field.
371    #[cfg(feature = "arbitrary")]
372    pub fn arbitrary_proto_string_opt<S: crate::ProtoString>(
373        u: &mut ::arbitrary::Unstructured<'_>,
374    ) -> ::arbitrary::Result<::core::option::Option<S>> {
375        let opt: ::core::option::Option<::alloc::string::String> =
376            ::arbitrary::Arbitrary::arbitrary(u)?;
377        Ok(opt.map(S::from))
378    }
379
380    /// Build the collection of a repeated `string` field: `Vec<S>`, or a
381    /// custom [`ProtoList<S>`](crate::ProtoList). The `Deref` bound names the
382    /// element type, so `S` is inferred from the field type.
383    #[cfg(feature = "arbitrary")]
384    pub fn arbitrary_proto_string_vec<S, L>(
385        u: &mut ::arbitrary::Unstructured<'_>,
386    ) -> ::arbitrary::Result<L>
387    where
388        S: crate::ProtoString,
389        L: ::core::ops::Deref<Target = [S]> + ::core::convert::From<::alloc::vec::Vec<S>>,
390    {
391        let vv: ::alloc::vec::Vec<::alloc::string::String> = ::arbitrary::Arbitrary::arbitrary(u)?;
392        Ok(L::from(vv.into_iter().map(S::from).collect()))
393    }
394
395    /// Build a [`ProtoBytes`](crate::ProtoBytes) from `Arbitrary` bytes.
396    #[cfg(feature = "arbitrary")]
397    pub fn arbitrary_proto_bytes<B: crate::ProtoBytes>(
398        u: &mut ::arbitrary::Unstructured<'_>,
399    ) -> ::arbitrary::Result<B> {
400        let v: ::alloc::vec::Vec<u8> = ::arbitrary::Arbitrary::arbitrary(u)?;
401        Ok(B::from(v))
402    }
403
404    /// Build an `Option<B>` for an explicit-presence `bytes` field.
405    #[cfg(feature = "arbitrary")]
406    pub fn arbitrary_proto_bytes_opt<B: crate::ProtoBytes>(
407        u: &mut ::arbitrary::Unstructured<'_>,
408    ) -> ::arbitrary::Result<::core::option::Option<B>> {
409        let opt: ::core::option::Option<::alloc::vec::Vec<u8>> =
410            ::arbitrary::Arbitrary::arbitrary(u)?;
411        Ok(opt.map(B::from))
412    }
413
414    /// Build the collection of a repeated `bytes` field: `Vec<B>`, or a
415    /// custom [`ProtoList<B>`](crate::ProtoList). The `Deref` bound names the
416    /// element type, so `B` is inferred from the field type.
417    #[cfg(feature = "arbitrary")]
418    pub fn arbitrary_proto_bytes_vec<B, L>(
419        u: &mut ::arbitrary::Unstructured<'_>,
420    ) -> ::arbitrary::Result<L>
421    where
422        B: crate::ProtoBytes,
423        L: ::core::ops::Deref<Target = [B]> + ::core::convert::From<::alloc::vec::Vec<B>>,
424    {
425        let vv: ::alloc::vec::Vec<::alloc::vec::Vec<u8>> = ::arbitrary::Arbitrary::arbitrary(u)?;
426        Ok(L::from(vv.into_iter().map(B::from).collect()))
427    }
428
429    // `map` fields: one builder per combination of slots that need converting.
430    // A slot converts when its type is a custom `string` type or a non-default
431    // `bytes` type; any other slot uses its own `Arbitrary` impl. All of them are
432    // generic over the container (any `MapStorage`), so a `HashMap`, `BTreeMap`
433    // or custom map field uses the same builder, and a custom container needs
434    // no `Arbitrary` impl on these fields.
435
436    /// Build a map from entries of the source types `K` and `V`, converting
437    /// each slot through `From`. A slot that needs no conversion passes its
438    /// own type (`From<T> for T`). Consumes the same bytes as
439    /// `HashMap<K, V>`'s `Arbitrary` impl.
440    #[cfg(feature = "arbitrary")]
441    fn arbitrary_map_from<'a, C, K, V>(
442        u: &mut ::arbitrary::Unstructured<'a>,
443    ) -> ::arbitrary::Result<C>
444    where
445        C: crate::map_codec::MapStorage + Default,
446        C::Key: ::core::convert::From<K>,
447        C::Value: ::core::convert::From<V>,
448        K: ::arbitrary::Arbitrary<'a>,
449        V: ::arbitrary::Arbitrary<'a>,
450    {
451        let mut out = C::default();
452        for entry in u.arbitrary_iter::<(K, V)>()? {
453            let (key, value) = entry?;
454            out.storage_insert(key.into(), value.into());
455        }
456        Ok(out)
457    }
458
459    /// Build a `map<K, bytes>` field whose value is a non-default `bytes` type
460    /// (`bytes::Bytes` or a custom one) and whose key is not a custom string.
461    #[cfg(feature = "arbitrary")]
462    pub fn arbitrary_proto_bytes_map<'a, C>(
463        u: &mut ::arbitrary::Unstructured<'a>,
464    ) -> ::arbitrary::Result<C>
465    where
466        C: crate::map_codec::MapStorage + Default,
467        C::Key: ::arbitrary::Arbitrary<'a>,
468        C::Value: crate::ProtoBytes,
469    {
470        arbitrary_map_from::<C, C::Key, ::alloc::vec::Vec<u8>>(u)
471    }
472
473    /// Build a `map<string, V>` field whose key is a custom string type and
474    /// whose value is neither a custom string nor a non-default `bytes` type.
475    #[cfg(feature = "arbitrary")]
476    pub fn arbitrary_proto_string_map_key<'a, C>(
477        u: &mut ::arbitrary::Unstructured<'a>,
478    ) -> ::arbitrary::Result<C>
479    where
480        C: crate::map_codec::MapStorage + Default,
481        C::Key: crate::ProtoString,
482        C::Value: ::arbitrary::Arbitrary<'a>,
483    {
484        arbitrary_map_from::<C, ::alloc::string::String, C::Value>(u)
485    }
486
487    /// Build a `map<K, string>` field whose value is a custom string type and
488    /// whose key is not a `string`.
489    #[cfg(feature = "arbitrary")]
490    pub fn arbitrary_proto_string_map_value<'a, C>(
491        u: &mut ::arbitrary::Unstructured<'a>,
492    ) -> ::arbitrary::Result<C>
493    where
494        C: crate::map_codec::MapStorage + Default,
495        C::Key: ::arbitrary::Arbitrary<'a>,
496        C::Value: crate::ProtoString,
497    {
498        arbitrary_map_from::<C, C::Key, ::alloc::string::String>(u)
499    }
500
501    /// Build a `map<string, string>` field whose key and value are a custom
502    /// string type.
503    #[cfg(feature = "arbitrary")]
504    pub fn arbitrary_proto_string_map<'a, C>(
505        u: &mut ::arbitrary::Unstructured<'a>,
506    ) -> ::arbitrary::Result<C>
507    where
508        C: crate::map_codec::MapStorage + Default,
509        C::Key: crate::ProtoString,
510        C::Value: crate::ProtoString,
511    {
512        arbitrary_map_from::<C, ::alloc::string::String, ::alloc::string::String>(u)
513    }
514
515    /// Build a `map<string, bytes>` field whose key is a custom string type
516    /// and whose value is a non-default `bytes` type.
517    #[cfg(feature = "arbitrary")]
518    pub fn arbitrary_proto_string_bytes_map<'a, C>(
519        u: &mut ::arbitrary::Unstructured<'a>,
520    ) -> ::arbitrary::Result<C>
521    where
522        C: crate::map_codec::MapStorage + Default,
523        C::Key: crate::ProtoString,
524        C::Value: crate::ProtoBytes,
525    {
526        arbitrary_map_from::<C, ::alloc::string::String, ::alloc::vec::Vec<u8>>(u)
527    }
528}
529
530#[cfg(all(test, feature = "arbitrary"))]
531mod arbitrary_tests {
532    use super::__private::{
533        arbitrary_proto_bytes, arbitrary_proto_bytes_map, arbitrary_proto_bytes_opt,
534        arbitrary_proto_bytes_vec, arbitrary_proto_string_bytes_map, arbitrary_proto_string_map,
535        arbitrary_proto_string_map_key, arbitrary_proto_string_map_value, HashMap,
536    };
537    use ::bytes::Bytes;
538    use alloc::{string::String, vec::Vec};
539    use arbitrary::{Arbitrary, Unstructured};
540
541    /// Non-zero seed so the helper has data to consume — an all-zero buffer
542    /// deterministically produces empty vectors regardless of whether the
543    /// helper's inner `Arbitrary` call is wired correctly. The exact lengths
544    /// that arise depend on the `arbitrary` crate's internal byte-consumption
545    /// strategy (and may change between versions), so the tests below assert
546    /// equivalence against the underlying `Vec<u8>` impl from an identical
547    /// `Unstructured` rather than a hard-coded non-empty length.
548    const SEED: [u8; 128] = {
549        let mut a = [0u8; 128];
550        let mut i = 0;
551        while i < 128 {
552            a[i] = (i as u8).wrapping_mul(31).wrapping_add(7);
553            i += 1;
554        }
555        a
556    };
557
558    // The generic `arbitrary_proto_bytes*` builders construct the canonical
559    // `Vec<u8>` and convert via `From`, so for any `ProtoBytes` type they must
560    // mirror the underlying `Vec<u8>` / `Option<Vec<u8>>` / `Vec<Vec<u8>>`
561    // impls byte-for-byte. Exercised here against `bytes::Bytes`.
562    #[test]
563    fn arbitrary_proto_bytes_matches_vec_u8() {
564        let b: Bytes = arbitrary_proto_bytes(&mut Unstructured::new(&SEED)).unwrap();
565        let v: Vec<u8> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
566        assert_eq!(b.as_ref(), v.as_slice());
567        assert!(b.len() <= SEED.len());
568    }
569
570    #[test]
571    fn arbitrary_proto_bytes_opt_matches_option_vec_u8() {
572        let b: Option<Bytes> = arbitrary_proto_bytes_opt(&mut Unstructured::new(&SEED)).unwrap();
573        let v: Option<Vec<u8>> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
574        assert_eq!(b.is_some(), v.is_some());
575        assert_eq!(
576            b.as_ref().map(|x| x.to_vec()),
577            v,
578            "Option<Bytes> builder must mirror Option<Vec<u8>>"
579        );
580    }
581
582    #[test]
583    fn arbitrary_proto_bytes_vec_matches_vec_vec_u8() {
584        let bs: Vec<Bytes> = arbitrary_proto_bytes_vec(&mut Unstructured::new(&SEED)).unwrap();
585        let vs: Vec<Vec<u8>> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
586        assert_eq!(bs.len(), vs.len());
587        for (b, v) in bs.iter().zip(&vs) {
588            assert_eq!(b.as_ref(), v.as_slice());
589        }
590    }
591
592    /// A custom repeated collection with no `Arbitrary` impl.
593    #[derive(Debug, PartialEq)]
594    struct List<T>(Vec<T>);
595
596    impl<T> core::ops::Deref for List<T> {
597        type Target = [T];
598        fn deref(&self) -> &[T] {
599            &self.0
600        }
601    }
602
603    impl<T> From<Vec<T>> for List<T> {
604        fn from(v: Vec<T>) -> Self {
605            List(v)
606        }
607    }
608
609    // The repeated builders return whatever collection the field uses; the
610    // element type is inferred from the collection.
611    #[test]
612    fn arbitrary_proto_vec_builders_fill_a_custom_collection() {
613        use super::__private::arbitrary_proto_string_vec;
614
615        let bs: List<Bytes> = arbitrary_proto_bytes_vec(&mut Unstructured::new(&SEED)).unwrap();
616        let vs: Vec<Vec<u8>> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
617        assert!(!vs.is_empty(), "the seed must produce elements");
618        assert_eq!(bs.iter().map(|b| b.to_vec()).collect::<Vec<_>>(), vs);
619
620        let ss: List<String> = arbitrary_proto_string_vec(&mut Unstructured::new(&SEED)).unwrap();
621        let vs: Vec<String> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
622        assert!(!vs.is_empty(), "the seed must produce elements");
623        assert_eq!(ss, List(vs));
624    }
625
626    // The generic `arbitrary_proto_string` builder is the identity for `String`;
627    // confirm it consumes bytes identically to the native `String` impl.
628    #[test]
629    fn arbitrary_proto_string_matches_string() {
630        use super::__private::arbitrary_proto_string;
631
632        let s: String = arbitrary_proto_string(&mut Unstructured::new(&SEED)).unwrap();
633        let v: String = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
634        assert_eq!(s, v);
635    }
636
637    // The map builders consume the same bytes as the native `HashMap<K, V>`
638    // impl of the source types. `String` and `Bytes` stand in for the custom
639    // types; the `string_map` fixture in `buffa-test` covers a real newtype.
640    fn native_map<K, V>() -> HashMap<K, V>
641    where
642        K: for<'a> Arbitrary<'a> + Eq + core::hash::Hash,
643        V: for<'a> Arbitrary<'a>,
644    {
645        let native: HashMap<K, V> = Arbitrary::arbitrary(&mut Unstructured::new(&SEED)).unwrap();
646        assert!(!native.is_empty(), "the seed must produce map entries");
647        native
648    }
649
650    #[test]
651    fn arbitrary_proto_string_map_key_matches_native_map() {
652        let mapped: HashMap<String, u32> =
653            arbitrary_proto_string_map_key(&mut Unstructured::new(&SEED)).unwrap();
654        assert_eq!(mapped, native_map::<String, u32>());
655    }
656
657    #[test]
658    fn arbitrary_proto_string_map_value_matches_native_map() {
659        let mapped: HashMap<u32, String> =
660            arbitrary_proto_string_map_value(&mut Unstructured::new(&SEED)).unwrap();
661        assert_eq!(mapped, native_map::<u32, String>());
662    }
663
664    #[test]
665    fn arbitrary_proto_string_map_matches_native_map() {
666        let mapped: HashMap<String, String> =
667            arbitrary_proto_string_map(&mut Unstructured::new(&SEED)).unwrap();
668        assert_eq!(mapped, native_map::<String, String>());
669    }
670
671    #[test]
672    fn arbitrary_proto_string_map_key_fills_a_btree_map() {
673        use alloc::collections::BTreeMap;
674
675        let mapped: BTreeMap<String, u32> =
676            arbitrary_proto_string_map_key(&mut Unstructured::new(&SEED)).unwrap();
677        let native = native_map::<String, u32>();
678        assert_eq!(mapped, native.into_iter().collect());
679    }
680
681    /// A custom map container with no `Arbitrary` impl.
682    #[derive(Default)]
683    struct PairList(Vec<(String, u32)>);
684
685    impl crate::map_codec::MapStorage for PairList {
686        type Key = String;
687        type Value = u32;
688        fn storage_len(&self) -> usize {
689            self.0.len()
690        }
691        fn storage_insert(&mut self, key: String, value: u32) {
692            self.0.retain(|(k, _)| *k != key);
693            self.0.push((key, value));
694        }
695        fn storage_clear(&mut self) {
696            self.0.clear();
697        }
698        fn storage_iter<'a>(&'a self) -> impl Iterator<Item = (&'a String, &'a u32)>
699        where
700            String: 'a,
701            u32: 'a,
702        {
703            self.0.iter().map(|(k, v)| (k, v))
704        }
705    }
706
707    #[test]
708    fn arbitrary_proto_string_map_key_fills_a_container_without_arbitrary() {
709        let mapped: PairList =
710            arbitrary_proto_string_map_key(&mut Unstructured::new(&SEED)).unwrap();
711        let mapped: HashMap<String, u32> = mapped.0.into_iter().collect();
712        assert_eq!(mapped, native_map::<String, u32>());
713    }
714
715    fn to_vec_values<K: Eq + core::hash::Hash>(map: HashMap<K, Bytes>) -> HashMap<K, Vec<u8>> {
716        map.into_iter().map(|(k, v)| (k, v.to_vec())).collect()
717    }
718
719    #[test]
720    fn arbitrary_proto_bytes_map_matches_native_map() {
721        let mapped: HashMap<u32, Bytes> =
722            arbitrary_proto_bytes_map(&mut Unstructured::new(&SEED)).unwrap();
723        assert_eq!(to_vec_values(mapped), native_map::<u32, Vec<u8>>());
724    }
725
726    #[test]
727    fn arbitrary_proto_string_bytes_map_matches_native_map() {
728        let mapped: HashMap<String, Bytes> =
729            arbitrary_proto_string_bytes_map(&mut Unstructured::new(&SEED)).unwrap();
730        assert_eq!(to_vec_values(mapped), native_map::<String, Vec<u8>>());
731    }
732}
733
734/// Minimal fixture types for compile-checking doc examples.
735///
736/// These stand in for generated message types (`Person`, `PersonView`, etc.)
737/// so that crate-level `//!` examples can be `no_run` instead of `ignore`.
738/// The module is `#[doc(hidden)]` — it appears in neither rendered docs
739/// nor IDE autocomplete — and its contents are stripped by LTO in release
740/// builds if unused. Not part of the public API; may change at any time.
741///
742/// README.md examples remain `ignore` because GitHub/crates.io Markdown
743/// rendering would show hidden `#` lines.
744#[doc(hidden)]
745pub mod __doctest_fixtures {
746    use crate::*;
747
748    #[derive(Clone, Default, PartialEq)]
749    pub struct Person {
750        pub name: alloc::string::String,
751        pub id: i32,
752    }
753
754    impl DefaultInstance for Person {
755        fn default_instance() -> &'static Self {
756            static INST: __private::OnceBox<Person> = __private::OnceBox::new();
757            INST.get_or_init(|| alloc::boxed::Box::new(Self::default()))
758        }
759    }
760
761    impl Message for Person {
762        fn compute_size(&self, _cache: &mut SizeCache) -> u32 {
763            0
764        }
765        fn write_to(&self, _cache: &mut SizeCache, _buf: &mut impl crate::EncodeSink) {}
766        fn merge_field(
767            &mut self,
768            tag: crate::encoding::Tag,
769            buf: &mut impl bytes::Buf,
770            _ctx: DecodeContext<'_>,
771        ) -> Result<(), DecodeError> {
772            crate::encoding::skip_field(tag, buf)
773        }
774        fn clear(&mut self) {
775            *self = Self::default();
776        }
777    }
778
779    #[derive(Clone, Debug, Default)]
780    pub struct PersonView<'a> {
781        pub name: &'a str,
782        pub id: i32,
783    }
784
785    impl<'a> view::MessageView<'a> for PersonView<'a> {
786        type Owned = Person;
787        fn decode_view(_buf: &'a [u8]) -> Result<Self, DecodeError> {
788            // Stub: examples are `no_run`, so this never executes.
789            Ok(PersonView::default())
790        }
791        fn merge_view_field(
792            &mut self,
793            _tag: encoding::Tag,
794            cur: &'a [u8],
795            _before_tag: &'a [u8],
796            _ctx: DecodeContext<'_>,
797        ) -> Result<&'a [u8], DecodeError> {
798            // Stub for the doc-example view; never executes.
799            Ok(cur)
800        }
801        fn to_owned_message(&self) -> Result<Person, DecodeError> {
802            Ok(Person {
803                name: self.name.into(),
804                id: self.id,
805            })
806        }
807    }
808
809    impl view::ViewReborrow for PersonView<'static> {
810        type Reborrowed<'b> = PersonView<'b>;
811        fn reborrow<'b>(this: &'b Self) -> &'b Self::Reborrowed<'b> {
812            this
813        }
814    }
815
816    // SAFETY: `PersonView<'a>` is generic over `'a`; every impl on it other
817    // than the canonical `ViewReborrow` shape above is parametric in `'a`, so
818    // none can retain a buffer borrow past `Self`.
819    unsafe impl view::ViewLifetimeParametric for PersonView<'static> {}
820}
821
822/// Wipe-owning collections and support for opt-in generated cleanup.
823#[cfg(feature = "zeroize")]
824pub mod sensitive;
825
826mod erasing;