miden_serde_utils/
lib.rs

1// Copyright (c) Facebook, Inc. and its affiliates.
2//
3// This source code is licensed under the MIT license found in the
4// LICENSE file in the root directory of this source tree.
5
6#![cfg_attr(not(feature = "std"), no_std)]
7
8extern crate alloc;
9
10use alloc::{
11    collections::{BTreeMap, BTreeSet, VecDeque},
12    format,
13    string::String,
14    sync::Arc,
15    vec::Vec,
16};
17use core::mem::size_of;
18
19/// Deserializes a wincode schema and rejects trailing bytes.
20///
21/// Unlike `wincode::config::deserialize_exact`, this accepts schema adapters whose decoded type
22/// differs from the schema type.
23pub fn deserialize_schema_exact<'de, T, C>(
24    mut bytes: &'de [u8],
25    _config: C,
26) -> wincode::ReadResult<T::Dst>
27where
28    T: wincode::SchemaRead<'de, C>,
29    C: wincode::config::Config,
30{
31    use wincode::io::Reader as _;
32
33    let value = T::get(bytes.by_ref())?;
34    if bytes.is_empty() {
35        Ok(value)
36    } else {
37        Err(wincode::error::trailing_bytes())
38    }
39}
40
41#[cfg(test)]
42mod wincode_tests {
43    use serde_wincode::SerdeCompat;
44
45    use super::deserialize_schema_exact;
46
47    #[test]
48    fn exact_deserialization_rejects_trailing_bytes() {
49        let config = wincode::config::Configuration::default();
50        let mut bytes =
51            <SerdeCompat<u8> as wincode::config::Serialize<_>>::serialize(&7, config).unwrap();
52
53        assert_eq!(deserialize_schema_exact::<SerdeCompat<u8>, _>(&bytes, config).unwrap(), 7);
54
55        bytes.push(0);
56        assert!(matches!(
57            deserialize_schema_exact::<SerdeCompat<u8>, _>(&bytes, config),
58            Err(wincode::error::ReadError::TrailingBytes)
59        ));
60    }
61}
62
63// ERROR
64// ================================================================================================
65
66/// Defines errors which can occur during deserialization.
67#[derive(Clone, Debug, PartialEq, Eq)]
68pub enum DeserializationError {
69    /// Indicates that the deserialization failed because of insufficient data.
70    UnexpectedEOF,
71    /// Indicates that the deserialization failed because the value was not valid.
72    InvalidValue(String),
73    /// Indicates that deserialization failed for an unknown reason.
74    UnknownError(String),
75}
76
77impl core::error::Error for DeserializationError {}
78
79impl core::fmt::Display for DeserializationError {
80    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
81        match self {
82            Self::UnexpectedEOF => write!(f, "unexpected end of file"),
83            Self::InvalidValue(msg) => write!(f, "invalid value: {msg}"),
84            Self::UnknownError(msg) => write!(f, "unknown error: {msg}"),
85        }
86    }
87}
88
89mod byte_reader;
90#[cfg(feature = "std")]
91pub use byte_reader::ReadAdapter;
92pub use byte_reader::{BudgetedReader, ByteReader, ReadManyIter, SliceReader};
93
94mod byte_writer;
95pub use byte_writer::ByteWriter;
96
97#[cfg(feature = "std")]
98mod file;
99#[cfg(feature = "std")]
100pub use file::read_file_bounded;
101
102// BOUNDED LENGTH HELPERS
103// ================================================================================================
104
105/// Reads and validates a serialized length before it is used for allocation.
106///
107/// `label` names the collection being read and is only used to build the error message.
108/// `min_element_size` is the minimum number of bytes one element occupies once serialized.
109///
110/// # Errors
111/// Returns an error if the length cannot be read, or if it fails the checks described in
112/// [`validate_bounded_len`].
113pub fn read_bounded_len<R: ByteReader>(
114    source: &mut R,
115    label: &str,
116    min_element_size: usize,
117) -> Result<usize, DeserializationError> {
118    let len = source.read_usize()?;
119    validate_bounded_len(source, label, len, min_element_size)?;
120    Ok(len)
121}
122
123/// Validates that a serialized length fits both the reader budget and remaining input.
124///
125/// This guards against malicious length prefixes that would otherwise cause a compact payload
126/// to be amplified into a large allocation.
127///
128/// # Errors
129/// Returns [`DeserializationError::InvalidValue`] if:
130/// * `len` exceeds the number of elements the reader's remaining budget allows.
131/// * `len * min_element_size` overflows.
132/// * The source does not hold `len * min_element_size` more bytes.
133pub fn validate_bounded_len<R: ByteReader>(
134    source: &R,
135    label: &str,
136    len: usize,
137    min_element_size: usize,
138) -> Result<(), DeserializationError> {
139    let max_len = source.max_alloc(min_element_size);
140    if len > max_len {
141        return Err(DeserializationError::InvalidValue(format!(
142            "{label} count {len} exceeds budget {max_len}"
143        )));
144    }
145
146    let min_bytes = len.checked_mul(min_element_size).ok_or_else(|| {
147        DeserializationError::InvalidValue(format!(
148            "{label} count {len} overflows minimum serialized size {min_element_size}"
149        ))
150    })?;
151    source.check_eor(min_bytes).map_err(|err| match err {
152        DeserializationError::UnexpectedEOF => DeserializationError::InvalidValue(format!(
153            "{label} count {len} exceeds remaining input"
154        )),
155        err => err,
156    })
157}
158
159// SERIALIZABLE TRAIT
160// ================================================================================================
161
162/// Defines how to serialize `Self` into bytes.
163pub trait Serializable {
164    // REQUIRED METHODS
165    // --------------------------------------------------------------------------------------------
166    /// Serializes `self` into bytes and writes these bytes into the `target`.
167    fn write_into<W: ByteWriter>(&self, target: &mut W);
168
169    // PROVIDED METHODS
170    // --------------------------------------------------------------------------------------------
171
172    /// Serializes `self` into a vector of bytes.
173    fn to_bytes(&self) -> Vec<u8> {
174        let mut result = Vec::with_capacity(self.get_size_hint());
175        self.write_into(&mut result);
176        result
177    }
178
179    /// Returns an estimate of how many bytes are needed to represent self.
180    ///
181    /// The default implementation returns zero.
182    fn get_size_hint(&self) -> usize {
183        0
184    }
185}
186
187impl<T: Serializable> Serializable for &T {
188    fn write_into<W: ByteWriter>(&self, target: &mut W) {
189        (*self).write_into(target)
190    }
191
192    fn get_size_hint(&self) -> usize {
193        (*self).get_size_hint()
194    }
195}
196
197impl Serializable for () {
198    fn write_into<W: ByteWriter>(&self, _target: &mut W) {}
199
200    fn get_size_hint(&self) -> usize {
201        0
202    }
203}
204
205impl<T1> Serializable for (T1,)
206where
207    T1: Serializable,
208{
209    fn write_into<W: ByteWriter>(&self, target: &mut W) {
210        self.0.write_into(target);
211    }
212
213    fn get_size_hint(&self) -> usize {
214        self.0.get_size_hint()
215    }
216}
217
218impl<T1, T2> Serializable for (T1, T2)
219where
220    T1: Serializable,
221    T2: Serializable,
222{
223    fn write_into<W: ByteWriter>(&self, target: &mut W) {
224        self.0.write_into(target);
225        self.1.write_into(target);
226    }
227
228    fn get_size_hint(&self) -> usize {
229        self.0.get_size_hint() + self.1.get_size_hint()
230    }
231}
232
233impl<T1, T2, T3> Serializable for (T1, T2, T3)
234where
235    T1: Serializable,
236    T2: Serializable,
237    T3: Serializable,
238{
239    fn write_into<W: ByteWriter>(&self, target: &mut W) {
240        self.0.write_into(target);
241        self.1.write_into(target);
242        self.2.write_into(target);
243    }
244
245    fn get_size_hint(&self) -> usize {
246        self.0.get_size_hint() + self.1.get_size_hint() + self.2.get_size_hint()
247    }
248}
249
250impl<T1, T2, T3, T4> Serializable for (T1, T2, T3, T4)
251where
252    T1: Serializable,
253    T2: Serializable,
254    T3: Serializable,
255    T4: Serializable,
256{
257    fn write_into<W: ByteWriter>(&self, target: &mut W) {
258        self.0.write_into(target);
259        self.1.write_into(target);
260        self.2.write_into(target);
261        self.3.write_into(target);
262    }
263
264    fn get_size_hint(&self) -> usize {
265        self.0.get_size_hint()
266            + self.1.get_size_hint()
267            + self.2.get_size_hint()
268            + self.3.get_size_hint()
269    }
270}
271
272impl<T1, T2, T3, T4, T5> Serializable for (T1, T2, T3, T4, T5)
273where
274    T1: Serializable,
275    T2: Serializable,
276    T3: Serializable,
277    T4: Serializable,
278    T5: Serializable,
279{
280    fn write_into<W: ByteWriter>(&self, target: &mut W) {
281        self.0.write_into(target);
282        self.1.write_into(target);
283        self.2.write_into(target);
284        self.3.write_into(target);
285        self.4.write_into(target);
286    }
287
288    fn get_size_hint(&self) -> usize {
289        self.0.get_size_hint()
290            + self.1.get_size_hint()
291            + self.2.get_size_hint()
292            + self.3.get_size_hint()
293            + self.4.get_size_hint()
294    }
295}
296
297impl<T1, T2, T3, T4, T5, T6> Serializable for (T1, T2, T3, T4, T5, T6)
298where
299    T1: Serializable,
300    T2: Serializable,
301    T3: Serializable,
302    T4: Serializable,
303    T5: Serializable,
304    T6: Serializable,
305{
306    fn write_into<W: ByteWriter>(&self, target: &mut W) {
307        self.0.write_into(target);
308        self.1.write_into(target);
309        self.2.write_into(target);
310        self.3.write_into(target);
311        self.4.write_into(target);
312        self.5.write_into(target);
313    }
314
315    fn get_size_hint(&self) -> usize {
316        self.0.get_size_hint()
317            + self.1.get_size_hint()
318            + self.2.get_size_hint()
319            + self.3.get_size_hint()
320            + self.4.get_size_hint()
321            + self.5.get_size_hint()
322    }
323}
324
325impl Serializable for u8 {
326    fn write_into<W: ByteWriter>(&self, target: &mut W) {
327        target.write_u8(*self);
328    }
329
330    fn get_size_hint(&self) -> usize {
331        size_of::<u8>()
332    }
333}
334
335impl Serializable for u16 {
336    fn write_into<W: ByteWriter>(&self, target: &mut W) {
337        target.write_u16(*self);
338    }
339
340    fn get_size_hint(&self) -> usize {
341        size_of::<u16>()
342    }
343}
344
345impl Serializable for u32 {
346    fn write_into<W: ByteWriter>(&self, target: &mut W) {
347        target.write_u32(*self);
348    }
349
350    fn get_size_hint(&self) -> usize {
351        size_of::<u32>()
352    }
353}
354
355impl Serializable for u64 {
356    fn write_into<W: ByteWriter>(&self, target: &mut W) {
357        target.write_u64(*self);
358    }
359
360    fn get_size_hint(&self) -> usize {
361        size_of::<u64>()
362    }
363}
364
365impl Serializable for u128 {
366    fn write_into<W: ByteWriter>(&self, target: &mut W) {
367        target.write_u128(*self);
368    }
369
370    fn get_size_hint(&self) -> usize {
371        size_of::<u128>()
372    }
373}
374
375impl Serializable for usize {
376    fn write_into<W: ByteWriter>(&self, target: &mut W) {
377        target.write_usize(*self)
378    }
379
380    fn get_size_hint(&self) -> usize {
381        byte_writer::usize_encoded_len(*self as u64)
382    }
383}
384
385impl<T: Serializable> Serializable for Option<T> {
386    fn write_into<W: ByteWriter>(&self, target: &mut W) {
387        match self {
388            Some(v) => {
389                target.write_bool(true);
390                v.write_into(target);
391            },
392            None => target.write_bool(false),
393        }
394    }
395
396    fn get_size_hint(&self) -> usize {
397        size_of::<bool>() + self.as_ref().map(Serializable::get_size_hint).unwrap_or(0)
398    }
399}
400
401impl<T: Serializable, const C: usize> Serializable for [T; C] {
402    fn write_into<W: ByteWriter>(&self, target: &mut W) {
403        target.write_many(self)
404    }
405
406    fn get_size_hint(&self) -> usize {
407        let mut size = 0;
408        for item in self {
409            size += item.get_size_hint();
410        }
411        size
412    }
413}
414
415impl<T: Serializable> Serializable for [T] {
416    fn write_into<W: ByteWriter>(&self, target: &mut W) {
417        target.write_usize(self.len());
418        for element in self.iter() {
419            element.write_into(target);
420        }
421    }
422
423    fn get_size_hint(&self) -> usize {
424        let mut size = self.len().get_size_hint();
425        for element in self {
426            size += element.get_size_hint();
427        }
428        size
429    }
430}
431
432impl<T: Serializable> Serializable for Vec<T> {
433    fn write_into<W: ByteWriter>(&self, target: &mut W) {
434        target.write_usize(self.len());
435        target.write_many(self);
436    }
437
438    fn get_size_hint(&self) -> usize {
439        let mut size = self.len().get_size_hint();
440        for item in self {
441            size += item.get_size_hint();
442        }
443        size
444    }
445}
446
447impl<K: Serializable, V: Serializable> Serializable for BTreeMap<K, V> {
448    fn write_into<W: ByteWriter>(&self, target: &mut W) {
449        target.write_usize(self.len());
450        target.write_many(self);
451    }
452
453    fn get_size_hint(&self) -> usize {
454        let mut size = self.len().get_size_hint();
455        for item in self {
456            size += item.get_size_hint();
457        }
458        size
459    }
460}
461
462impl<T: Serializable> Serializable for BTreeSet<T> {
463    fn write_into<W: ByteWriter>(&self, target: &mut W) {
464        target.write_usize(self.len());
465        target.write_many(self);
466    }
467
468    fn get_size_hint(&self) -> usize {
469        let mut size = self.len().get_size_hint();
470        for item in self {
471            size += item.get_size_hint();
472        }
473        size
474    }
475}
476
477impl Serializable for str {
478    fn write_into<W: ByteWriter>(&self, target: &mut W) {
479        target.write_usize(self.len());
480        target.write_many(self.as_bytes());
481    }
482
483    fn get_size_hint(&self) -> usize {
484        self.len().get_size_hint() + self.len()
485    }
486}
487
488impl Serializable for String {
489    fn write_into<W: ByteWriter>(&self, target: &mut W) {
490        self.as_str().write_into(target);
491    }
492
493    fn get_size_hint(&self) -> usize {
494        self.as_str().get_size_hint()
495    }
496}
497
498impl Serializable for Arc<str> {
499    fn write_into<W: ByteWriter>(&self, target: &mut W) {
500        self.as_ref().write_into(target);
501    }
502
503    fn get_size_hint(&self) -> usize {
504        self.as_ref().get_size_hint()
505    }
506}
507
508// DESERIALIZABLE
509// ================================================================================================
510
511/// Defines how to deserialize `Self` from bytes.
512pub trait Deserializable: Sized {
513    // REQUIRED METHODS
514    // --------------------------------------------------------------------------------------------
515
516    /// Reads a sequence of bytes from the provided `source`, attempts to deserialize these bytes
517    /// into `Self`, and returns the result.
518    ///
519    /// # Errors
520    /// Returns an error if:
521    /// * The `source` does not contain enough bytes to deserialize `Self`.
522    /// * Bytes read from the `source` do not represent a valid value for `Self`.
523    #[track_caller]
524    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError>;
525
526    /// Returns the minimum serialized size for one instance of this type.
527    ///
528    /// This is used by [`ByteReader::max_alloc`] to estimate how many elements can be
529    /// deserialized from the remaining budget, preventing denial-of-service attacks from
530    /// malicious length prefixes.
531    ///
532    /// The default implementation returns `size_of::<Self>()`, which is conservative: it may
533    /// reject valid input for types where the serialized size is smaller than the in-memory
534    /// size (e.g., structs with computed/cached fields that aren't serialized).
535    ///
536    /// Override this method for types where the serialized representation is smaller than
537    /// the in-memory representation to allow more elements to be deserialized.
538    fn min_serialized_size() -> usize {
539        size_of::<Self>()
540    }
541
542    // PROVIDED METHODS
543    // --------------------------------------------------------------------------------------------
544
545    /// Attempts to deserialize the provided `bytes` into `Self` and returns the result.
546    ///
547    /// # Errors
548    /// Returns an error if:
549    /// * The `bytes` do not contain enough information to deserialize `Self`.
550    /// * The `bytes` do not represent a valid value for `Self`.
551    ///
552    /// Note: if `bytes` contains more data than needed to deserialize `self`, no error is
553    /// returned.
554    ///
555    /// # Security
556    /// This method is for trusted input. It does not bound allocations or reject trailing bytes.
557    /// Use [`Deserializable::read_from_bytes_with_budget`] for attacker-controlled bytes.
558    #[track_caller]
559    fn read_from_bytes(bytes: &[u8]) -> Result<Self, DeserializationError> {
560        Self::read_from(&mut SliceReader::new(bytes))
561    }
562
563    /// Deserializes `Self` from bytes with a byte budget limit.
564    ///
565    /// This is the recommended method for deserializing untrusted input. The budget limits
566    /// how many bytes can be consumed during deserialization, preventing denial-of-service
567    /// attacks that exploit length fields to cause huge allocations.
568    ///
569    /// # Errors
570    /// Returns an error if:
571    /// * The budget is exhausted before deserialization completes.
572    /// * The `bytes` do not contain enough information to deserialize `Self`.
573    /// * The `bytes` do not represent a valid value for `Self`.
574    #[track_caller]
575    fn read_from_bytes_with_budget(
576        bytes: &[u8],
577        budget: usize,
578    ) -> Result<Self, DeserializationError> {
579        Self::read_from(&mut BudgetedReader::new(SliceReader::new(bytes), budget))
580    }
581}
582
583impl Deserializable for () {
584    fn read_from<R: ByteReader>(_source: &mut R) -> Result<Self, DeserializationError> {
585        Ok(())
586    }
587}
588
589impl<T1> Deserializable for (T1,)
590where
591    T1: Deserializable,
592{
593    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
594        let v1 = T1::read_from(source)?;
595        Ok((v1,))
596    }
597
598    fn min_serialized_size() -> usize {
599        T1::min_serialized_size()
600    }
601}
602
603impl<T1, T2> Deserializable for (T1, T2)
604where
605    T1: Deserializable,
606    T2: Deserializable,
607{
608    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
609        let v1 = T1::read_from(source)?;
610        let v2 = T2::read_from(source)?;
611        Ok((v1, v2))
612    }
613
614    fn min_serialized_size() -> usize {
615        T1::min_serialized_size().saturating_add(T2::min_serialized_size())
616    }
617}
618
619impl<T1, T2, T3> Deserializable for (T1, T2, T3)
620where
621    T1: Deserializable,
622    T2: Deserializable,
623    T3: Deserializable,
624{
625    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
626        let v1 = T1::read_from(source)?;
627        let v2 = T2::read_from(source)?;
628        let v3 = T3::read_from(source)?;
629        Ok((v1, v2, v3))
630    }
631
632    fn min_serialized_size() -> usize {
633        T1::min_serialized_size()
634            .saturating_add(T2::min_serialized_size())
635            .saturating_add(T3::min_serialized_size())
636    }
637}
638
639impl<T1, T2, T3, T4> Deserializable for (T1, T2, T3, T4)
640where
641    T1: Deserializable,
642    T2: Deserializable,
643    T3: Deserializable,
644    T4: Deserializable,
645{
646    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
647        let v1 = T1::read_from(source)?;
648        let v2 = T2::read_from(source)?;
649        let v3 = T3::read_from(source)?;
650        let v4 = T4::read_from(source)?;
651        Ok((v1, v2, v3, v4))
652    }
653
654    fn min_serialized_size() -> usize {
655        T1::min_serialized_size()
656            .saturating_add(T2::min_serialized_size())
657            .saturating_add(T3::min_serialized_size())
658            .saturating_add(T4::min_serialized_size())
659    }
660}
661
662impl<T1, T2, T3, T4, T5> Deserializable for (T1, T2, T3, T4, T5)
663where
664    T1: Deserializable,
665    T2: Deserializable,
666    T3: Deserializable,
667    T4: Deserializable,
668    T5: Deserializable,
669{
670    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
671        let v1 = T1::read_from(source)?;
672        let v2 = T2::read_from(source)?;
673        let v3 = T3::read_from(source)?;
674        let v4 = T4::read_from(source)?;
675        let v5 = T5::read_from(source)?;
676        Ok((v1, v2, v3, v4, v5))
677    }
678
679    fn min_serialized_size() -> usize {
680        T1::min_serialized_size()
681            .saturating_add(T2::min_serialized_size())
682            .saturating_add(T3::min_serialized_size())
683            .saturating_add(T4::min_serialized_size())
684            .saturating_add(T5::min_serialized_size())
685    }
686}
687
688impl<T1, T2, T3, T4, T5, T6> Deserializable for (T1, T2, T3, T4, T5, T6)
689where
690    T1: Deserializable,
691    T2: Deserializable,
692    T3: Deserializable,
693    T4: Deserializable,
694    T5: Deserializable,
695    T6: Deserializable,
696{
697    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
698        let v1 = T1::read_from(source)?;
699        let v2 = T2::read_from(source)?;
700        let v3 = T3::read_from(source)?;
701        let v4 = T4::read_from(source)?;
702        let v5 = T5::read_from(source)?;
703        let v6 = T6::read_from(source)?;
704        Ok((v1, v2, v3, v4, v5, v6))
705    }
706
707    fn min_serialized_size() -> usize {
708        T1::min_serialized_size()
709            .saturating_add(T2::min_serialized_size())
710            .saturating_add(T3::min_serialized_size())
711            .saturating_add(T4::min_serialized_size())
712            .saturating_add(T5::min_serialized_size())
713            .saturating_add(T6::min_serialized_size())
714    }
715}
716
717impl Deserializable for u8 {
718    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
719        source.read_u8()
720    }
721}
722
723impl Deserializable for u16 {
724    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
725        source.read_u16()
726    }
727}
728
729impl Deserializable for u32 {
730    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
731        source.read_u32()
732    }
733}
734
735impl Deserializable for u64 {
736    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
737        source.read_u64()
738    }
739}
740
741impl Deserializable for u128 {
742    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
743        source.read_u128()
744    }
745}
746
747impl Deserializable for usize {
748    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
749        source.read_usize()
750    }
751
752    fn min_serialized_size() -> usize {
753        1 // vint64 encoding: minimum 1 byte for values 0-127
754    }
755}
756
757impl<T: Deserializable> Deserializable for Option<T> {
758    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
759        if source.read_bool()? {
760            Ok(Some(T::read_from(source)?))
761        } else {
762            Ok(None)
763        }
764    }
765
766    /// Returns 1 (just the bool discriminator).
767    ///
768    /// The `Some` variant would be `1 + T::min_serialized_size()`, but we use the minimum
769    /// to allow more elements through the early check.
770    fn min_serialized_size() -> usize {
771        1
772    }
773}
774
775impl<T: Deserializable, const C: usize> Deserializable for [T; C] {
776    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
777        let data: Vec<T> = source.read_many_iter(C)?.collect::<Result<_, _>>()?;
778
779        // The iterator yields exactly C elements (or fails early), so this always succeeds
780        Ok(data.try_into().unwrap_or_else(|v: Vec<T>| {
781            panic!("Expected a Vec of length {} but it was {}", C, v.len())
782        }))
783    }
784
785    fn min_serialized_size() -> usize {
786        C.saturating_mul(T::min_serialized_size())
787    }
788}
789
790impl<T: Deserializable> Deserializable for Vec<T> {
791    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
792        let len = source.read_usize()?;
793        source.read_many_iter(len)?.collect()
794    }
795
796    /// Returns 1 (the minimum vint length prefix size).
797    ///
798    /// The actual serialized size depends on the number of elements, which we don't know
799    /// at the point this is called. Using the minimum allows more elements through the
800    /// early check; budget enforcement during actual reads provides the real protection.
801    fn min_serialized_size() -> usize {
802        1
803    }
804}
805
806impl<T: Serializable> Serializable for VecDeque<T> {
807    fn write_into<W: ByteWriter>(&self, target: &mut W) {
808        target.write_usize(self.len());
809        for item in self {
810            item.write_into(target);
811        }
812    }
813
814    fn get_size_hint(&self) -> usize {
815        let mut size = self.len().get_size_hint();
816        for item in self {
817            size += item.get_size_hint();
818        }
819        size
820    }
821}
822
823impl<T: Deserializable> Deserializable for VecDeque<T> {
824    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
825        let len = source.read_usize()?;
826        source.read_many_iter(len)?.collect()
827    }
828
829    /// Returns 1 (the minimum vint length prefix size).
830    ///
831    /// See the note on the `Vec` impl above: budget enforcement during the actual reads provides
832    /// the real protection against oversized length prefixes.
833    fn min_serialized_size() -> usize {
834        1
835    }
836}
837
838impl<K: Deserializable + Ord, V: Deserializable> Deserializable for BTreeMap<K, V> {
839    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
840        let len = source.read_usize()?;
841        let mut map = BTreeMap::new();
842        for entry in source.read_many_iter(len)? {
843            let (key, value) = entry?;
844            if map.insert(key, value).is_some() {
845                return Err(DeserializationError::InvalidValue(String::from(
846                    "duplicate key in BTreeMap encoding",
847                )));
848            }
849        }
850        Ok(map)
851    }
852
853    fn min_serialized_size() -> usize {
854        1 // minimum vint length prefix
855    }
856}
857
858impl<T: Deserializable + Ord> Deserializable for BTreeSet<T> {
859    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
860        let len = source.read_usize()?;
861        let mut set = BTreeSet::new();
862        for item in source.read_many_iter(len)? {
863            if !set.insert(item?) {
864                return Err(DeserializationError::InvalidValue(String::from(
865                    "duplicate item in BTreeSet encoding",
866                )));
867            }
868        }
869        Ok(set)
870    }
871
872    fn min_serialized_size() -> usize {
873        1 // minimum vint length prefix
874    }
875}
876
877impl Deserializable for String {
878    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
879        let len = source.read_usize()?;
880        let data: Vec<u8> = source.read_many_iter(len)?.collect::<Result<_, _>>()?;
881
882        String::from_utf8(data).map_err(|err| DeserializationError::InvalidValue(format!("{err}")))
883    }
884
885    fn min_serialized_size() -> usize {
886        1 // minimum vint length prefix
887    }
888}
889
890impl Deserializable for Arc<str> {
891    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
892        String::read_from(source).map(Arc::from)
893    }
894
895    fn min_serialized_size() -> usize {
896        1 // minimum vint length prefix
897    }
898}
899
900// PLONKY3 FIELD IMPLEMENTATIONS
901// ================================================================================================
902
903impl<F, const D: usize> Serializable for p3_field::extension::BinomialExtensionField<F, D>
904where
905    F: p3_field::Field + p3_field::extension::BinomiallyExtendable<D> + Serializable,
906{
907    fn write_into<W: ByteWriter>(&self, target: &mut W) {
908        let coefficients =
909            <Self as p3_field::BasedVectorSpace<F>>::as_basis_coefficients_slice(self);
910        target.write_many(coefficients);
911    }
912
913    fn get_size_hint(&self) -> usize {
914        <Self as p3_field::BasedVectorSpace<F>>::as_basis_coefficients_slice(self)
915            .iter()
916            .map(Serializable::get_size_hint)
917            .sum()
918    }
919}
920
921impl<F, const D: usize> Deserializable for p3_field::extension::BinomialExtensionField<F, D>
922where
923    F: p3_field::Field + p3_field::extension::BinomiallyExtendable<D> + Deserializable,
924{
925    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
926        Ok(Self::new(<[F; D]>::read_from(source)?))
927    }
928
929    fn min_serialized_size() -> usize {
930        D.saturating_mul(F::min_serialized_size())
931    }
932}
933
934impl Serializable for p3_goldilocks::Goldilocks {
935    fn write_into<W: ByteWriter>(&self, target: &mut W) {
936        use p3_field::PrimeField64;
937        target.write_u64(self.as_canonical_u64());
938    }
939
940    fn get_size_hint(&self) -> usize {
941        size_of::<u64>()
942    }
943}
944
945impl Deserializable for p3_goldilocks::Goldilocks {
946    fn read_from<R: ByteReader>(source: &mut R) -> Result<Self, DeserializationError> {
947        use p3_field::integers::QuotientMap;
948
949        let value = source.read_u64()?;
950        Self::from_canonical_checked(value).ok_or_else(|| {
951            DeserializationError::InvalidValue(format!(
952                "value {value} is not a valid Goldilocks field element"
953            ))
954        })
955    }
956}
957
958#[cfg(test)]
959mod tests {
960    use alloc::{collections::VecDeque, sync::Arc};
961
962    use p3_field::extension::BinomialExtensionField;
963    use p3_goldilocks::Goldilocks;
964
965    use super::*;
966
967    #[test]
968    fn arc_str_roundtrip() {
969        let original: Arc<str> = Arc::from("hello world");
970        let bytes = original.to_bytes();
971        let deserialized = Arc::<str>::read_from_bytes(&bytes).unwrap();
972        assert_eq!(original, deserialized);
973    }
974
975    #[test]
976    fn string_roundtrip() {
977        let original = String::from("hello world");
978        let bytes = original.to_bytes();
979        let deserialized = String::read_from_bytes(&bytes).unwrap();
980        assert_eq!(original, deserialized);
981    }
982
983    #[test]
984    fn vec_deque_roundtrip_and_vec_compatibility() {
985        let original = VecDeque::from([1u32, 2, 3]);
986        let bytes = original.to_bytes();
987
988        assert_eq!(VecDeque::<u32>::read_from_bytes(&bytes).unwrap(), original);
989        assert_eq!(Vec::<u32>::read_from_bytes(&bytes).unwrap(), Vec::from([1, 2, 3]));
990        assert_eq!(
991            VecDeque::<u32>::read_from_bytes(&Vec::from([1u32, 2, 3]).to_bytes()).unwrap(),
992            original
993        );
994    }
995
996    #[test]
997    fn binomial_extension_field_roundtrip() {
998        let coefficients = [Goldilocks::new(1), Goldilocks::new(2)];
999        let original = BinomialExtensionField::<Goldilocks, 2>::new(coefficients);
1000        let bytes = original.to_bytes();
1001
1002        assert_eq!(bytes, coefficients.to_bytes());
1003        assert_eq!(
1004            BinomialExtensionField::<Goldilocks, 2>::read_from_bytes(&bytes).unwrap(),
1005            original
1006        );
1007    }
1008
1009    #[test]
1010    fn empty_string_roundtrip() {
1011        let arc: Arc<str> = Arc::from("");
1012        let bytes = arc.to_bytes();
1013        let deserialized = Arc::<str>::read_from_bytes(&bytes).unwrap();
1014        assert_eq!(deserialized, Arc::from(""));
1015
1016        let string = String::from("");
1017        let bytes = string.to_bytes();
1018        let deserialized = String::read_from_bytes(&bytes).unwrap();
1019        assert_eq!(deserialized, "");
1020    }
1021
1022    #[test]
1023    fn multibyte_utf8_roundtrip() {
1024        let text = "héllo 🌍";
1025
1026        let arc: Arc<str> = Arc::from(text);
1027        let bytes = arc.to_bytes();
1028        let deserialized = Arc::<str>::read_from_bytes(&bytes).unwrap();
1029        assert_eq!(&*deserialized, text);
1030
1031        let string = String::from(text);
1032        let bytes = string.to_bytes();
1033        let deserialized = String::read_from_bytes(&bytes).unwrap();
1034        assert_eq!(deserialized, text);
1035
1036        // Cross-compat: Arc<str> bytes can be read as String and vice versa
1037        let arc_bytes = Arc::<str>::from(text).to_bytes();
1038        let string_bytes = String::from(text).to_bytes();
1039        assert_eq!(arc_bytes, string_bytes);
1040        assert_eq!(String::read_from_bytes(&arc_bytes).unwrap(), text);
1041        assert_eq!(&*Arc::<str>::read_from_bytes(&string_bytes).unwrap(), text);
1042    }
1043
1044    #[test]
1045    fn arc_str_string_cross_compat() {
1046        // Arc<str> -> bytes -> String
1047        let arc: Arc<str> = Arc::from("cross type");
1048        let bytes = arc.to_bytes();
1049        let as_string = String::read_from_bytes(&bytes).unwrap();
1050        assert_eq!(as_string, "cross type");
1051
1052        // String -> bytes -> Arc<str>
1053        let string = String::from("other direction");
1054        let bytes = string.to_bytes();
1055        let as_arc = Arc::<str>::read_from_bytes(&bytes).unwrap();
1056        assert_eq!(&*as_arc, "other direction");
1057    }
1058
1059    #[test]
1060    fn btree_map_rejects_duplicate_keys() {
1061        let mut bytes = Vec::new();
1062        bytes.extend_from_slice(&2usize.to_bytes());
1063        bytes.extend_from_slice(&7u8.to_bytes());
1064        bytes.extend_from_slice(&1u8.to_bytes());
1065        bytes.extend_from_slice(&7u8.to_bytes());
1066        bytes.extend_from_slice(&2u8.to_bytes());
1067
1068        let result = BTreeMap::<u8, u8>::read_from_bytes(&bytes);
1069
1070        assert!(matches!(result, Err(DeserializationError::InvalidValue(_))));
1071    }
1072
1073    #[test]
1074    fn btree_set_rejects_duplicate_items() {
1075        let mut bytes = Vec::new();
1076        bytes.extend_from_slice(&2usize.to_bytes());
1077        bytes.extend_from_slice(&7u8.to_bytes());
1078        bytes.extend_from_slice(&7u8.to_bytes());
1079
1080        let result = BTreeSet::<u8>::read_from_bytes(&bytes);
1081
1082        assert!(matches!(result, Err(DeserializationError::InvalidValue(_))));
1083    }
1084
1085    #[test]
1086    fn read_bounded_len_accepts_a_length_backed_by_enough_input() {
1087        let mut bytes = 3usize.to_bytes();
1088        bytes.extend_from_slice(&[0u8; 3]);
1089        let mut source = SliceReader::new(&bytes);
1090
1091        assert_eq!(read_bounded_len(&mut source, "elements", 1).unwrap(), 3);
1092    }
1093
1094    #[test]
1095    fn read_bounded_len_rejects_a_length_exceeding_remaining_input() {
1096        let mut bytes = 8usize.to_bytes();
1097        bytes.extend_from_slice(&[0u8; 3]);
1098        let mut source = SliceReader::new(&bytes);
1099
1100        assert!(matches!(
1101            read_bounded_len(&mut source, "elements", 1),
1102            Err(DeserializationError::InvalidValue(_))
1103        ));
1104    }
1105
1106    #[test]
1107    fn read_bounded_len_rejects_a_length_exceeding_the_budget() {
1108        let mut bytes = 64usize.to_bytes();
1109        bytes.extend_from_slice(&[0u8; 64]);
1110        let mut source = BudgetedReader::new(SliceReader::new(&bytes), 16);
1111
1112        assert!(matches!(
1113            read_bounded_len(&mut source, "elements", 1),
1114            Err(DeserializationError::InvalidValue(_))
1115        ));
1116    }
1117
1118    #[test]
1119    fn validate_bounded_len_rejects_a_length_overflowing_the_element_size() {
1120        let source = SliceReader::new(&[]);
1121
1122        assert!(matches!(
1123            validate_bounded_len(&source, "elements", usize::MAX, 2),
1124            Err(DeserializationError::InvalidValue(_))
1125        ));
1126    }
1127
1128    #[test]
1129    fn budgeted_vec_of_one_element_tuples_accepts_exact_budget() {
1130        let values = Vec::<(usize,)>::from([(0,), (1,), (2,)]);
1131        let bytes = values.to_bytes();
1132
1133        let decoded = Vec::<(usize,)>::read_from_bytes_with_budget(&bytes, bytes.len()).unwrap();
1134
1135        assert_eq!(decoded, values);
1136    }
1137}
miden_serde_utils/lib.rs

miden_serde_utils/
lib.rs
