onc_xdr/lib.rs
1//! XDR (External Data Representation) codec -- [RFC 4506].
2//!
3//! Every ONC RPC protocol encodes its arguments and results with XDR. The
4//! rules that matter for reading the protocol crates built on this one:
5//!
6//! * Integers are big-endian and always occupy a multiple of 4 bytes. A
7//! `u8`, a `bool`, and a `u32` all take 4 bytes on the wire.
8//! * Variable-length data (opaque byte strings, arrays) is length-prefixed by
9//! a 4-byte count and then zero-padded up to the next 4-byte boundary.
10//! * Fixed-length opaque data carries no length prefix -- NFSv2's 32-byte file
11//! handle is 32 raw bytes, whereas NFSv3's is a prefixed byte string.
12//! * Discriminated unions lead with a 4-byte discriminant.
13//!
14//! [`Pack`] and [`Unpack`] are the two traits every wire type implements.
15//! Most types get them from `#[derive(XdrCodec)]`, re-exported here; types
16//! whose encoding does not follow the mechanical field-by-field rule implement
17//! them by hand.
18//!
19//! # Decoding untrusted input
20//!
21//! Every length and count on the wire is chosen by the peer. [`util`] provides
22//! the hardened readers the protocol crates use instead of sizing an
23//! allocation from a declared length directly -- see [`PREALLOC_CAP`].
24//!
25//! [RFC 4506]: https://www.rfc-editor.org/rfc/rfc4506
26
27// The XdrCodec derive macro expands to `::onc_xdr::` paths so that it works
28// for downstream crates. This alias lets those same paths resolve when the
29// macro is used inside this crate.
30#[expect(unused_extern_crates, reason = "required for derive macro path resolution")]
31extern crate self as onc_xdr;
32
33mod error;
34mod list;
35mod opaque;
36mod primitives;
37mod traits;
38pub mod util;
39mod void;
40
41pub use onc_xdr_derive::XdrCodec;
42
43pub use self::error::Error;
44pub use self::list::{BoundedList, List};
45pub use self::opaque::Opaque;
46pub use self::traits::{Pack, Unpack};
47pub use self::util::{PREALLOC_CAP, pack_string, read_bytes, skip_pad, string_packed_size, unpack_string, vec_with_capacity, write_pad};
48pub use self::void::Void;
49
50/// Result of an XDR encode or decode operation.
51pub type Result<T> = std::result::Result<T, Error>;