Skip to main content

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}