facet-xdr 0.44.3

XDR serialization for facet using the new format architecture - successor to facet-xdr
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! XDR (External Data Representation) format support via facet-format.
//!
//! XDR is a binary format defined in RFC 4506 for encoding structured data.
//! It is primarily used in Sun RPC (ONC RPC) protocols.
//!
//! Key characteristics:
//! - Big-endian byte order
//! - Fixed-size integers (4 bytes for i32/u32, 8 bytes for i64/u64)
//! - No support for i128/u128
//! - Strings are length-prefixed with 4-byte aligned padding
//! - Arrays have explicit length prefixes
//!
//! # Serialization
//!
//! ```
//! use facet::Facet;
//! use facet_xdr::to_vec;
//!
//! #[derive(Facet)]
//! struct Point { x: i32, y: i32 }
//!
//! let point = Point { x: 10, y: 20 };
//! let bytes = to_vec(&point).unwrap();
//! ```
//!
//! # Deserialization
//!
//! ```
//! use facet::Facet;
//! use facet_xdr::from_slice;
//!
//! #[derive(Facet, Debug, PartialEq)]
//! struct Point { x: i32, y: i32 }
//!
//! // XDR encoding of Point { x: 10, y: 20 }
//! let bytes = &[0, 0, 0, 10, 0, 0, 0, 20];
//! let point: Point = from_slice(bytes).unwrap();
//! assert_eq!(point.x, 10);
//! assert_eq!(point.y, 20);
//! ```

#![forbid(unsafe_code)]

extern crate alloc;

mod error;
mod parser;
mod serializer;

pub use error::{XdrError, XdrSerializeError};
pub use parser::XdrParser;
pub use serializer::{XdrSerializer, to_vec, to_writer};

// Re-export DeserializeError for convenience
pub use facet_format::DeserializeError;

/// Deserialize a value from XDR bytes into an owned type.
///
/// This is the recommended default for most use cases.
///
/// # Example
///
/// ```
/// use facet::Facet;
/// use facet_xdr::from_slice;
///
/// #[derive(Facet, Debug, PartialEq)]
/// struct Point { x: i32, y: i32 }
///
/// // XDR encoding of Point { x: 10, y: 20 }
/// let bytes = &[0, 0, 0, 10, 0, 0, 0, 20];
/// let point: Point = from_slice(bytes).unwrap();
/// assert_eq!(point.x, 10);
/// assert_eq!(point.y, 20);
/// ```
pub fn from_slice<T>(input: &[u8]) -> Result<T, DeserializeError>
where
    T: facet_core::Facet<'static>,
{
    use facet_format::FormatDeserializer;
    let mut parser = XdrParser::new(input);
    let mut de = FormatDeserializer::new_owned(&mut parser);
    de.deserialize()
}

/// Deserialize a value from XDR bytes, allowing zero-copy borrowing.
///
/// This variant requires the input to outlive the result (`'input: 'facet`),
/// enabling zero-copy deserialization of byte slices as `&[u8]` or `Cow<[u8]>`.
///
/// # Example
///
/// ```
/// use facet::Facet;
/// use facet_xdr::from_slice_borrowed;
/// use std::borrow::Cow;
///
/// #[derive(Facet, Debug, PartialEq)]
/// struct Message<'a> {
///     id: u32,
///     #[facet(sensitive)]
///     data: Cow<'a, [u8]>,
/// }
///
/// // XDR encoding of Message { id: 1, data: [0xAB, 0xCD, 0xEF] }
/// // id (4 bytes) + data length (4 bytes) + data (3 bytes) + padding (1 byte)
/// let bytes = &[0, 0, 0, 1, 0, 0, 0, 3, 0xAB, 0xCD, 0xEF, 0];
/// let msg: Message = from_slice_borrowed(bytes).unwrap();
/// assert_eq!(msg.id, 1);
/// assert_eq!(&*msg.data, &[0xAB, 0xCD, 0xEF]);
/// ```
pub fn from_slice_borrowed<'input, 'facet, T>(input: &'input [u8]) -> Result<T, DeserializeError>
where
    T: facet_core::Facet<'facet>,
    'input: 'facet,
{
    use facet_format::FormatDeserializer;
    let mut parser = XdrParser::new(input);
    let mut de = FormatDeserializer::new(&mut parser);
    de.deserialize()
}