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.2/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.2 --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;