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

bitcoin_consensus_encoding/decode/
decoders.rs
