bitcoin_consensus_encoding/decode/
decoders.rs

1// SPDX-License-Identifier: CC0-1.0
2
3//! Primitive decoders.
4
5#[cfg(feature = "alloc")]
6use alloc::vec::Vec;
7#[cfg(feature = "alloc")]
8use core::convert::Infallible;
9use core::{fmt, mem};
10
11use internals::write_err;
12
13#[cfg(feature = "alloc")]
14use super::Decodable;
15use super::Decoder;
16
17/// Maximum size, in bytes, of a vector we are allowed to decode.
18///
19/// This is also the default value limit that can be decoded with a decoder from
20/// [`CompactSizeDecoder::new`].
21const MAX_VEC_SIZE: usize = 4_000_000;
22
23/// Maximum amount of memory (in bytes) to allocate at once when deserializing vectors.
24#[cfg(feature = "alloc")]
25const MAX_VECTOR_ALLOCATE: usize = 1_000_000;
26
27/// A decoder that decodes a byte vector.
28///
29/// The encoding is expected to start with the number of encoded bytes (length prefix).
30#[cfg(feature = "alloc")]
31pub struct ByteVecDecoder {
32    prefix_decoder: Option<CompactSizeDecoder>,
33    buffer: Vec<u8>,
34    bytes_expected: usize,
35    bytes_written: usize,
36}
37
38#[cfg(feature = "alloc")]
39impl ByteVecDecoder {
40    /// Constructs a new byte decoder.
41    pub const fn new() -> Self {
42        Self {
43            prefix_decoder: Some(CompactSizeDecoder::new()),
44            buffer: Vec::new(),
45            bytes_expected: 0,
46            bytes_written: 0,
47        }
48    }
49
50    /// Reserves capacity for byte vectors in batches.
51    ///
52    /// Reserves up to `MAX_VECTOR_ALLOCATE` bytes when the buffer has no remaining capacity.
53    ///
54    /// Documentation adapted from Bitcoin Core:
55    ///
56    /// > For `DoS` prevention, do not blindly allocate as much as the stream claims to contain.
57    /// > Instead, allocate in ~1 MB batches, so that an attacker actually needs to provide X MB of
58    /// > data to make us allocate X+1 MB of memory.
59    ///
60    /// ref: <https://github.com/bitcoin/bitcoin/blob/72511fd02e72b74be11273e97bd7911786a82e54/src/serialize.h#L669C2-L672C1>
61    fn reserve(&mut self) {
62        if self.buffer.len() == self.buffer.capacity() {
63            let bytes_remaining = self.bytes_expected - self.bytes_written;
64            let batch_size = bytes_remaining.min(MAX_VECTOR_ALLOCATE);
65            self.buffer.reserve_exact(batch_size);
66        }
67    }
68}
69
70#[cfg(feature = "alloc")]
71impl Default for ByteVecDecoder {
72    fn default() -> Self { Self::new() }
73}
74
75#[cfg(feature = "alloc")]
76impl Decoder for ByteVecDecoder {
77    type Output = Vec<u8>;
78    type Error = ByteVecDecoderError;
79
80    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
81        use {ByteVecDecoderError as E, ByteVecDecoderErrorInner as Inner};
82
83        if let Some(mut decoder) = self.prefix_decoder.take() {
84            if decoder.push_bytes(bytes).map_err(|e| E(Inner::LengthPrefixDecode(e)))? {
85                self.prefix_decoder = Some(decoder);
86                return Ok(true);
87            }
88            self.bytes_expected = decoder.end().map_err(|e| E(Inner::LengthPrefixDecode(e)))?;
89            self.prefix_decoder = None;
90
91            // For DoS prevention, let's not allocate all memory upfront.
92        }
93
94        self.reserve();
95
96        let remaining = self.bytes_expected - self.bytes_written;
97        let available_capacity = self.buffer.capacity() - self.buffer.len();
98        let copy_len = bytes.len().min(remaining).min(available_capacity);
99
100        self.buffer.extend_from_slice(&bytes[..copy_len]);
101        self.bytes_written += copy_len;
102        *bytes = &bytes[copy_len..];
103
104        // Return true if we still need more data.
105        Ok(self.bytes_written < self.bytes_expected)
106    }
107
108    fn end(self) -> Result<Self::Output, Self::Error> {
109        use {ByteVecDecoderError as E, ByteVecDecoderErrorInner as Inner};
110
111        if self.bytes_written == self.bytes_expected {
112            Ok(self.buffer)
113        } else {
114            Err(E(Inner::UnexpectedEof(UnexpectedEofError {
115                missing: self.bytes_expected - self.bytes_written,
116            })))
117        }
118    }
119
120    fn read_limit(&self) -> usize {
121        if let Some(prefix_decoder) = &self.prefix_decoder {
122            prefix_decoder.read_limit()
123        } else {
124            self.bytes_expected - self.bytes_written
125        }
126    }
127}
128
129/// A decoder that decodes a vector of `T`s.
130///
131/// The decoding is expected to start with expected number of items in the vector.
132#[cfg(feature = "alloc")]
133pub struct VecDecoder<T: Decodable> {
134    prefix_decoder: Option<CompactSizeDecoder>,
135    length: usize,
136    buffer: Vec<T>,
137    decoder: Option<<T as Decodable>::Decoder>,
138}
139
140#[cfg(feature = "alloc")]
141impl<T: Decodable> VecDecoder<T> {
142    /// Constructs a new byte decoder.
143    pub const fn new() -> Self {
144        Self {
145            prefix_decoder: Some(CompactSizeDecoder::new()),
146            length: 0,
147            buffer: Vec::new(),
148            decoder: None,
149        }
150    }
151
152    /// Reserves capacity for typed vectors in batches.
153    ///
154    /// Calculates how many elements of type `T` fit within `MAX_VECTOR_ALLOCATE` bytes and reserves
155    /// up to that amount when the buffer reaches capacity.
156    ///
157    /// Documentation adapted from Bitcoin Core:
158    ///
159    /// > For `DoS` prevention, do not blindly allocate as much as the stream claims to contain.
160    /// > Instead, allocate in ~1 MB batches, so that an attacker actually needs to provide X MB of
161    /// > data to make us allocate X+1 MB of memory.
162    ///
163    /// ref: <https://github.com/bitcoin/bitcoin/blob/72511fd02e72b74be11273e97bd7911786a82e54/src/serialize.h#L669C2-L672C1>
164    fn reserve(&mut self) {
165        if self.buffer.len() == self.buffer.capacity() {
166            let elements_remaining = self.length - self.buffer.len();
167            let element_size = mem::size_of::<T>().max(1);
168            let batch_elements = MAX_VECTOR_ALLOCATE / element_size;
169            let elements_to_reserve = elements_remaining.min(batch_elements);
170            self.buffer.reserve_exact(elements_to_reserve);
171        }
172    }
173}
174
175#[cfg(feature = "alloc")]
176impl<T: Decodable> Default for VecDecoder<T> {
177    fn default() -> Self { Self::new() }
178}
179
180#[cfg(feature = "alloc")]
181impl<T: Decodable> Decoder for VecDecoder<T> {
182    type Output = Vec<T>;
183    type Error = VecDecoderError<<<T as Decodable>::Decoder as Decoder>::Error>;
184
185    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
186        use {VecDecoderError as E, VecDecoderErrorInner as Inner};
187
188        if let Some(mut decoder) = self.prefix_decoder.take() {
189            if decoder.push_bytes(bytes).map_err(|e| E(Inner::LengthPrefixDecode(e)))? {
190                self.prefix_decoder = Some(decoder);
191                return Ok(true);
192            }
193            self.length = decoder.end().map_err(|e| E(Inner::LengthPrefixDecode(e)))?;
194            if self.length == 0 {
195                return Ok(false);
196            }
197
198            self.prefix_decoder = None;
199
200            // For DoS prevention, let's not allocate all memory upfront.
201        }
202
203        while !bytes.is_empty() {
204            self.reserve();
205
206            let mut decoder = self.decoder.take().unwrap_or_else(T::decoder);
207
208            if decoder.push_bytes(bytes).map_err(|e| E(Inner::Item(e)))? {
209                self.decoder = Some(decoder);
210                return Ok(true);
211            }
212            let item = decoder.end().map_err(|e| E(Inner::Item(e)))?;
213            self.buffer.push(item);
214
215            if self.buffer.len() == self.length {
216                return Ok(false);
217            }
218        }
219
220        if self.buffer.len() == self.length {
221            Ok(false)
222        } else {
223            Ok(true)
224        }
225    }
226
227    fn end(self) -> Result<Self::Output, Self::Error> {
228        use VecDecoderErrorInner as E;
229
230        if self.buffer.len() == self.length {
231            Ok(self.buffer)
232        } else {
233            Err(VecDecoderError(E::UnexpectedEof(UnexpectedEofError {
234                missing: self.length - self.buffer.len(),
235            })))
236        }
237    }
238
239    fn read_limit(&self) -> usize {
240        if let Some(prefix_decoder) = &self.prefix_decoder {
241            prefix_decoder.read_limit()
242        } else if let Some(decoder) = &self.decoder {
243            decoder.read_limit()
244        } else if self.buffer.len() == self.length {
245            // Totally done.
246            0
247        } else {
248            let items_left_to_decode = self.length - self.buffer.len();
249            let decoder = T::decoder();
250            // This could be inaccurate (eg 1 for a `ByteVecDecoder`) but its the best we can do.
251            let limit_per_decoder = decoder.read_limit();
252            items_left_to_decode * limit_per_decoder
253        }
254    }
255}
256
257/// A decoder that expects exactly N bytes and returns them as an array.
258pub struct ArrayDecoder<const N: usize> {
259    buffer: [u8; N],
260    bytes_written: usize,
261}
262
263impl<const N: usize> ArrayDecoder<N> {
264    /// Constructs a new array decoder that expects exactly N bytes.
265    pub const fn new() -> Self { Self { buffer: [0; N], bytes_written: 0 } }
266}
267
268impl<const N: usize> Default for ArrayDecoder<N> {
269    fn default() -> Self { Self::new() }
270}
271
272impl<const N: usize> Decoder for ArrayDecoder<N> {
273    type Output = [u8; N];
274    type Error = UnexpectedEofError;
275
276    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
277        let remaining_space = N - self.bytes_written;
278        let copy_len = bytes.len().min(remaining_space);
279
280        if copy_len > 0 {
281            self.buffer[self.bytes_written..self.bytes_written + copy_len]
282                .copy_from_slice(&bytes[..copy_len]);
283            self.bytes_written += copy_len;
284            // Advance the slice reference to consume the bytes.
285            *bytes = &bytes[copy_len..];
286        }
287
288        // Return true if we still need more data.
289        Ok(self.bytes_written < N)
290    }
291
292    #[inline]
293    fn end(self) -> Result<Self::Output, Self::Error> {
294        if self.bytes_written == N {
295            Ok(self.buffer)
296        } else {
297            Err(UnexpectedEofError { missing: N - self.bytes_written })
298        }
299    }
300
301    #[inline]
302    fn read_limit(&self) -> usize { N - self.bytes_written }
303}
304
305/// A decoder which wraps two inner decoders and returns the output of both.
306pub struct Decoder2<A, B>
307where
308    A: Decoder,
309    B: Decoder,
310{
311    state: Decoder2State<A, B>,
312}
313
314enum Decoder2State<A: Decoder, B: Decoder> {
315    /// Decoding the first decoder, with second decoder waiting.
316    First(A, B),
317    /// Decoding the second decoder, with the first result stored.
318    Second(A::Output, B),
319    /// Decoder has failed and cannot be used again.
320    Errored,
321}
322
323impl<A, B> Decoder2<A, B>
324where
325    A: Decoder,
326    B: Decoder,
327{
328    /// Constructs a new composite decoder.
329    pub const fn new(first: A, second: B) -> Self {
330        Self { state: Decoder2State::First(first, second) }
331    }
332}
333
334impl<A, B> Decoder for Decoder2<A, B>
335where
336    A: Decoder,
337    B: Decoder,
338{
339    type Output = (A::Output, B::Output);
340    type Error = Decoder2Error<A::Error, B::Error>;
341
342    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
343        loop {
344            match &mut self.state {
345                Decoder2State::First(first_decoder, _) => {
346                    if first_decoder.push_bytes(bytes).map_err(Decoder2Error::First)? {
347                        // First decoder wants more data.
348                        return Ok(true);
349                    }
350
351                    // First decoder is complete, transition to second.
352                    // If the first decoder fails, the composite decoder
353                    // remains in an Errored state.
354                    match mem::replace(&mut self.state, Decoder2State::Errored) {
355                        Decoder2State::First(first, second) => {
356                            let first_result = first.end().map_err(Decoder2Error::First)?;
357                            self.state = Decoder2State::Second(first_result, second);
358                        }
359                        _ => unreachable!("we know we're in First state"),
360                    }
361                }
362                Decoder2State::Second(_, second_decoder) => {
363                    return second_decoder.push_bytes(bytes).map_err(|error| {
364                        self.state = Decoder2State::Errored;
365                        Decoder2Error::Second(error)
366                    });
367                }
368                Decoder2State::Errored => {
369                    panic!("use of failed decoder");
370                }
371            }
372        }
373    }
374
375    #[inline]
376    fn end(self) -> Result<Self::Output, Self::Error> {
377        match self.state {
378            Decoder2State::First(first_decoder, second_decoder) => {
379                // This branch is most likely an error since the decoder
380                // never got to the second one. But letting the error bubble
381                // up naturally from the child decoders.
382                let first_result = first_decoder.end().map_err(Decoder2Error::First)?;
383                let second_result = second_decoder.end().map_err(Decoder2Error::Second)?;
384                Ok((first_result, second_result))
385            }
386            Decoder2State::Second(first_result, second_decoder) => {
387                let second_result = second_decoder.end().map_err(Decoder2Error::Second)?;
388                Ok((first_result, second_result))
389            }
390            Decoder2State::Errored => {
391                panic!("use of failed decoder");
392            }
393        }
394    }
395
396    #[inline]
397    fn read_limit(&self) -> usize {
398        match &self.state {
399            Decoder2State::First(first_decoder, second_decoder) =>
400                first_decoder.read_limit() + second_decoder.read_limit(),
401            Decoder2State::Second(_, second_decoder) => second_decoder.read_limit(),
402            Decoder2State::Errored => 0,
403        }
404    }
405}
406
407/// A decoder which decodes three objects, one after the other.
408pub struct Decoder3<A, B, C>
409where
410    A: Decoder,
411    B: Decoder,
412    C: Decoder,
413{
414    inner: Decoder2<Decoder2<A, B>, C>,
415}
416
417impl<A, B, C> Decoder3<A, B, C>
418where
419    A: Decoder,
420    B: Decoder,
421    C: Decoder,
422{
423    /// Constructs a new composite decoder.
424    pub const fn new(dec_1: A, dec_2: B, dec_3: C) -> Self {
425        Self { inner: Decoder2::new(Decoder2::new(dec_1, dec_2), dec_3) }
426    }
427}
428
429impl<A, B, C> Decoder for Decoder3<A, B, C>
430where
431    A: Decoder,
432    B: Decoder,
433    C: Decoder,
434{
435    type Output = (A::Output, B::Output, C::Output);
436    type Error = Decoder3Error<A::Error, B::Error, C::Error>;
437
438    #[inline]
439    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
440        self.inner.push_bytes(bytes).map_err(|error| match error {
441            Decoder2Error::First(Decoder2Error::First(a)) => Decoder3Error::First(a),
442            Decoder2Error::First(Decoder2Error::Second(b)) => Decoder3Error::Second(b),
443            Decoder2Error::Second(c) => Decoder3Error::Third(c),
444        })
445    }
446
447    #[inline]
448    fn end(self) -> Result<Self::Output, Self::Error> {
449        let result = self.inner.end().map_err(|error| match error {
450            Decoder2Error::First(Decoder2Error::First(a)) => Decoder3Error::First(a),
451            Decoder2Error::First(Decoder2Error::Second(b)) => Decoder3Error::Second(b),
452            Decoder2Error::Second(c) => Decoder3Error::Third(c),
453        })?;
454
455        let ((first, second), third) = result;
456        Ok((first, second, third))
457    }
458
459    #[inline]
460    fn read_limit(&self) -> usize { self.inner.read_limit() }
461}
462
463/// A decoder which decodes four objects, one after the other.
464pub struct Decoder4<A, B, C, D>
465where
466    A: Decoder,
467    B: Decoder,
468    C: Decoder,
469    D: Decoder,
470{
471    inner: Decoder2<Decoder2<A, B>, Decoder2<C, D>>,
472}
473
474impl<A, B, C, D> Decoder4<A, B, C, D>
475where
476    A: Decoder,
477    B: Decoder,
478    C: Decoder,
479    D: Decoder,
480{
481    /// Constructs a new composite decoder.
482    pub const fn new(dec_1: A, dec_2: B, dec_3: C, dec_4: D) -> Self {
483        Self { inner: Decoder2::new(Decoder2::new(dec_1, dec_2), Decoder2::new(dec_3, dec_4)) }
484    }
485}
486
487impl<A, B, C, D> Decoder for Decoder4<A, B, C, D>
488where
489    A: Decoder,
490    B: Decoder,
491    C: Decoder,
492    D: Decoder,
493{
494    type Output = (A::Output, B::Output, C::Output, D::Output);
495    type Error = Decoder4Error<A::Error, B::Error, C::Error, D::Error>;
496
497    #[inline]
498    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
499        self.inner.push_bytes(bytes).map_err(|error| match error {
500            Decoder2Error::First(Decoder2Error::First(a)) => Decoder4Error::First(a),
501            Decoder2Error::First(Decoder2Error::Second(b)) => Decoder4Error::Second(b),
502            Decoder2Error::Second(Decoder2Error::First(c)) => Decoder4Error::Third(c),
503            Decoder2Error::Second(Decoder2Error::Second(d)) => Decoder4Error::Fourth(d),
504        })
505    }
506
507    #[inline]
508    fn end(self) -> Result<Self::Output, Self::Error> {
509        let result = self.inner.end().map_err(|error| match error {
510            Decoder2Error::First(Decoder2Error::First(a)) => Decoder4Error::First(a),
511            Decoder2Error::First(Decoder2Error::Second(b)) => Decoder4Error::Second(b),
512            Decoder2Error::Second(Decoder2Error::First(c)) => Decoder4Error::Third(c),
513            Decoder2Error::Second(Decoder2Error::Second(d)) => Decoder4Error::Fourth(d),
514        })?;
515
516        let ((first, second), (third, fourth)) = result;
517        Ok((first, second, third, fourth))
518    }
519
520    #[inline]
521    fn read_limit(&self) -> usize { self.inner.read_limit() }
522}
523
524/// A decoder which decodes six objects, one after the other.
525#[allow(clippy::type_complexity)] // Nested composition is easier than flattened alternatives.
526pub struct Decoder6<A, B, C, D, E, F>
527where
528    A: Decoder,
529    B: Decoder,
530    C: Decoder,
531    D: Decoder,
532    E: Decoder,
533    F: Decoder,
534{
535    inner: Decoder2<Decoder3<A, B, C>, Decoder3<D, E, F>>,
536}
537
538impl<A, B, C, D, E, F> Decoder6<A, B, C, D, E, F>
539where
540    A: Decoder,
541    B: Decoder,
542    C: Decoder,
543    D: Decoder,
544    E: Decoder,
545    F: Decoder,
546{
547    /// Constructs a new composite decoder.
548    pub const fn new(dec_1: A, dec_2: B, dec_3: C, dec_4: D, dec_5: E, dec_6: F) -> Self {
549        Self {
550            inner: Decoder2::new(
551                Decoder3::new(dec_1, dec_2, dec_3),
552                Decoder3::new(dec_4, dec_5, dec_6),
553            ),
554        }
555    }
556}
557
558impl<A, B, C, D, E, F> Decoder for Decoder6<A, B, C, D, E, F>
559where
560    A: Decoder,
561    B: Decoder,
562    C: Decoder,
563    D: Decoder,
564    E: Decoder,
565    F: Decoder,
566{
567    type Output = (A::Output, B::Output, C::Output, D::Output, E::Output, F::Output);
568    type Error = Decoder6Error<A::Error, B::Error, C::Error, D::Error, E::Error, F::Error>;
569
570    #[inline]
571    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
572        self.inner.push_bytes(bytes).map_err(|error| match error {
573            Decoder2Error::First(Decoder3Error::First(a)) => Decoder6Error::First(a),
574            Decoder2Error::First(Decoder3Error::Second(b)) => Decoder6Error::Second(b),
575            Decoder2Error::First(Decoder3Error::Third(c)) => Decoder6Error::Third(c),
576            Decoder2Error::Second(Decoder3Error::First(d)) => Decoder6Error::Fourth(d),
577            Decoder2Error::Second(Decoder3Error::Second(e)) => Decoder6Error::Fifth(e),
578            Decoder2Error::Second(Decoder3Error::Third(f)) => Decoder6Error::Sixth(f),
579        })
580    }
581
582    #[inline]
583    fn end(self) -> Result<Self::Output, Self::Error> {
584        let result = self.inner.end().map_err(|error| match error {
585            Decoder2Error::First(Decoder3Error::First(a)) => Decoder6Error::First(a),
586            Decoder2Error::First(Decoder3Error::Second(b)) => Decoder6Error::Second(b),
587            Decoder2Error::First(Decoder3Error::Third(c)) => Decoder6Error::Third(c),
588            Decoder2Error::Second(Decoder3Error::First(d)) => Decoder6Error::Fourth(d),
589            Decoder2Error::Second(Decoder3Error::Second(e)) => Decoder6Error::Fifth(e),
590            Decoder2Error::Second(Decoder3Error::Third(f)) => Decoder6Error::Sixth(f),
591        })?;
592
593        let ((first, second, third), (fourth, fifth, sixth)) = result;
594        Ok((first, second, third, fourth, fifth, sixth))
595    }
596
597    #[inline]
598    fn read_limit(&self) -> usize { self.inner.read_limit() }
599}
600
601/// Decodes a compact size encoded integer.
602///
603/// For more information about decoder see the documentation of the [`Decoder`] trait.
604#[derive(Debug, Clone)]
605pub struct CompactSizeDecoder {
606    buf: internals::array_vec::ArrayVec<u8, 9>,
607    limit: usize,
608}
609
610impl CompactSizeDecoder {
611    /// Constructs a new compact size decoder.
612    ///
613    /// Consensus encoded vectors can be up to 4,000,000 bytes long.
614    /// This is a theoretical max since block size is 4 meg wu and minimum vector element is one byte.
615    ///
616    /// The final call to [`CompactSizeDecoder::end`] on this decoder will fail if the
617    /// decoded value exceeds 4,000,000 or won't fit in a `usize`.
618    pub const fn new() -> Self {
619        Self { buf: internals::array_vec::ArrayVec::new(), limit: MAX_VEC_SIZE }
620    }
621
622    /// Constructs a new compact size decoder with encoded value limited to the provided usize.
623    ///
624    /// The final call to [`CompactSizeDecoder::end`] on this decoder will fail if the
625    /// decoded value exceeds `limit` or won't fit in a `usize`.
626    pub const fn new_with_limit(limit: usize) -> Self {
627        Self { buf: internals::array_vec::ArrayVec::new(), limit }
628    }
629}
630
631impl Default for CompactSizeDecoder {
632    fn default() -> Self { Self::new() }
633}
634
635impl Decoder for CompactSizeDecoder {
636    type Output = usize;
637    type Error = CompactSizeDecoderError;
638
639    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
640        if bytes.is_empty() {
641            return Ok(true);
642        }
643
644        if self.buf.is_empty() {
645            self.buf.push(bytes[0]);
646            *bytes = &bytes[1..];
647        }
648        let len = match self.buf[0] {
649            0xFF => 9,
650            0xFE => 5,
651            0xFD => 3,
652            _ => 1,
653        };
654        let to_copy = bytes.len().min(len - self.buf.len());
655        self.buf.extend_from_slice(&bytes[..to_copy]);
656        *bytes = &bytes[to_copy..];
657
658        Ok(self.buf.len() != len)
659    }
660
661    fn end(self) -> Result<Self::Output, Self::Error> {
662        use CompactSizeDecoderErrorInner as E;
663
664        fn arr<const N: usize>(slice: &[u8]) -> Result<[u8; N], CompactSizeDecoderError> {
665            slice.try_into().map_err(|_| {
666                CompactSizeDecoderError(E::UnexpectedEof { required: N, received: slice.len() })
667            })
668        }
669
670        let (first, payload) = self
671            .buf
672            .split_first()
673            .ok_or(CompactSizeDecoderError(E::UnexpectedEof { required: 1, received: 0 }))?;
674
675        let dec_value = match *first {
676            0xFF => {
677                let x = u64::from_le_bytes(arr(payload)?);
678                if x < 0x100_000_000 {
679                    Err(CompactSizeDecoderError(E::NonMinimal { value: x }))
680                } else {
681                    Ok(x)
682                }
683            }
684            0xFE => {
685                let x = u32::from_le_bytes(arr(payload)?);
686                if x < 0x10000 {
687                    Err(CompactSizeDecoderError(E::NonMinimal { value: x.into() }))
688                } else {
689                    Ok(x.into())
690                }
691            }
692            0xFD => {
693                let x = u16::from_le_bytes(arr(payload)?);
694                if x < 0xFD {
695                    Err(CompactSizeDecoderError(E::NonMinimal { value: x.into() }))
696                } else {
697                    Ok(x.into())
698                }
699            }
700            n => Ok(n.into()),
701        }?;
702
703        // This error is returned if dec_value is outside of the usize range, or
704        // if it is above the given limit.
705        let make_err = || {
706            CompactSizeDecoderError(E::ValueExceedsLimit(LengthPrefixExceedsMaxError {
707                value: dec_value,
708                limit: self.limit,
709            }))
710        };
711
712        usize::try_from(dec_value).map_err(|_| make_err()).and_then(|nsize| {
713            if nsize > self.limit {
714                Err(make_err())
715            } else {
716                Ok(nsize)
717            }
718        })
719    }
720
721    fn read_limit(&self) -> usize {
722        match self.buf.len() {
723            0 => 1,
724            already_read => match self.buf[0] {
725                0xFF => 9_usize.saturating_sub(already_read),
726                0xFE => 5_usize.saturating_sub(already_read),
727                0xFD => 3_usize.saturating_sub(already_read),
728                _ => 0,
729            },
730        }
731    }
732}
733
734/// An error consensus decoding a compact size encoded integer.
735#[derive(Debug, Clone, PartialEq, Eq)]
736pub struct CompactSizeDecoderError(CompactSizeDecoderErrorInner);
737
738#[derive(Debug, Clone, PartialEq, Eq)]
739enum CompactSizeDecoderErrorInner {
740    /// Returned when the decoder reaches end of stream (EOF).
741    UnexpectedEof {
742        /// How many bytes were required.
743        required: usize,
744        /// How many bytes were received.
745        received: usize,
746    },
747    /// Returned when the encoding is not minimal
748    NonMinimal {
749        /// The encoded value.
750        value: u64,
751    },
752    /// Returned when the encoded value exceeds the decoder's limit.
753    ValueExceedsLimit(LengthPrefixExceedsMaxError),
754}
755
756impl fmt::Display for CompactSizeDecoderError {
757    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
758        use CompactSizeDecoderErrorInner as E;
759
760        match self.0 {
761            E::UnexpectedEof { required: 1, received: 0 } => {
762                write!(f, "required at least one byte but the input is empty")
763            }
764            E::UnexpectedEof { required, received: 0 } => {
765                write!(f, "required at least {} bytes but the input is empty", required)
766            }
767            E::UnexpectedEof { required, received } => write!(
768                f,
769                "required at least {} bytes but only {} bytes were received",
770                required, received
771            ),
772            E::NonMinimal { value } => write!(f, "the value {} was not encoded minimally", value),
773            E::ValueExceedsLimit(ref e) => write_err!(f, "value exceeds limit"; e),
774        }
775    }
776}
777
778#[cfg(feature = "std")]
779impl std::error::Error for CompactSizeDecoderError {
780    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
781        use CompactSizeDecoderErrorInner as E;
782
783        match self {
784            Self(E::ValueExceedsLimit(ref e)) => Some(e),
785            _ => None,
786        }
787    }
788}
789
790/// The error returned by the [`ByteVecDecoder`].
791#[cfg(feature = "alloc")]
792#[derive(Debug, Clone, PartialEq, Eq)]
793pub struct ByteVecDecoderError(ByteVecDecoderErrorInner);
794
795#[cfg(feature = "alloc")]
796#[derive(Debug, Clone, PartialEq, Eq)]
797enum ByteVecDecoderErrorInner {
798    /// Error decoding the byte vector length prefix.
799    LengthPrefixDecode(CompactSizeDecoderError),
800    /// Not enough bytes given to decoder.
801    UnexpectedEof(UnexpectedEofError),
802}
803
804#[cfg(feature = "alloc")]
805impl From<Infallible> for ByteVecDecoderError {
806    fn from(never: Infallible) -> Self { match never {} }
807}
808
809#[cfg(feature = "alloc")]
810impl fmt::Display for ByteVecDecoderError {
811    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
812        use ByteVecDecoderErrorInner as E;
813
814        match self.0 {
815            E::LengthPrefixDecode(ref e) => write_err!(f, "byte vec decoder error"; e),
816            E::UnexpectedEof(ref e) => write_err!(f, "byte vec decoder error"; e),
817        }
818    }
819}
820
821#[cfg(all(feature = "std", feature = "alloc"))]
822impl std::error::Error for ByteVecDecoderError {
823    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
824        use ByteVecDecoderErrorInner as E;
825
826        match self.0 {
827            E::LengthPrefixDecode(ref e) => Some(e),
828            E::UnexpectedEof(ref e) => Some(e),
829        }
830    }
831}
832
833/// The error returned by the [`VecDecoder`].
834#[cfg(feature = "alloc")]
835#[derive(Debug, Clone, PartialEq, Eq)]
836pub struct VecDecoderError<Err>(VecDecoderErrorInner<Err>);
837
838#[cfg(feature = "alloc")]
839#[derive(Debug, Clone, PartialEq, Eq)]
840enum VecDecoderErrorInner<Err> {
841    /// Error decoding the vector length prefix.
842    LengthPrefixDecode(CompactSizeDecoderError),
843    /// Error while decoding an item.
844    Item(Err),
845    /// Not enough bytes given to decoder.
846    UnexpectedEof(UnexpectedEofError),
847}
848
849#[cfg(feature = "alloc")]
850impl<Err> From<Infallible> for VecDecoderError<Err> {
851    fn from(never: Infallible) -> Self { match never {} }
852}
853
854#[cfg(feature = "alloc")]
855impl<Err> fmt::Display for VecDecoderError<Err>
856where
857    Err: fmt::Display + fmt::Debug,
858{
859    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
860        use VecDecoderErrorInner as E;
861
862        match self.0 {
863            E::LengthPrefixDecode(ref e) => write_err!(f, "vec decoder error"; e),
864            E::Item(ref e) => write_err!(f, "vec decoder error"; e),
865            E::UnexpectedEof(ref e) => write_err!(f, "vec decoder error"; e),
866        }
867    }
868}
869
870#[cfg(feature = "std")]
871impl<Err> std::error::Error for VecDecoderError<Err>
872where
873    Err: std::error::Error + 'static,
874{
875    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
876        use VecDecoderErrorInner as E;
877
878        match self.0 {
879            E::LengthPrefixDecode(ref e) => Some(e),
880            E::Item(ref e) => Some(e),
881            E::UnexpectedEof(ref e) => Some(e),
882        }
883    }
884}
885
886/// Length prefix exceeds the configured limit.
887#[derive(Debug, Clone, PartialEq, Eq)]
888pub struct LengthPrefixExceedsMaxError {
889    /// Decoded value of the compact encoded length prefix.
890    value: u64,
891    /// The value limit that the length prefix exceeds.
892    limit: usize,
893}
894
895impl core::fmt::Display for LengthPrefixExceedsMaxError {
896    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
897        write!(f, "length prefix {} exceeds max value {}", self.value, self.limit)
898    }
899}
900
901#[cfg(feature = "std")]
902impl std::error::Error for LengthPrefixExceedsMaxError {}
903
904/// Not enough bytes given to decoder.
905#[derive(Debug, Clone, PartialEq, Eq)]
906pub struct UnexpectedEofError {
907    /// Number of bytes missing to complete decoder.
908    missing: usize,
909}
910
911impl fmt::Display for UnexpectedEofError {
912    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
913        write!(f, "not enough bytes for decoder, {} more bytes required", self.missing)
914    }
915}
916
917#[cfg(feature = "std")]
918impl std::error::Error for UnexpectedEofError {}
919
920/// Error type for [`Decoder2`].
921#[derive(Debug, Clone, PartialEq, Eq)]
922pub enum Decoder2Error<A, B> {
923    /// Error from the first decoder.
924    First(A),
925    /// Error from the second decoder.
926    Second(B),
927}
928
929impl<A, B> fmt::Display for Decoder2Error<A, B>
930where
931    A: fmt::Display,
932    B: fmt::Display,
933{
934    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
935        match self {
936            Self::First(ref e) => write_err!(f, "first decoder error"; e),
937            Self::Second(ref e) => write_err!(f, "second decoder error"; e),
938        }
939    }
940}
941
942#[cfg(feature = "std")]
943impl<A, B> std::error::Error for Decoder2Error<A, B>
944where
945    A: std::error::Error + 'static,
946    B: std::error::Error + 'static,
947{
948    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
949        match self {
950            Self::First(ref e) => Some(e),
951            Self::Second(ref e) => Some(e),
952        }
953    }
954}
955
956/// Error type for [`Decoder3`].
957#[derive(Debug, Clone, PartialEq, Eq)]
958pub enum Decoder3Error<A, B, C> {
959    /// Error from the first decoder.
960    First(A),
961    /// Error from the second decoder.
962    Second(B),
963    /// Error from the third decoder.
964    Third(C),
965}
966
967impl<A, B, C> fmt::Display for Decoder3Error<A, B, C>
968where
969    A: fmt::Display,
970    B: fmt::Display,
971    C: fmt::Display,
972{
973    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
974        match self {
975            Self::First(ref e) => write_err!(f, "first decoder error"; e),
976            Self::Second(ref e) => write_err!(f, "second decoder error"; e),
977            Self::Third(ref e) => write_err!(f, "third decoder error"; e),
978        }
979    }
980}
981
982#[cfg(feature = "std")]
983impl<A, B, C> std::error::Error for Decoder3Error<A, B, C>
984where
985    A: std::error::Error + 'static,
986    B: std::error::Error + 'static,
987    C: std::error::Error + 'static,
988{
989    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
990        match self {
991            Self::First(ref e) => Some(e),
992            Self::Second(ref e) => Some(e),
993            Self::Third(ref e) => Some(e),
994        }
995    }
996}
997
998/// Error type for [`Decoder4`].
999#[derive(Debug, Clone, PartialEq, Eq)]
1000pub enum Decoder4Error<A, B, C, D> {
1001    /// Error from the first decoder.
1002    First(A),
1003    /// Error from the second decoder.
1004    Second(B),
1005    /// Error from the third decoder.
1006    Third(C),
1007    /// Error from the fourth decoder.
1008    Fourth(D),
1009}
1010
1011impl<A, B, C, D> fmt::Display for Decoder4Error<A, B, C, D>
1012where
1013    A: fmt::Display,
1014    B: fmt::Display,
1015    C: fmt::Display,
1016    D: fmt::Display,
1017{
1018    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1019        match self {
1020            Self::First(ref e) => write_err!(f, "first decoder error"; e),
1021            Self::Second(ref e) => write_err!(f, "second decoder error"; e),
1022            Self::Third(ref e) => write_err!(f, "third decoder error"; e),
1023            Self::Fourth(ref e) => write_err!(f, "fourth decoder error"; e),
1024        }
1025    }
1026}
1027
1028#[cfg(feature = "std")]
1029impl<A, B, C, D> std::error::Error for Decoder4Error<A, B, C, D>
1030where
1031    A: std::error::Error + 'static,
1032    B: std::error::Error + 'static,
1033    C: std::error::Error + 'static,
1034    D: std::error::Error + 'static,
1035{
1036    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
1037        match self {
1038            Self::First(ref e) => Some(e),
1039            Self::Second(ref e) => Some(e),
1040            Self::Third(ref e) => Some(e),
1041            Self::Fourth(ref e) => Some(e),
1042        }
1043    }
1044}
1045
1046/// Error type for [`Decoder6`].
1047#[derive(Debug, Clone, PartialEq, Eq)]
1048pub enum Decoder6Error<A, B, C, D, E, F> {
1049    /// Error from the first decoder.
1050    First(A),
1051    /// Error from the second decoder.
1052    Second(B),
1053    /// Error from the third decoder.
1054    Third(C),
1055    /// Error from the fourth decoder.
1056    Fourth(D),
1057    /// Error from the fifth decoder.
1058    Fifth(E),
1059    /// Error from the sixth decoder.
1060    Sixth(F),
1061}
1062
1063impl<A, B, C, D, E, F> fmt::Display for Decoder6Error<A, B, C, D, E, F>
1064where
1065    A: fmt::Display,
1066    B: fmt::Display,
1067    C: fmt::Display,
1068    D: fmt::Display,
1069    E: fmt::Display,
1070    F: fmt::Display,
1071{
1072    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1073        match self {
1074            Self::First(ref e) => write_err!(f, "first decoder error"; e),
1075            Self::Second(ref e) => write_err!(f, "second decoder error"; e),
1076            Self::Third(ref e) => write_err!(f, "third decoder error"; e),
1077            Self::Fourth(ref e) => write_err!(f, "fourth decoder error"; e),
1078            Self::Fifth(ref e) => write_err!(f, "fifth decoder error"; e),
1079            Self::Sixth(ref e) => write_err!(f, "sixth decoder error"; e),
1080        }
1081    }
1082}
1083
1084#[cfg(feature = "std")]
1085impl<A, B, C, D, E, F> std::error::Error for Decoder6Error<A, B, C, D, E, F>
1086where
1087    A: std::error::Error + 'static,
1088    B: std::error::Error + 'static,
1089    C: std::error::Error + 'static,
1090    D: std::error::Error + 'static,
1091    E: std::error::Error + 'static,
1092    F: std::error::Error + 'static,
1093{
1094    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
1095        match self {
1096            Self::First(ref e) => Some(e),
1097            Self::Second(ref e) => Some(e),
1098            Self::Third(ref e) => Some(e),
1099            Self::Fourth(ref e) => Some(e),
1100            Self::Fifth(ref e) => Some(e),
1101            Self::Sixth(ref e) => Some(e),
1102        }
1103    }
1104}
1105
1106#[cfg(test)]
1107mod tests {
1108    #[cfg(feature = "alloc")]
1109    use alloc::vec;
1110    #[cfg(feature = "alloc")]
1111    use alloc::vec::Vec;
1112    #[cfg(feature = "alloc")]
1113    use core::iter;
1114    #[cfg(feature = "std")]
1115    use std::io::Cursor;
1116
1117    use super::*;
1118
1119    // Stress test the push_bytes impl by passing in a single byte slice repeatedly.
1120    macro_rules! check_decode_one_byte_at_a_time {
1121        ($decoder:expr; $($test_name:ident, $want:expr, $array:expr);* $(;)?) => {
1122            $(
1123                #[test]
1124                #[allow(non_snake_case)]
1125                fn $test_name() {
1126                    let mut decoder = $decoder;
1127
1128                    for (i, _) in $array.iter().enumerate() {
1129                        if i < $array.len() - 1 {
1130                            let mut p = &$array[i..i+1];
1131                            assert!(decoder.push_bytes(&mut p).unwrap());
1132                        } else {
1133                            // last byte: `push_bytes` should return false since no more bytes required.
1134                            let mut p = &$array[i..];
1135                            assert!(!decoder.push_bytes(&mut p).unwrap());
1136                        }
1137                    }
1138
1139                    let got = decoder.end().unwrap();
1140                    assert_eq!(got, $want);
1141                }
1142            )*
1143
1144        }
1145    }
1146
1147    check_decode_one_byte_at_a_time! {
1148        CompactSizeDecoder::new_with_limit(0xF0F0_F0F0);
1149        decode_compact_size_0x10, 0x10, [0x10];
1150        decode_compact_size_0xFC, 0xFC, [0xFC];
1151        decode_compact_size_0xFD, 0xFD, [0xFD, 0xFD, 0x00];
1152        decode_compact_size_0x100, 0x100, [0xFD, 0x00, 0x01];
1153        decode_compact_size_0xFFF, 0x0FFF, [0xFD, 0xFF, 0x0F];
1154        decode_compact_size_0x0F0F_0F0F, 0x0F0F_0F0F, [0xFE, 0xF, 0xF, 0xF, 0xF];
1155    }
1156
1157    #[test]
1158    #[cfg(target_pointer_width = "64")]
1159    #[allow(non_snake_case)]
1160    fn decode_compact_size_0xF0F0_F0F0_F0E0() {
1161        let mut decoder = CompactSizeDecoder::new_with_limit(0xF0F0_F0F0_F0EF);
1162        let array = [0xFF, 0xE0, 0xF0, 0xF0, 0xF0, 0xF0, 0xF0, 0, 0];
1163
1164        for (i, _) in array.iter().enumerate() {
1165            if i < array.len() - 1 {
1166                let mut p = &array[i..=i];
1167                assert!(decoder.push_bytes(&mut p).unwrap());
1168            } else {
1169                // last byte: `push_bytes` should return false since no more bytes required.
1170                let mut p = &array[i..];
1171                assert!(!decoder.push_bytes(&mut p).unwrap());
1172            }
1173        }
1174
1175        let got = decoder.end().unwrap();
1176        assert_eq!(got, 0xF0F0_F0F0_F0E0);
1177    }
1178
1179    #[test]
1180    #[cfg(feature = "alloc")]
1181    fn compact_size_zero() {
1182        // Zero (eg for an empty vector) with a couple of arbitrary extra bytes.
1183        let encoded = alloc::vec![0x00, 0xFF, 0xFF];
1184
1185        let mut slice = encoded.as_slice();
1186        let mut decoder = CompactSizeDecoder::new();
1187        assert!(!decoder.push_bytes(&mut slice).unwrap());
1188
1189        let got = decoder.end().unwrap();
1190        assert_eq!(got, 0);
1191    }
1192
1193    #[cfg(feature = "alloc")]
1194    fn two_fifty_six_bytes_encoded() -> Vec<u8> {
1195        let data = [0xff; 256];
1196        let mut v = Vec::with_capacity(259);
1197
1198        v.extend_from_slice(&[0xFD, 0x00, 0x01]); // 256 encoded as a  compact size.
1199        v.extend_from_slice(&data);
1200        v
1201    }
1202
1203    #[cfg(feature = "alloc")]
1204    check_decode_one_byte_at_a_time! {
1205        ByteVecDecoder::default();
1206            decode_byte_vec, alloc::vec![0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef],
1207        [0x08, 0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef];
1208            decode_byte_vec_multi_byte_length_prefix, [0xff; 256], two_fifty_six_bytes_encoded();
1209    }
1210
1211    #[test]
1212    #[cfg(feature = "alloc")]
1213    fn byte_vec_decoder_reserves_in_batches() {
1214        // A small number of extra bytes so we extend exactly by the remainder
1215        // instead of another full batch.
1216        let tail_length: usize = 11;
1217
1218        let total_len = MAX_VECTOR_ALLOCATE + tail_length;
1219        let total_len_le = u32::try_from(total_len).expect("total_len fits u32").to_le_bytes();
1220        let mut decoder = ByteVecDecoder::new();
1221
1222        let mut prefix = vec![0xFE]; // total_len_le is a compact size of four bytes.
1223        prefix.extend_from_slice(&total_len_le);
1224        prefix.push(0xAA);
1225        let mut prefix_slice = prefix.as_slice();
1226        decoder.push_bytes(&mut prefix_slice).expect("length plus first element");
1227        assert!(prefix_slice.is_empty());
1228
1229        assert_eq!(decoder.buffer.capacity(), MAX_VECTOR_ALLOCATE);
1230        assert_eq!(decoder.buffer.len(), 1);
1231        assert_eq!(decoder.buffer[0], 0xAA);
1232
1233        let fill = vec![0xBB; MAX_VECTOR_ALLOCATE - 1];
1234        let mut fill_slice = fill.as_slice();
1235        decoder.push_bytes(&mut fill_slice).expect("fills to batch boundary, full capacity");
1236        assert!(fill_slice.is_empty());
1237
1238        assert_eq!(decoder.buffer.capacity(), MAX_VECTOR_ALLOCATE);
1239        assert_eq!(decoder.buffer.len(), MAX_VECTOR_ALLOCATE);
1240        assert_eq!(decoder.buffer[MAX_VECTOR_ALLOCATE - 1], 0xBB);
1241
1242        let mut tail = vec![0xCC];
1243        tail.extend([0xDD].repeat(tail_length - 1));
1244        let mut tail_slice = tail.as_slice();
1245        decoder.push_bytes(&mut tail_slice).expect("fills the remaining bytes");
1246        assert!(tail_slice.is_empty());
1247
1248        assert_eq!(decoder.buffer.capacity(), MAX_VECTOR_ALLOCATE + tail_length);
1249        assert_eq!(decoder.buffer.len(), total_len);
1250        assert_eq!(decoder.buffer[MAX_VECTOR_ALLOCATE], 0xCC);
1251
1252        let result = decoder.end().unwrap();
1253        assert_eq!(result.len(), total_len);
1254        assert_eq!(result[total_len - 1], 0xDD);
1255    }
1256
1257    #[cfg(feature = "alloc")]
1258    #[derive(Clone, Debug, PartialEq, Eq)]
1259    pub struct Inner(u32);
1260
1261    /// The decoder for the [`Inner`] type.
1262    #[cfg(feature = "alloc")]
1263    pub struct InnerDecoder(ArrayDecoder<4>);
1264
1265    #[cfg(feature = "alloc")]
1266    impl Decoder for InnerDecoder {
1267        type Output = Inner;
1268        type Error = UnexpectedEofError;
1269
1270        fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
1271            self.0.push_bytes(bytes)
1272        }
1273
1274        fn end(self) -> Result<Self::Output, Self::Error> {
1275            let n = u32::from_le_bytes(self.0.end()?);
1276            Ok(Inner(n))
1277        }
1278
1279        fn read_limit(&self) -> usize { self.0.read_limit() }
1280    }
1281
1282    #[cfg(feature = "alloc")]
1283    impl Decodable for Inner {
1284        type Decoder = InnerDecoder;
1285        fn decoder() -> Self::Decoder { InnerDecoder(ArrayDecoder::<4>::new()) }
1286    }
1287
1288    #[cfg(feature = "alloc")]
1289    #[derive(Clone, Debug, PartialEq, Eq)]
1290    pub struct Test(Vec<Inner>);
1291
1292    /// The decoder for the [`Test`] type.
1293    #[cfg(feature = "alloc")]
1294    #[derive(Default)]
1295    pub struct TestDecoder(VecDecoder<Inner>);
1296
1297    #[cfg(feature = "alloc")]
1298    impl Decoder for TestDecoder {
1299        type Output = Test;
1300        type Error = VecDecoderError<UnexpectedEofError>;
1301
1302        fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<bool, Self::Error> {
1303            self.0.push_bytes(bytes)
1304        }
1305
1306        fn end(self) -> Result<Self::Output, Self::Error> {
1307            let v = self.0.end()?;
1308            Ok(Test(v))
1309        }
1310
1311        fn read_limit(&self) -> usize { self.0.read_limit() }
1312    }
1313
1314    #[cfg(feature = "alloc")]
1315    impl Decodable for Test {
1316        type Decoder = TestDecoder;
1317        fn decoder() -> Self::Decoder { TestDecoder(VecDecoder::new()) }
1318    }
1319
1320    #[test]
1321    #[cfg(feature = "alloc")]
1322    fn vec_decoder_empty() {
1323        // Empty with a couple of arbitrary extra bytes.
1324        let encoded = vec![0x00, 0xFF, 0xFF];
1325
1326        let mut slice = encoded.as_slice();
1327        let mut decoder = Test::decoder();
1328        assert!(!decoder.push_bytes(&mut slice).unwrap());
1329
1330        let got = decoder.end().unwrap();
1331        let want = Test(vec![]);
1332
1333        assert_eq!(got, want);
1334    }
1335
1336    #[test]
1337    #[cfg(feature = "alloc")]
1338    fn vec_decoder_one_item() {
1339        let encoded = vec![0x01, 0xEF, 0xBE, 0xAD, 0xDE];
1340
1341        let mut slice = encoded.as_slice();
1342        let mut decoder = Test::decoder();
1343        decoder.push_bytes(&mut slice).unwrap();
1344
1345        let got = decoder.end().unwrap();
1346        let want = Test(vec![Inner(0xDEAD_BEEF)]);
1347
1348        assert_eq!(got, want);
1349    }
1350
1351    #[test]
1352    #[cfg(feature = "alloc")]
1353    fn vec_decoder_two_items() {
1354        let encoded = vec![0x02, 0xEF, 0xBE, 0xAD, 0xDE, 0xBE, 0xBA, 0xFE, 0xCA];
1355
1356        let mut slice = encoded.as_slice();
1357        let mut decoder = Test::decoder();
1358        decoder.push_bytes(&mut slice).unwrap();
1359
1360        let got = decoder.end().unwrap();
1361        let want = Test(vec![Inner(0xDEAD_BEEF), Inner(0xCAFE_BABE)]);
1362
1363        assert_eq!(got, want);
1364    }
1365
1366    #[test]
1367    #[cfg(feature = "alloc")]
1368    fn vec_decoder_reserves_in_batches() {
1369        // A small number of extra elements so we extend exactly by the remainder
1370        // instead of another full batch.
1371        let tail_length: usize = 11;
1372
1373        let element_size = core::mem::size_of::<Inner>();
1374        let batch_length = MAX_VECTOR_ALLOCATE / element_size;
1375        assert!(batch_length > 1);
1376        let total_len = batch_length + tail_length;
1377        let total_len_le = u32::try_from(total_len).expect("total_len fits u32").to_le_bytes();
1378        let mut decoder = Test::decoder();
1379
1380        let mut prefix = vec![0xFE]; // total_len_le is a compact size of four bytes.
1381        prefix.extend_from_slice(&total_len_le);
1382        prefix.extend_from_slice(&0xAA_u32.to_le_bytes());
1383        let mut prefix_slice = prefix.as_slice();
1384        decoder.push_bytes(&mut prefix_slice).expect("length plus first element");
1385        assert!(prefix_slice.is_empty());
1386
1387        assert_eq!(decoder.0.buffer.capacity(), batch_length);
1388        assert_eq!(decoder.0.buffer.len(), 1);
1389        assert_eq!(decoder.0.buffer[0], Inner(0xAA));
1390
1391        let fill = 0xBB_u32.to_le_bytes().repeat(batch_length - 1);
1392        let mut fill_slice = fill.as_slice();
1393        decoder.push_bytes(&mut fill_slice).expect("fills to batch boundary, full capacity");
1394        assert!(fill_slice.is_empty());
1395
1396        assert_eq!(decoder.0.buffer.capacity(), batch_length);
1397        assert_eq!(decoder.0.buffer.len(), batch_length);
1398        assert_eq!(decoder.0.buffer[batch_length - 1], Inner(0xBB));
1399
1400        let mut tail = 0xCC_u32.to_le_bytes().to_vec();
1401        tail.extend(0xDD_u32.to_le_bytes().repeat(tail_length - 1));
1402        let mut tail_slice = tail.as_slice();
1403        decoder.push_bytes(&mut tail_slice).expect("fills the remaining bytes");
1404        assert!(tail_slice.is_empty());
1405
1406        assert_eq!(decoder.0.buffer.capacity(), batch_length + tail_length);
1407        assert_eq!(decoder.0.buffer.len(), total_len);
1408        assert_eq!(decoder.0.buffer[batch_length], Inner(0xCC));
1409
1410        let Test(result) = decoder.end().unwrap();
1411        assert_eq!(result.len(), total_len);
1412        assert_eq!(result[total_len - 1], Inner(0xDD));
1413    }
1414
1415    #[cfg(feature = "alloc")]
1416    fn two_fifty_six_elements() -> Test {
1417        Test(iter::repeat(Inner(0xDEAD_BEEF)).take(256).collect())
1418    }
1419
1420    #[cfg(feature = "alloc")]
1421    fn two_fifty_six_elements_encoded() -> Vec<u8> {
1422        [0xFD, 0x00, 0x01] // 256 encoded as a  compact size.
1423            .into_iter()
1424            .chain(iter::repeat(0xDEAD_BEEF_u32.to_le_bytes()).take(256).flatten())
1425            .collect()
1426    }
1427
1428    #[cfg(feature = "alloc")]
1429    check_decode_one_byte_at_a_time! {
1430        TestDecoder::default();
1431            decode_vec, Test(vec![Inner(0xDEAD_BEEF), Inner(0xCAFE_BABE)]),
1432        vec![0x02, 0xEF, 0xBE, 0xAD, 0xDE, 0xBE, 0xBA, 0xFE, 0xCA];
1433            decode_vec_multi_byte_length_prefix, two_fifty_six_elements(), two_fifty_six_elements_encoded();
1434    }
1435
1436    #[test]
1437    #[cfg(feature = "alloc")]
1438    fn vec_decoder_one_item_plus_more_data() {
1439        // One u32 plus some other bytes.
1440        let encoded = vec![0x01, 0xEF, 0xBE, 0xAD, 0xDE, 0xff, 0xff, 0xff, 0xff];
1441
1442        let mut slice = encoded.as_slice();
1443
1444        let mut decoder = Test::decoder();
1445        decoder.push_bytes(&mut slice).unwrap();
1446
1447        let got = decoder.end().unwrap();
1448        let want = Test(vec![Inner(0xDEAD_BEEF)]);
1449
1450        assert_eq!(got, want);
1451    }
1452
1453    #[cfg(feature = "std")]
1454    #[test]
1455    fn decode_vec_from_read_unbuffered_success() {
1456        let encoded = [0x01, 0xEF, 0xBE, 0xAD, 0xDE, 0xff, 0xff, 0xff, 0xff];
1457        let mut cursor = Cursor::new(&encoded);
1458
1459        let got = crate::decode_from_read_unbuffered::<Test, _>(&mut cursor).unwrap();
1460        assert_eq!(cursor.position(), 5);
1461
1462        let want = Test(vec![Inner(0xDEAD_BEEF)]);
1463        assert_eq!(got, want);
1464    }
1465}
bitcoin_consensus_encoding/decode/decoders.rs

bitcoin_consensus_encoding/decode/
decoders.rs
