Skip to main content

ic_wire/packed/
mod.rs

1//! Explicit fixed-width little-endian packed fields with optional element bounds.
2// Contract and minimal algorithm adapted from pinned IC Wire; see docs/design/packed.md.
3
4use crate::Error;
5use alloc::vec::Vec;
6use core::fmt;
7use core::marker::PhantomData;
8use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
9
10#[cfg(test)]
11mod tests;
12
13/// Qualified fixed-width packed words. Sealed; arbitrary-bit casts never admit
14/// booleans, nonzero integers or floating-point domain values.
15pub trait PackedElement: word::Word {}
16mod word {
17    // Readers receive exact-width chunks after visitor admission. Keep the
18    // checked conversion simple: a custom expect message retains a per-word
19    // Result::expect call under opt-z (see the codec benchmark investigation).
20    pub trait Word: bytemuck::Pod + core::fmt::Debug + Eq {
21        const SCHEMA: &'static str;
22        fn read(bytes: &[u8]) -> Self;
23        #[cfg(any(target_endian = "big", test))]
24        fn append(self, bytes: &mut alloc::vec::Vec<u8>);
25    }
26    macro_rules! integer {
27        ($($ty:ty),+) => {$(
28            impl super::PackedElement for $ty {}
29            impl Word for $ty {
30                const SCHEMA: &'static str = stringify!($ty);
31                fn read(bytes: &[u8]) -> Self { Self::from_le_bytes(bytes.try_into().unwrap()) }
32                #[cfg(any(target_endian = "big", test))]
33                fn append(self, bytes: &mut alloc::vec::Vec<u8>) { bytes.extend_from_slice(&self.to_le_bytes()); }
34            }
35        )+};
36    }
37    integer!(i8, i16, u16, i32, u32, i64, u64);
38    macro_rules! opaque {
39        ($n:literal,$schema:literal) => {
40            impl super::PackedElement for [u8; $n] {}
41            impl Word for [u8; $n] {
42                const SCHEMA: &'static str = $schema;
43                fn read(bytes: &[u8]) -> Self {
44                    bytes.try_into().unwrap()
45                }
46                #[cfg(any(target_endian = "big", test))]
47                fn append(self, bytes: &mut alloc::vec::Vec<u8>) {
48                    bytes.extend_from_slice(&self);
49                }
50            }
51        };
52    }
53    opaque!(16, "hash16");
54    opaque!(32, "hash32");
55}
56
57/// Explicit fixed-width little-endian byte buffer. Prefix counts bytes, not
58/// elements. Ordinary vectors retain their original Serde representation.
59/// N limits the number of words; the default is unbounded apart from codec limits.
60///
61/// ```compile_fail
62/// let value = ic_wire::Packed::<f32>::new(vec![1.0_f32]).unwrap();
63/// fn serializable(_: impl serde::Serialize) {}
64/// serializable(value);
65/// ```
66#[derive(Clone, Debug, Eq, PartialEq)]
67pub struct Packed<T, const N: usize = { usize::MAX }>(Vec<T>);
68impl<T, const N: usize> Packed<T, N> {
69    /// Admit owned words without copying; codec limits also apply on traversal.
70    /// # Errors
71    /// Returns [`Error::Limit`] when the element count exceeds N.
72    pub fn new(words: Vec<T>) -> Result<Self, Error> {
73        if words.len() > N {
74            Err(Error::Limit)
75        } else {
76            Ok(Self(words))
77        }
78    }
79    /// Borrow the words.
80    #[must_use]
81    pub fn as_slice(&self) -> &[T] {
82        &self.0
83    }
84    /// Recover storage without copying.
85    #[must_use]
86    pub fn into_vec(self) -> Vec<T> {
87        self.0
88    }
89}
90impl<T: PackedElement, const N: usize> Serialize for Packed<T, N> {
91    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
92        serialize_words(&self.0, serializer)
93    }
94}
95impl<'de, T: PackedElement, const N: usize> Deserialize<'de> for Packed<T, N> {
96    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
97        deserializer
98            .deserialize_bytes(PackedVisitor::<T> {
99                limit: N,
100                marker: PhantomData,
101            })
102            .map(Self)
103    }
104}
105
106pub(crate) fn serialize_words<T: PackedElement, S: Serializer>(
107    words: &[T],
108    serializer: S,
109) -> Result<S::Ok, S::Error> {
110    #[cfg(target_endian = "little")]
111    {
112        serializer.serialize_bytes(bytemuck::must_cast_slice(words))
113    }
114    #[cfg(target_endian = "big")]
115    {
116        let bytes = little_endian_bytes::<T, S::Error>(words)?;
117        serializer.serialize_bytes(&bytes)
118    }
119}
120
121// Compiled in native tests as well as on big-endian targets, so conversion is
122// exercised without claiming a native big-endian execution result.
123#[cfg(any(target_endian = "big", test))]
124fn little_endian_bytes<T: PackedElement, E: serde::ser::Error>(words: &[T]) -> Result<Vec<u8>, E> {
125    let length = words
126        .len()
127        .checked_mul(size_of::<T>())
128        .ok_or_else(|| E::custom("length overflow"))?;
129    let mut bytes = Vec::new();
130    bytes
131        .try_reserve_exact(length)
132        .map_err(|_| E::custom("allocation"))?;
133    for word in words {
134        word.append(&mut bytes);
135    }
136    Ok(bytes)
137}
138
139// Returning Vec keeps traversal accounting independent of the wrapper. The runtime
140// bound keeps one allocation/copy body rather than duplicating it per N.
141struct PackedVisitor<T> {
142    limit: usize,
143    marker: PhantomData<T>,
144}
145
146impl<T: PackedElement> de::Visitor<'_> for PackedVisitor<T> {
147    type Value = Vec<T>;
148
149    fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
150        formatter.write_str("packed little-endian words")
151    }
152
153    fn visit_bytes<E: de::Error>(self, bytes: &[u8]) -> Result<Self::Value, E> {
154        let width = size_of::<T>();
155        if !bytes.len().is_multiple_of(width) || bytes.len() / width > self.limit {
156            return Err(E::custom("invalid packed length"));
157        }
158        let mut values = Vec::new();
159        values
160            .try_reserve_exact(bytes.len() / width)
161            .map_err(|_| E::custom("allocation"))?;
162        values.extend(bytes.chunks_exact(width).map(T::read));
163        Ok(values)
164    }
165}