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