ic_wire/decode/mod.rs
1//! One bounded Postcard decoding path for payloads and frames.
2
3mod admitted;
4#[cfg(test)]
5mod tests;
6
7use crate::{Encoding, Error, Limits, framing::validate_header, meter::Budget};
8use serde::Deserialize;
9
10/// Decode exactly one payload or frame under explicit traversal allowances.
11///
12/// Borrowed results may reference the original input. Postcard owns primitive
13/// acceptance; this does not enforce canonical bytes or reserialize results.
14/// Consumer collections and custom Serde may normalize values. Retain original
15/// bytes for signatures, hashes and retries. Custom Serde work outside admitted
16/// visits is trusted; a valid prefix can allocate before a later failure.
17///
18/// # Errors
19///
20/// Oversized input returns [`Error::Limit`] before header checks. Short frames
21/// return [`Error::Malformed`], then header mismatches return [`Error::Identity`].
22/// During payload decoding exhausted allowances return [`Error::Limit`], other
23/// deserialization failures return [`Error::Malformed`]. A successful value
24/// followed by unused input returns [`Error::Trailing`].
25pub fn decode<'de, T: Deserialize<'de>>(
26 input: &'de [u8],
27 encoding: Encoding,
28 mut limits: Limits,
29) -> Result<T, Error> {
30 if input.len() > limits.bytes {
31 return Err(Error::Limit);
32 }
33 let payload = match encoding {
34 Encoding::Payload => input,
35 Encoding::Frame { method, direction } => {
36 let (header, payload) = input.split_first_chunk::<11>().ok_or(Error::Malformed)?;
37 validate_header(method, direction, header)?;
38 limits = limits.without_prefix(11)?;
39 payload
40 }
41 };
42 let budget = Budget::new(limits);
43 let mut deserializer = postcard::Deserializer::from_bytes(payload);
44 let value = T::deserialize(admitted::Bounded {
45 inner: &mut deserializer,
46 budget: &budget,
47 depth: 1,
48 })
49 .map_err(|_| budget.error())?;
50 if !deserializer
51 .finalize()
52 .map_err(|_| Error::Malformed)?
53 .is_empty()
54 {
55 return Err(Error::Trailing);
56 }
57 Ok(value)
58}