ic_wire/bounded/
mod.rs

1use crate::{Error, Shape, Wire};
2use alloc::{string::String, vec::Vec};
3use core::fmt;
4use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
5
6/// A sequence with a compile-time element bound.
7#[derive(Clone, Debug, Eq, PartialEq)]
8pub struct List<T, const N: usize>(Vec<T>);
9impl<T, const N: usize> List<T, N> {
10    /// Admit an owned sequence without copying.
11    pub fn new(values: Vec<T>) -> Result<Self, Error> {
12        if values.len() > N {
13            Err(Error::Limit)
14        } else {
15            Ok(Self(values))
16        }
17    }
18    /// Borrow the elements.
19    pub fn as_slice(&self) -> &[T] {
20        &self.0
21    }
22    /// Recover the admitted sequence.
23    pub fn into_vec(self) -> Vec<T> {
24        self.0
25    }
26}
27impl<T: Serialize, const N: usize> Serialize for List<T, N> {
28    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
29        self.0.serialize(s)
30    }
31}
32impl<'de, T: Deserialize<'de>, const N: usize> Deserialize<'de> for List<T, N> {
33    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
34        struct Visitor<T, const N: usize>(core::marker::PhantomData<T>);
35        impl<'de, T: Deserialize<'de>, const N: usize> de::Visitor<'de> for Visitor<T, N> {
36            type Value = List<T, N>;
37            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
38                f.write_str("bounded sequence")
39            }
40            fn visit_seq<A: de::SeqAccess<'de>>(self, mut seq: A) -> Result<Self::Value, A::Error> {
41                // Postcard hides its count when remaining bytes are fewer than
42                // elements (including legitimate unit values). Bound both paths.
43                let count = seq.size_hint();
44                if count.is_some_and(|count| count > N) {
45                    return Err(de::Error::custom("element limit"));
46                }
47                let mut values = Vec::new();
48                values
49                    .try_reserve_exact(count.unwrap_or(0))
50                    .map_err(|_| de::Error::custom("allocation"))?;
51                for _ in 0..N {
52                    let Some(value) = seq.next_element()? else {
53                        return Ok(List(values));
54                    };
55                    if values.len() == values.capacity() {
56                        values
57                            .try_reserve_exact(1)
58                            .map_err(|_| de::Error::custom("allocation"))?;
59                    }
60                    values.push(value);
61                }
62                // Detect an excess element without invoking its decoder.
63                struct Reject;
64                impl<'de> de::DeserializeSeed<'de> for Reject {
65                    type Value = ();
66                    fn deserialize<D: Deserializer<'de>>(self, _: D) -> Result<(), D::Error> {
67                        Err(de::Error::custom("element limit"))
68                    }
69                }
70                seq.next_element_seed(Reject)?;
71                Ok(List(values))
72            }
73        }
74        d.deserialize_seq(Visitor::<T, N>(core::marker::PhantomData))
75    }
76}
77impl<T: Wire, const N: usize> Wire for List<T, N> {
78    const SCHEMA: crate::schema::Schema = crate::schema::Schema::List(&T::SCHEMA, N);
79    const SHAPE: Shape = Shape {
80        bytes: 10_usize.saturating_add(T::SHAPE.bytes.saturating_mul(N)),
81        heap: N.saturating_mul(core::mem::size_of::<T>().saturating_add(T::SHAPE.heap)),
82        nodes: 1_usize.saturating_add(N.saturating_mul(T::SHAPE.nodes)),
83        depth: T::SHAPE.depth.saturating_add(1),
84    };
85}
86
87/// Bounded opaque bytes; consumers validate principal bytes using their existing
88/// principal type. IC Wire defines no new identity type.
89#[derive(Clone, Debug, Eq, PartialEq)]
90pub struct Bytes<const N: usize>(Vec<u8>);
91impl<const N: usize> Bytes<N> {
92    /// Admit bytes without copying.
93    pub fn new(bytes: Vec<u8>) -> Result<Self, Error> {
94        if bytes.len() > N {
95            Err(Error::Limit)
96        } else {
97            Ok(Self(bytes))
98        }
99    }
100    /// Borrow the bytes.
101    pub fn as_slice(&self) -> &[u8] {
102        &self.0
103    }
104}
105impl<const N: usize> Serialize for Bytes<N> {
106    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
107        s.serialize_bytes(&self.0)
108    }
109}
110impl<'de, const N: usize> Deserialize<'de> for Bytes<N> {
111    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
112        struct Visitor<const N: usize>;
113        impl<const N: usize> de::Visitor<'_> for Visitor<N> {
114            type Value = Bytes<N>;
115            fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
116                f.write_str("bounded bytes")
117            }
118            fn visit_bytes<E: de::Error>(self, bytes: &[u8]) -> Result<Self::Value, E> {
119                if bytes.len() > N {
120                    return Err(E::custom("byte limit"));
121                }
122                let mut out = Vec::new();
123                out.try_reserve_exact(bytes.len())
124                    .map_err(|_| E::custom("allocation"))?;
125                out.extend_from_slice(bytes);
126                Ok(Bytes(out))
127            }
128        }
129        d.deserialize_bytes(Visitor::<N>)
130    }
131}
132impl<const N: usize> Wire for Bytes<N> {
133    const SCHEMA: crate::schema::Schema = crate::schema::Schema::Bytes(N);
134    const SHAPE: Shape = Shape {
135        bytes: N.saturating_add(10),
136        heap: N,
137        nodes: 1,
138        depth: 1,
139    };
140}
141
142/// UTF-8 text bounded in bytes.
143#[derive(Clone, Debug, Eq, PartialEq)]
144pub struct Text<const N: usize>(String);
145impl<const N: usize> Text<N> {
146    /// Admit owned text without copying.
147    pub fn new(text: String) -> Result<Self, Error> {
148        if text.len() > N {
149            Err(Error::Limit)
150        } else {
151            Ok(Self(text))
152        }
153    }
154    /// Borrow the text.
155    pub fn as_str(&self) -> &str {
156        &self.0
157    }
158}
159impl<const N: usize> Serialize for Text<N> {
160    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
161        s.serialize_str(&self.0)
162    }
163}
164impl<'de, const N: usize> Deserialize<'de> for Text<N> {
165    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
166        let bytes = Bytes::<N>::deserialize(d)?;
167        let text = String::from_utf8(bytes.0).map_err(|_| de::Error::custom("invalid UTF-8"))?;
168        Ok(Self(text))
169    }
170}
171impl<const N: usize> Wire for Text<N> {
172    const SCHEMA: crate::schema::Schema = crate::schema::Schema::Text(N);
173    const SHAPE: Shape = Bytes::<N>::SHAPE;
174}
ic_wire/bounded/mod.rs

ic_wire/bounded/
mod.rs
