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}