Skip to main content

ic_wire/serde_packed/
mod.rs

1//! Explicit bulk field adapters within the single Serde/Postcard codec.
2//!
3//! Select using `#[serde(with = "ic_wire::serde_packed::bools")]` (or another
4//! adapter below). Ordinary fields are never rewritten. Adoption changes traversal
5//! accounting and, except for bools, ordinary-list bytes. Preserve field bounds,
6//! coordinate clients and retain original retry/hash bytes. Reference contracts
7//! and qualification are recorded in docs/design/parity.md.
8
9#[cfg(test)]
10mod tests;
11
12/// Checked boolean bytes, projected as a browser boolean array.
13pub mod bools {
14    use alloc::vec::Vec;
15    use serde::{Deserializer, Serializer, de};
16    /// Borrow boolean storage as bytes; only 0/1 patterns can occur.
17    /// # Errors
18    /// Propagates serializer refusal.
19    pub fn serialize<S: Serializer>(values: &[bool], serializer: S) -> Result<S::Ok, S::Error> {
20        serializer.serialize_bytes(bytemuck::must_cast_slice(values))
21    }
22
23    /// Validate every byte before reserving owned output.
24    /// # Errors
25    /// Rejects invalid boolean patterns and propagates admission/allocation errors.
26    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Vec<bool>, D::Error> {
27        struct Visitor;
28        impl de::Visitor<'_> for Visitor {
29            type Value = Vec<bool>;
30            fn expecting(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
31                f.write_str("boolean bytes")
32            }
33
34            fn visit_bytes<E: de::Error>(self, bytes: &[u8]) -> Result<Self::Value, E> {
35                let words: &[bool] = bytemuck::checked::try_cast_slice(bytes)
36                    .map_err(|_| E::custom("invalid boolean byte"))?;
37                let mut output = Vec::new();
38                output
39                    .try_reserve_exact(words.len())
40                    .map_err(|_| E::custom("allocation"))?;
41                output.extend_from_slice(words);
42                Ok(output)
43            }
44        }
45        deserializer.deserialize_bytes(Visitor)
46    }
47}
48
49/// Packed signed words retaining the nonzero domain rule.
50pub mod nonzero_i64 {
51    use alloc::vec::Vec;
52    use core::num::NonZeroI64;
53    use serde::{Deserialize, Deserializer, Serializer};
54    /// Encode borrowed nonzero storage without a temporary integer vector.
55    /// # Errors
56    /// Propagates serializer refusal.
57    pub fn serialize<S: Serializer>(
58        values: &[NonZeroI64],
59        serializer: S,
60    ) -> Result<S::Ok, S::Error> {
61        crate::packed::serialize_words::<i64, S>(bytemuck::must_cast_slice(values), serializer)
62    }
63
64    /// Decode packed words and enforce nonzero values.
65    /// # Errors
66    /// Rejects zero and propagates packed decoding failures. Validation follows
67    /// owned word decoding; it is not a pre-allocation validation guarantee.
68    pub fn deserialize<'de, D: Deserializer<'de>>(
69        deserializer: D,
70    ) -> Result<Vec<NonZeroI64>, D::Error> {
71        crate::Packed::<i64>::deserialize(deserializer)?
72            .into_vec()
73            .into_iter()
74            .map(NonZeroI64::new)
75            .collect::<Option<Vec<_>>>()
76            .ok_or_else(|| serde::de::Error::custom("zero in nonzero list"))
77    }
78}
79
80/// Packed heap backing order; decoding reconstructs the heap.
81/// Re-encoding may reorder accepted input. Retain original signed/retry bytes.
82pub mod heap_u64 {
83    use alloc::collections::BinaryHeap;
84    use serde::{Deserialize, Deserializer, Serializer};
85    /// Encode the existing backing slice without copying.
86    /// # Errors
87    /// Propagates serializer refusal.
88    pub fn serialize<S: Serializer>(
89        values: &BinaryHeap<u64>,
90        serializer: S,
91    ) -> Result<S::Ok, S::Error> {
92        crate::packed::serialize_words(values.as_slice(), serializer)
93    }
94
95    /// Rebuild a heap from owned packed words, accepting duplicates and any order.
96    /// # Errors
97    /// Propagates packed decoding failures.
98    pub fn deserialize<'de, D: Deserializer<'de>>(
99        deserializer: D,
100    ) -> Result<BinaryHeap<u64>, D::Error> {
101        Ok(BinaryHeap::from(
102            crate::Packed::<u64>::deserialize(deserializer)?.into_vec(),
103        ))
104    }
105}
106
107// A shared source pattern for two domain adapters. No consumer-specific codec
108// generation or inherited unrolled/scanner optimization without new measurements.
109macro_rules! finite {
110    ($module:ident,$float:ty,$width:literal) => {
111        /// Finite little-endian float byte fields. Preserves signed zero and subnormals.
112        pub mod $module {
113            use alloc::vec::Vec;
114            use serde::{Deserializer, Serializer, de};
115            fn valid(bytes: &[u8]) -> bool {
116                if !bytes.len().is_multiple_of($width) {
117                    return false;
118                }
119                let mut tail = bytes;
120                if $width == 4 {
121                    // Independent f32 exponent lanes: adding one exponent unit
122                    // reaches each sign bit exactly for exponent 0xff. Masking
123                    // first prevents mantissa/sign bits and cross-lane carries.
124                    let mut pairs = bytes.chunks_exact(8);
125                    if !pairs.by_ref().all(|pair| {
126                        let bits = u64::from_le_bytes(pair.try_into().unwrap());
127                        ((bits & 0x7f80_0000_7f80_0000) + 0x0080_0000_0080_0000)
128                            & 0x8000_0000_8000_0000
129                            == 0
130                    }) {
131                        return false;
132                    }
133                    tail = pairs.remainder();
134                }
135                tail.chunks_exact($width).all(|word| {
136                    <$float>::from_le_bytes(word.try_into().expect("whole float word")).is_finite()
137                })
138            }
139
140            /// Encode finite values as one byte buffer without narrowing finite bits.
141            /// # Errors
142            /// Rejects NaN/infinity and propagates serializer/allocation failures.
143            pub fn serialize<S: Serializer>(
144                values: &[$float],
145                serializer: S,
146            ) -> Result<S::Ok, S::Error> {
147                if cfg!(target_endian = "little") {
148                    let bytes = bytemuck::must_cast_slice(values);
149                    if !valid(bytes) {
150                        return Err(serde::ser::Error::custom("non-finite float"));
151                    }
152                    serializer.serialize_bytes(bytes)
153                } else {
154                    serializer.serialize_bytes(&little_endian::<S::Error>(values)?)
155                }
156            }
157
158            pub(super) fn little_endian<E: serde::ser::Error>(
159                values: &[$float],
160            ) -> Result<Vec<u8>, E> {
161                if values.iter().any(|value| !value.is_finite()) {
162                    return Err(E::custom("non-finite float"));
163                }
164                let length = values
165                    .len()
166                    .checked_mul($width)
167                    .ok_or_else(|| E::custom("length overflow"))?;
168                let mut bytes = Vec::new();
169                bytes
170                    .try_reserve_exact(length)
171                    .map_err(|_| E::custom("allocation"))?;
172                for value in values {
173                    bytes.extend_from_slice(&value.to_le_bytes());
174                }
175                Ok(bytes)
176            }
177
178            /// Reject partial/nonfinite words before allocating owned float storage.
179            /// # Errors
180            /// Rejects invalid spans and propagates admission/allocation failures.
181            pub fn deserialize<'de, D: Deserializer<'de>>(
182                deserializer: D,
183            ) -> Result<Vec<$float>, D::Error> {
184                struct Visitor;
185                impl de::Visitor<'_> for Visitor {
186                    type Value = Vec<$float>;
187                    fn expecting(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
188                        f.write_str("finite little-endian float bytes")
189                    }
190
191                    fn visit_bytes<E: de::Error>(self, bytes: &[u8]) -> Result<Self::Value, E> {
192                        if !valid(bytes) {
193                            return Err(E::custom("invalid finite float bytes"));
194                        }
195                        let mut values = Vec::new();
196                        values
197                            .try_reserve_exact(bytes.len() / $width)
198                            .map_err(|_| E::custom("allocation"))?;
199                        values.extend(bytes.chunks_exact($width).map(|word| {
200                            <$float>::from_le_bytes(
201                                word.try_into().expect("validated whole float word"),
202                            )
203                        }));
204                        Ok(values)
205                    }
206                }
207                deserializer.deserialize_bytes(Visitor)
208            }
209        }
210    };
211}
212finite!(finite_f32, f32, 4);
213finite!(finite_f64, f64, 8);