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;