facet_postcard/
lib.rs

1//! Postcard binary format for facet.
2//!
3//! This crate provides serialization and deserialization for the postcard binary format.
4//!
5//! # Serialization
6//!
7//! Serialization supports all types that implement [`facet_core::Facet`]:
8//!
9//! ```
10//! use facet::Facet;
11//! use facet_postcard::to_vec;
12//!
13//! #[derive(Facet)]
14//! struct Point { x: i32, y: i32 }
15//!
16//! let point = Point { x: 10, y: 20 };
17//! let bytes = to_vec(&point).unwrap();
18//! ```
19//!
20//! # Deserialization
21//!
22//! There are two deserialization functions:
23//!
24//! - [`from_slice`]: Deserializes into owned types (`T: Facet<'static>`)
25//! - [`from_slice_borrowed`]: Deserializes with zero-copy borrowing from the input buffer
26//!
27//! ```
28//! use facet_postcard::from_slice;
29//!
30//! // Postcard encoding: [length=3, true, false, true]
31//! let bytes = &[0x03, 0x01, 0x00, 0x01];
32//! let result: Vec<bool> = from_slice(bytes).unwrap();
33//! assert_eq!(result, vec![true, false, true]);
34//! ```
35//!
36//! Both functions automatically select the best deserialization tier:
37//! - **Tier-2 (Format JIT)**: Fastest path for compatible types (primitives, structs, vecs, simple enums)
38//! - **Tier-0 (Reflection)**: Fallback for all other types (nested enums, complex types)
39//!
40//! This ensures all `Facet` types can be deserialized.
41
42#![cfg_attr(not(feature = "jit"), forbid(unsafe_code))]
43
44extern crate alloc;
45
46mod error;
47mod parser;
48mod serialize;
49
50#[cfg(feature = "jit")]
51pub mod jit;
52
53#[cfg(feature = "axum")]
54mod axum;
55
56#[cfg(feature = "axum")]
57pub use axum::{Postcard, PostcardRejection, PostcardSerializeRejection};
58pub use error::{PostcardError, SerializeError};
59#[cfg(feature = "jit")]
60pub use jit::PostcardJitFormat;
61pub use parser::PostcardParser;
62pub use serialize::{Writer, peek_to_vec, to_vec, to_writer_fallible};
63
64// Re-export DeserializeError for convenience
65pub use facet_format::DeserializeError;
66
67/// Deserialize a value from postcard bytes into an owned type.
68///
69/// This is the recommended default for most use cases. The input does not need
70/// to outlive the result, making it suitable for deserializing from temporary
71/// buffers (e.g., HTTP request bodies).
72///
73/// Types containing `&str` or `&[u8]` fields cannot be deserialized with this
74/// function; use `String`/`Vec<u8>` or `Cow<str>`/`Cow<[u8]>` instead. For
75/// zero-copy deserialization into borrowed types, use [`from_slice_borrowed`].
76///
77/// # Example
78///
79/// ```
80/// use facet::Facet;
81/// use facet_postcard::from_slice;
82///
83/// #[derive(Facet, Debug, PartialEq)]
84/// struct Point {
85///     x: i32,
86///     y: i32,
87/// }
88///
89/// // Postcard encoding: [x=10 (zigzag), y=20 (zigzag)]
90/// let bytes = &[0x14, 0x28];
91/// let point: Point = from_slice(bytes).unwrap();
92/// assert_eq!(point.x, 10);
93/// assert_eq!(point.y, 20);
94/// ```
95pub fn from_slice<T>(input: &[u8]) -> Result<T, DeserializeError<PostcardError>>
96where
97    T: facet_core::Facet<'static>,
98{
99    use facet_format::FormatDeserializer;
100    let parser = PostcardParser::new(input);
101    let mut de = FormatDeserializer::new_owned(parser);
102    de.deserialize()
103}
104
105/// Deserialize a value from postcard bytes, allowing zero-copy borrowing.
106///
107/// This variant requires the input to outlive the result (`'input: 'facet`),
108/// enabling zero-copy deserialization of byte slices as `&[u8]` or `Cow<[u8]>`.
109///
110/// Use this when you need maximum performance and can guarantee the input
111/// buffer outlives the deserialized value. For most use cases, prefer
112/// [`from_slice`] which doesn't have lifetime requirements.
113///
114/// # Example
115///
116/// ```
117/// use facet::Facet;
118/// use facet_postcard::from_slice_borrowed;
119///
120/// #[derive(Facet, Debug, PartialEq)]
121/// struct Message<'a> {
122///     id: u32,
123///     data: &'a [u8],
124/// }
125///
126/// // Postcard encoding: [id=1, data_len=3, 0xAB, 0xCD, 0xEF]
127/// let bytes = &[0x01, 0x03, 0xAB, 0xCD, 0xEF];
128/// let msg: Message = from_slice_borrowed(bytes).unwrap();
129/// assert_eq!(msg.id, 1);
130/// assert_eq!(msg.data, &[0xAB, 0xCD, 0xEF]);
131/// ```
132pub fn from_slice_borrowed<'input, 'facet, T>(
133    input: &'input [u8],
134) -> Result<T, DeserializeError<PostcardError>>
135where
136    T: facet_core::Facet<'facet>,
137    'input: 'facet,
138{
139    use facet_format::FormatDeserializer;
140    let parser = PostcardParser::new(input);
141    let mut de = FormatDeserializer::new(parser);
142    de.deserialize()
143}
facet_postcard/lib.rs

facet_postcard/
lib.rs
