xdr_common/lib.rs
1//! Common types for XDR (External Data Representation) encoding and decoding.
2//!
3//! This crate provides length-constrained collection types for XDR serialization:
4//! - [`VecM`] - Generic vector with maximum length constraint
5//! - [`BytesM`] - Byte vector with maximum length constraint
6//! - [`StringM`] - String (as bytes) with maximum length constraint
7//!
8//! # Features
9//!
10//! - **`alloc`** - Enables heap allocation support (required for most functionality)
11//! - **`std`** - Enables standard library support (implies `alloc`)
12//! - **`serde`** - Enables serde serialization/deserialization (implies `alloc`)
13//! - **`schemars`** - Enables JSON Schema generation via schemars (implies `alloc`)
14//!
15//! # no_std Support
16//!
17//! This crate is `no_std` by default. Enable the `alloc` feature for heap-allocated
18//! collections, or `std` for full standard library support.
19//!
20//! # Examples
21//!
22//! ```ignore
23//! use xdr_common::{VecM, BytesM, StringM};
24//!
25//! // Create a vector with max length of 10
26//! let v: VecM<u32, 10> = vec![1, 2, 3].try_into()?;
27//!
28//! // Create a byte array with max length of 100
29//! let b: BytesM<100> = b"hello".as_slice().try_into()?;
30//!
31//! // Create a string with max length of 50
32//! let s: StringM<50> = "world".try_into()?;
33//! ```
34
35#![cfg_attr(docsrs, feature(doc_cfg))]
36#![no_std]
37#![warn(missing_docs)]
38
39#[cfg(feature = "alloc")]
40extern crate alloc;
41
42mod cfg;
43pub use cfg::{Box, Vec, box_as_ref};
44
45mod error;
46pub use error::*;
47
48/// The maximum number of bytes a decoder will preallocate for a
49/// variable-length collection before reading its elements.
50///
51/// Decoded lengths are untrusted, so capacity reservations are capped at
52/// this many bytes to prevent memory-exhaustion attacks from maliciously
53/// large length prefixes; collections grow normally beyond it.
54#[cfg(feature = "alloc")]
55#[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
56pub const MAX_PREALLOC_BYTES: usize = 0x1_0000;
57
58mod vecm;
59pub use vecm::*;
60
61mod bytesm;
62pub use bytesm::*;
63
64mod stringm;
65pub use stringm::*;
66
67#[cfg(feature = "serde")]
68#[cfg_attr(docsrs, doc(cfg(feature = "serde")))]
69pub mod serde_hex;