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;
7use core::{fmt, mem};
8
9#[cfg(feature = "alloc")]
10use super::Decode;
11use super::{Decoder, DecoderStatus};
12#[cfg(feature = "alloc")]
13use crate::compact_size::CompactSizeDecoder;
14#[cfg(feature = "alloc")]
15use crate::error::{
16    ByteVecDecoderError, ByteVecDecoderErrorInner, VecDecoderError, VecDecoderErrorInner,
17};
18use crate::{Decoder2Error, Decoder3Error, Decoder4Error, Decoder6Error, UnexpectedEofError};
19
20/// Maximum amount of memory (in bytes) to allocate at once when deserializing vectors.
21#[cfg(feature = "alloc")]
22const MAX_VECTOR_ALLOCATE: usize = 1_000_000;
23
24/// Maximum number of elements in a decoded vector.
25///
26/// This is an anti-DoS limit based on Bitcoin's 4MB block weight limit.
27/// Applied to both byte vectors [`ByteVecDecoder`] and typed vectors [`VecDecoder`],
28/// regardless of whether the element type is a single byte or a larger structure.
29#[cfg(feature = "alloc")]
30const MAX_VEC_SIZE: usize = 4_000_000;
31
32/// A decoder that decodes a byte vector.
33///
34/// The encoding is expected to start with the number of encoded bytes (length prefix).
35#[cfg(feature = "alloc")]
36#[derive(Debug, Clone)]
37pub struct ByteVecDecoder {
38    prefix_decoder: Option<CompactSizeDecoder>,
39    buffer: Vec<u8>,
40    bytes_expected: usize,
41    bytes_written: usize,
42}
43
44#[cfg(feature = "alloc")]
45impl ByteVecDecoder {
46    /// Constructs a new byte decoder with the default limit of 4,000,000 bytes.
47    pub const fn new() -> Self { Self::new_with_limit(MAX_VEC_SIZE) }
48
49    /// Constructs a new byte decoder with a custom limit of bytes.
50    pub const fn new_with_limit(limit: usize) -> Self {
51        Self {
52            prefix_decoder: Some(CompactSizeDecoder::new_with_limit(limit)),
53            buffer: Vec::new(),
54            bytes_expected: 0,
55            bytes_written: 0,
56        }
57    }
58
59    /// Reserves capacity for byte vectors in batches.
60    ///
61    /// Reserves up to `MAX_VECTOR_ALLOCATE` bytes when the buffer has no remaining capacity.
62    ///
63    /// Documentation adapted from Bitcoin Core:
64    ///
65    /// > For `DoS` prevention, do not blindly allocate as much as the stream claims to contain.
66    /// > Instead, allocate in ~1 MB batches, so that an attacker actually needs to provide X MB of
67    /// > data to make us allocate X+1 MB of memory.
68    ///
69    /// ref: <https://github.com/bitcoin/bitcoin/blob/72511fd02e72b74be11273e97bd7911786a82e54/src/serialize.h#L669C2-L672C1>
70    fn reserve(&mut self) {
71        if self.buffer.len() == self.buffer.capacity() {
72            let bytes_remaining = self.bytes_expected - self.bytes_written;
73            let batch_size = bytes_remaining.min(MAX_VECTOR_ALLOCATE);
74            self.buffer.reserve_exact(batch_size);
75        }
76    }
77}
78
79#[cfg(feature = "alloc")]
80impl Default for ByteVecDecoder {
81    fn default() -> Self { Self::new() }
82}
83
84#[cfg(feature = "alloc")]
85impl Decoder for ByteVecDecoder {
86    type Output = Vec<u8>;
87    type Error = ByteVecDecoderError;
88
89    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<DecoderStatus, Self::Error> {
90        use ByteVecDecoderError as E;
91        use ByteVecDecoderErrorInner as Inner;
92
93        if let Some(mut decoder) = self.prefix_decoder.take() {
94            if decoder.push_bytes(bytes).map_err(|e| E(Inner::LengthPrefixDecode(e)))?.needs_more()
95            {
96                self.prefix_decoder = Some(decoder);
97                return Ok(DecoderStatus::NeedsMore);
98            }
99            self.bytes_expected = decoder.end().map_err(|e| E(Inner::LengthPrefixDecode(e)))?;
100            self.prefix_decoder = None;
101
102            // For DoS prevention, let's not allocate all memory upfront.
103        }
104
105        self.reserve();
106
107        let remaining = self.bytes_expected - self.bytes_written;
108        let available_capacity = self.buffer.capacity() - self.buffer.len();
109        let copy_len = bytes.len().min(remaining).min(available_capacity);
110
111        self.buffer.extend_from_slice(&bytes[..copy_len]);
112        self.bytes_written += copy_len;
113        *bytes = &bytes[copy_len..];
114
115        if self.bytes_written < self.bytes_expected {
116            Ok(DecoderStatus::NeedsMore)
117        } else {
118            Ok(DecoderStatus::Ready)
119        }
120    }
121
122    fn end(self) -> Result<Self::Output, Self::Error> {
123        use ByteVecDecoderError as E;
124        use ByteVecDecoderErrorInner as Inner;
125
126        if let Some(ref prefix_decoder) = self.prefix_decoder {
127            return Err(E(Inner::UnexpectedEof(UnexpectedEofError {
128                missing: prefix_decoder.read_limit(),
129            })));
130        }
131
132        if self.bytes_written == self.bytes_expected {
133            Ok(self.buffer)
134        } else {
135            Err(E(Inner::UnexpectedEof(UnexpectedEofError {
136                missing: self.bytes_expected - self.bytes_written,
137            })))
138        }
139    }
140
141    fn read_limit(&self) -> usize {
142        self.prefix_decoder
143            .as_ref()
144            .map_or(self.bytes_expected - self.bytes_written, CompactSizeDecoder::read_limit)
145    }
146}
147
148/// A decoder that decodes a vector of `T`s.
149///
150/// The vector encoding must start with the number of items in the vector, encoded as a compact
151/// size.
152#[cfg(feature = "alloc")]
153pub struct VecDecoder<T: Decode> {
154    prefix_decoder: Option<CompactSizeDecoder>,
155    length: usize,
156    buffer: Vec<T>,
157    decoder: Option<<T as Decode>::Decoder>,
158}
159
160#[cfg(feature = "alloc")]
161impl<T: Decode> fmt::Debug for VecDecoder<T>
162where
163    T::Decoder: fmt::Debug,
164{
165    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
166        f.debug_struct("VecDecoder")
167            .field("prefix_decoder", &self.prefix_decoder)
168            .field("length", &self.length)
169            // Print the count rather than contents to avoid requiring `T: Debug`.
170            .field("buffer_len", &self.buffer.len())
171            .field("decoder", &self.decoder)
172            .finish()
173    }
174}
175
176#[cfg(feature = "alloc")]
177impl<T: Decode> Clone for VecDecoder<T>
178where
179    T: Clone,
180    T::Decoder: Clone,
181{
182    fn clone(&self) -> Self {
183        Self {
184            prefix_decoder: self.prefix_decoder.clone(),
185            length: self.length,
186            buffer: self.buffer.clone(),
187            decoder: self.decoder.clone(),
188        }
189    }
190}
191
192#[cfg(feature = "alloc")]
193impl<T: Decode> VecDecoder<T> {
194    /// Constructs a new typed vector decoder with the default limit of 4,000,000 elements.
195    pub const fn new() -> Self { Self::new_with_limit(MAX_VEC_SIZE) }
196
197    /// Constructs a new typed vector decoder with a custom limit of elements.
198    pub const fn new_with_limit(limit: usize) -> Self {
199        Self {
200            prefix_decoder: Some(CompactSizeDecoder::new_with_limit(limit)),
201            length: 0,
202            buffer: Vec::new(),
203            decoder: None,
204        }
205    }
206
207    /// Reserves capacity for typed vectors in batches.
208    ///
209    /// Calculates how many elements of type `T` fit within `MAX_VECTOR_ALLOCATE` bytes and reserves
210    /// up to that amount when the buffer reaches capacity.
211    ///
212    /// Documentation adapted from Bitcoin Core:
213    ///
214    /// > For `DoS` prevention, do not blindly allocate as much as the stream claims to contain.
215    /// > Instead, allocate in ~1 MB batches, so that an attacker actually needs to provide X MB of
216    /// > data to make us allocate X+1 MB of memory.
217    ///
218    /// ref: <https://github.com/bitcoin/bitcoin/blob/72511fd02e72b74be11273e97bd7911786a82e54/src/serialize.h#L669C2-L672C1>
219    fn reserve(&mut self) {
220        if self.buffer.len() == self.buffer.capacity() {
221            let elements_remaining = self.length - self.buffer.len();
222            let element_size = mem::size_of::<T>().max(1);
223            let batch_elements = MAX_VECTOR_ALLOCATE / element_size;
224            let elements_to_reserve = elements_remaining.min(batch_elements);
225            self.buffer.reserve_exact(elements_to_reserve);
226        }
227    }
228}
229
230#[cfg(feature = "alloc")]
231impl<T: Decode> Default for VecDecoder<T> {
232    fn default() -> Self { Self::new() }
233}
234
235#[cfg(feature = "alloc")]
236impl<T: Decode> Decoder for VecDecoder<T> {
237    type Output = Vec<T>;
238    type Error = VecDecoderError<<<T as Decode>::Decoder as Decoder>::Error>;
239
240    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<DecoderStatus, Self::Error> {
241        use VecDecoderError as E;
242        use VecDecoderErrorInner as Inner;
243
244        if let Some(mut decoder) = self.prefix_decoder.take() {
245            if decoder.push_bytes(bytes).map_err(|e| E(Inner::LengthPrefixDecode(e)))?.needs_more()
246            {
247                self.prefix_decoder = Some(decoder);
248                return Ok(DecoderStatus::NeedsMore);
249            }
250            self.length = decoder.end().map_err(|e| E(Inner::LengthPrefixDecode(e)))?;
251            if self.length == 0 {
252                return Ok(DecoderStatus::Ready);
253            }
254
255            self.prefix_decoder = None;
256
257            // For DoS prevention, let's not allocate all memory upfront.
258        }
259
260        while !bytes.is_empty() {
261            self.reserve();
262
263            let mut decoder = self.decoder.take().unwrap_or_else(T::decoder);
264
265            if decoder.push_bytes(bytes).map_err(|e| E(Inner::Item(e)))?.needs_more() {
266                self.decoder = Some(decoder);
267                return Ok(DecoderStatus::NeedsMore);
268            }
269            let item = decoder.end().map_err(|e| E(Inner::Item(e)))?;
270            self.buffer.push(item);
271
272            if self.buffer.len() == self.length {
273                return Ok(DecoderStatus::Ready);
274            }
275        }
276
277        if self.buffer.len() == self.length {
278            Ok(DecoderStatus::Ready)
279        } else {
280            Ok(DecoderStatus::NeedsMore)
281        }
282    }
283
284    fn end(self) -> Result<Self::Output, Self::Error> {
285        use VecDecoderErrorInner as E;
286
287        if let Some(ref prefix_decoder) = self.prefix_decoder {
288            return Err(VecDecoderError(E::UnexpectedEof(UnexpectedEofError {
289                missing: prefix_decoder.read_limit(),
290            })));
291        }
292
293        if self.buffer.len() == self.length {
294            Ok(self.buffer)
295        } else {
296            Err(VecDecoderError(E::UnexpectedEof(UnexpectedEofError {
297                missing: self.length - self.buffer.len(),
298            })))
299        }
300    }
301
302    fn read_limit(&self) -> usize {
303        match (&self.prefix_decoder, &self.decoder) {
304            (Some(pd), _) => pd.read_limit(),
305            (None, Some(d)) => d.read_limit(),
306            (None, None) if self.buffer.len() == self.length => 0, // Totally done
307            (None, None) => {
308                let items_left_to_decode = self.length - self.buffer.len();
309                // This could be inaccurate (eg 1 for a `ByteVecDecoder`) but its the best we can do.
310                let limit_per_decoder = T::decoder().read_limit();
311                items_left_to_decode * limit_per_decoder
312            }
313        }
314    }
315}
316
317/// A decoder that expects exactly N bytes and returns them as an array.
318#[derive(Debug, Clone)]
319pub struct ArrayDecoder<const N: usize> {
320    buffer: [u8; N],
321    bytes_written: usize,
322}
323
324impl<const N: usize> ArrayDecoder<N> {
325    /// Constructs a new array decoder that expects exactly N bytes.
326    pub const fn new() -> Self { Self { buffer: [0; N], bytes_written: 0 } }
327}
328
329impl<const N: usize> Default for ArrayDecoder<N> {
330    fn default() -> Self { Self::new() }
331}
332
333impl<const N: usize> Decoder for ArrayDecoder<N> {
334    type Output = [u8; N];
335    type Error = UnexpectedEofError;
336
337    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<DecoderStatus, Self::Error> {
338        let remaining_space = N - self.bytes_written;
339        let copy_len = bytes.len().min(remaining_space);
340
341        if copy_len > 0 {
342            self.buffer[self.bytes_written..self.bytes_written + copy_len]
343                .copy_from_slice(&bytes[..copy_len]);
344            self.bytes_written += copy_len;
345            // Advance the slice reference to consume the bytes.
346            *bytes = &bytes[copy_len..];
347        }
348
349        if self.bytes_written < N {
350            Ok(DecoderStatus::NeedsMore)
351        } else {
352            Ok(DecoderStatus::Ready)
353        }
354    }
355
356    #[inline]
357    fn end(self) -> Result<Self::Output, Self::Error> {
358        if self.bytes_written == N {
359            Ok(self.buffer)
360        } else {
361            Err(UnexpectedEofError { missing: N - self.bytes_written })
362        }
363    }
364
365    #[inline]
366    fn read_limit(&self) -> usize { N - self.bytes_written }
367}
368
369/// A decoder which wraps two inner decoders and returns the output of both.
370#[derive(Default)]
371pub struct Decoder2<A, B>
372where
373    A: Decoder,
374    B: Decoder,
375{
376    state: Decoder2State<A, B>,
377}
378
379enum Decoder2State<A: Decoder, B: Decoder> {
380    /// Decoding the first decoder, with second decoder waiting.
381    First(A, B),
382    /// Decoding the second decoder, with the first result stored.
383    Second(A::Output, B),
384    /// Decoder has failed and cannot be used again.
385    Errored,
386}
387
388// the `#[default]` attribute may only be used on unit enum variants
389impl<A: Decoder + Default, B: Decoder + Default> Default for Decoder2State<A, B> {
390    fn default() -> Self { Self::First(A::default(), B::default()) }
391}
392
393impl<A, B> Decoder2<A, B>
394where
395    A: Decoder,
396    B: Decoder,
397{
398    /// Constructs a new composite decoder.
399    pub const fn new(first: A, second: B) -> Self {
400        Self { state: Decoder2State::First(first, second) }
401    }
402}
403
404impl<A, B> fmt::Debug for Decoder2<A, B>
405where
406    A: Decoder + fmt::Debug,
407    B: Decoder + fmt::Debug,
408    A::Output: fmt::Debug,
409{
410    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
411        match &self.state {
412            Decoder2State::First(a, b) => f.debug_tuple("First").field(a).field(b).finish(),
413            Decoder2State::Second(out, b) => f.debug_tuple("Second").field(out).field(b).finish(),
414            Decoder2State::Errored => write!(f, "Errored"),
415        }
416    }
417}
418
419impl<A, B> Clone for Decoder2<A, B>
420where
421    A: Decoder + Clone,
422    B: Decoder + Clone,
423    A::Output: Clone,
424{
425    fn clone(&self) -> Self {
426        let state = match &self.state {
427            Decoder2State::First(a, b) => Decoder2State::First(a.clone(), b.clone()),
428            Decoder2State::Second(out, b) => Decoder2State::Second(out.clone(), b.clone()),
429            Decoder2State::Errored => Decoder2State::Errored,
430        };
431        Self { state }
432    }
433}
434
435impl<A, B> Decoder for Decoder2<A, B>
436where
437    A: Decoder,
438    B: Decoder,
439{
440    type Output = (A::Output, B::Output);
441    type Error = Decoder2Error<A::Error, B::Error>;
442
443    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<DecoderStatus, Self::Error> {
444        loop {
445            match &mut self.state {
446                Decoder2State::First(first_decoder, _) => {
447                    if first_decoder.push_bytes(bytes).map_err(Decoder2Error::First)?.needs_more() {
448                        // First decoder wants more data.
449                        return Ok(DecoderStatus::NeedsMore);
450                    }
451
452                    // First decoder is complete, transition to second.
453                    // If the first decoder fails, the composite decoder
454                    // remains in an Errored state.
455                    match mem::replace(&mut self.state, Decoder2State::Errored) {
456                        Decoder2State::First(first, second) => {
457                            let first_result = first.end().map_err(Decoder2Error::First)?;
458                            self.state = Decoder2State::Second(first_result, second);
459                        }
460                        _ => unreachable!("we know we're in First state"),
461                    }
462                }
463                Decoder2State::Second(_, second_decoder) => {
464                    return second_decoder.push_bytes(bytes).map_err(|error| {
465                        self.state = Decoder2State::Errored;
466                        Decoder2Error::Second(error)
467                    });
468                }
469                Decoder2State::Errored => {
470                    panic!("use of failed decoder");
471                }
472            }
473        }
474    }
475
476    #[inline]
477    fn end(self) -> Result<Self::Output, Self::Error> {
478        match self.state {
479            Decoder2State::First(first_decoder, second_decoder) => {
480                // This branch is most likely an error since the decoder
481                // never got to the second one. But letting the error bubble
482                // up naturally from the child decoders.
483                let first_result = first_decoder.end().map_err(Decoder2Error::First)?;
484                let second_result = second_decoder.end().map_err(Decoder2Error::Second)?;
485                Ok((first_result, second_result))
486            }
487            Decoder2State::Second(first_result, second_decoder) => {
488                let second_result = second_decoder.end().map_err(Decoder2Error::Second)?;
489                Ok((first_result, second_result))
490            }
491            Decoder2State::Errored => {
492                panic!("use of failed decoder");
493            }
494        }
495    }
496
497    #[inline]
498    fn read_limit(&self) -> usize {
499        match &self.state {
500            Decoder2State::First(first_decoder, second_decoder) =>
501                first_decoder.read_limit() + second_decoder.read_limit(),
502            Decoder2State::Second(_, second_decoder) => second_decoder.read_limit(),
503            Decoder2State::Errored => 0,
504        }
505    }
506}
507
508/// A decoder which decodes three objects, one after the other.
509#[derive(Default)]
510pub struct Decoder3<A, B, C>
511where
512    A: Decoder,
513    B: Decoder,
514    C: Decoder,
515{
516    inner: Decoder2<Decoder2<A, B>, C>,
517}
518
519impl<A, B, C> Decoder3<A, B, C>
520where
521    A: Decoder,
522    B: Decoder,
523    C: Decoder,
524{
525    /// Constructs a new composite decoder.
526    pub const fn new(dec_1: A, dec_2: B, dec_3: C) -> Self {
527        Self { inner: Decoder2::new(Decoder2::new(dec_1, dec_2), dec_3) }
528    }
529}
530
531impl<A, B, C> fmt::Debug for Decoder3<A, B, C>
532where
533    A: Decoder + fmt::Debug,
534    B: Decoder + fmt::Debug,
535    C: Decoder + fmt::Debug,
536    A::Output: fmt::Debug,
537    B::Output: fmt::Debug,
538{
539    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { self.inner.fmt(f) }
540}
541
542impl<A, B, C> Clone for Decoder3<A, B, C>
543where
544    A: Decoder + Clone,
545    B: Decoder + Clone,
546    C: Decoder + Clone,
547    A::Output: Clone,
548    B::Output: Clone,
549{
550    fn clone(&self) -> Self { Self { inner: self.inner.clone() } }
551}
552
553impl<A, B, C> Decoder for Decoder3<A, B, C>
554where
555    A: Decoder,
556    B: Decoder,
557    C: Decoder,
558{
559    type Output = (A::Output, B::Output, C::Output);
560    type Error = Decoder3Error<A::Error, B::Error, C::Error>;
561
562    #[inline]
563    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<DecoderStatus, Self::Error> {
564        self.inner.push_bytes(bytes).map_err(|error| match error {
565            Decoder2Error::First(Decoder2Error::First(a)) => Decoder3Error::First(a),
566            Decoder2Error::First(Decoder2Error::Second(b)) => Decoder3Error::Second(b),
567            Decoder2Error::Second(c) => Decoder3Error::Third(c),
568        })
569    }
570
571    #[inline]
572    fn end(self) -> Result<Self::Output, Self::Error> {
573        let result = self.inner.end().map_err(|error| match error {
574            Decoder2Error::First(Decoder2Error::First(a)) => Decoder3Error::First(a),
575            Decoder2Error::First(Decoder2Error::Second(b)) => Decoder3Error::Second(b),
576            Decoder2Error::Second(c) => Decoder3Error::Third(c),
577        })?;
578
579        let ((first, second), third) = result;
580        Ok((first, second, third))
581    }
582
583    #[inline]
584    fn read_limit(&self) -> usize { self.inner.read_limit() }
585}
586
587/// A decoder which decodes four objects, one after the other.
588#[derive(Default)]
589pub struct Decoder4<A, B, C, D>
590where
591    A: Decoder,
592    B: Decoder,
593    C: Decoder,
594    D: Decoder,
595{
596    inner: Decoder2<Decoder2<A, B>, Decoder2<C, D>>,
597}
598
599impl<A, B, C, D> Decoder4<A, B, C, D>
600where
601    A: Decoder,
602    B: Decoder,
603    C: Decoder,
604    D: Decoder,
605{
606    /// Constructs a new composite decoder.
607    pub const fn new(dec_1: A, dec_2: B, dec_3: C, dec_4: D) -> Self {
608        Self { inner: Decoder2::new(Decoder2::new(dec_1, dec_2), Decoder2::new(dec_3, dec_4)) }
609    }
610}
611
612impl<A, B, C, D> fmt::Debug for Decoder4<A, B, C, D>
613where
614    A: Decoder + fmt::Debug,
615    B: Decoder + fmt::Debug,
616    C: Decoder + fmt::Debug,
617    D: Decoder + fmt::Debug,
618    A::Output: fmt::Debug,
619    B::Output: fmt::Debug,
620    C::Output: fmt::Debug,
621{
622    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { self.inner.fmt(f) }
623}
624
625impl<A, B, C, D> Clone for Decoder4<A, B, C, D>
626where
627    A: Decoder + Clone,
628    B: Decoder + Clone,
629    C: Decoder + Clone,
630    D: Decoder + Clone,
631    A::Output: Clone,
632    B::Output: Clone,
633    C::Output: Clone,
634{
635    fn clone(&self) -> Self { Self { inner: self.inner.clone() } }
636}
637
638impl<A, B, C, D> Decoder for Decoder4<A, B, C, D>
639where
640    A: Decoder,
641    B: Decoder,
642    C: Decoder,
643    D: Decoder,
644{
645    type Output = (A::Output, B::Output, C::Output, D::Output);
646    type Error = Decoder4Error<A::Error, B::Error, C::Error, D::Error>;
647
648    #[inline]
649    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<DecoderStatus, Self::Error> {
650        self.inner.push_bytes(bytes).map_err(|error| match error {
651            Decoder2Error::First(Decoder2Error::First(a)) => Decoder4Error::First(a),
652            Decoder2Error::First(Decoder2Error::Second(b)) => Decoder4Error::Second(b),
653            Decoder2Error::Second(Decoder2Error::First(c)) => Decoder4Error::Third(c),
654            Decoder2Error::Second(Decoder2Error::Second(d)) => Decoder4Error::Fourth(d),
655        })
656    }
657
658    #[inline]
659    fn end(self) -> Result<Self::Output, Self::Error> {
660        let result = self.inner.end().map_err(|error| match error {
661            Decoder2Error::First(Decoder2Error::First(a)) => Decoder4Error::First(a),
662            Decoder2Error::First(Decoder2Error::Second(b)) => Decoder4Error::Second(b),
663            Decoder2Error::Second(Decoder2Error::First(c)) => Decoder4Error::Third(c),
664            Decoder2Error::Second(Decoder2Error::Second(d)) => Decoder4Error::Fourth(d),
665        })?;
666
667        let ((first, second), (third, fourth)) = result;
668        Ok((first, second, third, fourth))
669    }
670
671    #[inline]
672    fn read_limit(&self) -> usize { self.inner.read_limit() }
673}
674
675/// A decoder which decodes six objects, one after the other.
676#[allow(clippy::type_complexity)] // Nested composition is easier than flattened alternatives.
677#[derive(Default)]
678pub struct Decoder6<A, B, C, D, E, F>
679where
680    A: Decoder,
681    B: Decoder,
682    C: Decoder,
683    D: Decoder,
684    E: Decoder,
685    F: Decoder,
686{
687    inner: Decoder2<Decoder3<A, B, C>, Decoder3<D, E, F>>,
688}
689
690impl<A, B, C, D, E, F> Decoder6<A, B, C, D, E, F>
691where
692    A: Decoder,
693    B: Decoder,
694    C: Decoder,
695    D: Decoder,
696    E: Decoder,
697    F: Decoder,
698{
699    /// Constructs a new composite decoder.
700    pub const fn new(dec_1: A, dec_2: B, dec_3: C, dec_4: D, dec_5: E, dec_6: F) -> Self {
701        Self {
702            inner: Decoder2::new(
703                Decoder3::new(dec_1, dec_2, dec_3),
704                Decoder3::new(dec_4, dec_5, dec_6),
705            ),
706        }
707    }
708}
709
710impl<A, B, C, D, E, F> fmt::Debug for Decoder6<A, B, C, D, E, F>
711where
712    A: Decoder + fmt::Debug,
713    B: Decoder + fmt::Debug,
714    C: Decoder + fmt::Debug,
715    D: Decoder + fmt::Debug,
716    E: Decoder + fmt::Debug,
717    F: Decoder + fmt::Debug,
718    A::Output: fmt::Debug,
719    B::Output: fmt::Debug,
720    C::Output: fmt::Debug,
721    D::Output: fmt::Debug,
722    E::Output: fmt::Debug,
723{
724    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { self.inner.fmt(f) }
725}
726
727impl<A, B, C, D, E, F> Clone for Decoder6<A, B, C, D, E, F>
728where
729    A: Decoder + Clone,
730    B: Decoder + Clone,
731    C: Decoder + Clone,
732    D: Decoder + Clone,
733    E: Decoder + Clone,
734    F: Decoder + Clone,
735    A::Output: Clone,
736    B::Output: Clone,
737    C::Output: Clone,
738    D::Output: Clone,
739    E::Output: Clone,
740{
741    fn clone(&self) -> Self { Self { inner: self.inner.clone() } }
742}
743
744impl<A, B, C, D, E, F> Decoder for Decoder6<A, B, C, D, E, F>
745where
746    A: Decoder,
747    B: Decoder,
748    C: Decoder,
749    D: Decoder,
750    E: Decoder,
751    F: Decoder,
752{
753    type Output = (A::Output, B::Output, C::Output, D::Output, E::Output, F::Output);
754    type Error = Decoder6Error<A::Error, B::Error, C::Error, D::Error, E::Error, F::Error>;
755
756    #[inline]
757    fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<DecoderStatus, Self::Error> {
758        self.inner.push_bytes(bytes).map_err(|error| match error {
759            Decoder2Error::First(Decoder3Error::First(a)) => Decoder6Error::First(a),
760            Decoder2Error::First(Decoder3Error::Second(b)) => Decoder6Error::Second(b),
761            Decoder2Error::First(Decoder3Error::Third(c)) => Decoder6Error::Third(c),
762            Decoder2Error::Second(Decoder3Error::First(d)) => Decoder6Error::Fourth(d),
763            Decoder2Error::Second(Decoder3Error::Second(e)) => Decoder6Error::Fifth(e),
764            Decoder2Error::Second(Decoder3Error::Third(f)) => Decoder6Error::Sixth(f),
765        })
766    }
767
768    #[inline]
769    fn end(self) -> Result<Self::Output, Self::Error> {
770        let result = self.inner.end().map_err(|error| match error {
771            Decoder2Error::First(Decoder3Error::First(a)) => Decoder6Error::First(a),
772            Decoder2Error::First(Decoder3Error::Second(b)) => Decoder6Error::Second(b),
773            Decoder2Error::First(Decoder3Error::Third(c)) => Decoder6Error::Third(c),
774            Decoder2Error::Second(Decoder3Error::First(d)) => Decoder6Error::Fourth(d),
775            Decoder2Error::Second(Decoder3Error::Second(e)) => Decoder6Error::Fifth(e),
776            Decoder2Error::Second(Decoder3Error::Third(f)) => Decoder6Error::Sixth(f),
777        })?;
778
779        let ((first, second, third), (fourth, fifth, sixth)) = result;
780        Ok((first, second, third, fourth, fifth, sixth))
781    }
782
783    #[inline]
784    fn read_limit(&self) -> usize { self.inner.read_limit() }
785}
786
787#[cfg(test)]
788mod tests {
789    #[cfg(feature = "alloc")]
790    use alloc::vec;
791    #[cfg(feature = "alloc")]
792    use alloc::vec::Vec;
793
794    #[cfg(feature = "alloc")]
795    use super::*;
796
797    #[test]
798    #[cfg(feature = "alloc")]
799    fn byte_vec_decoder_decode_empty_slice() {
800        let mut decoder = ByteVecDecoder::new();
801        let data = [];
802        let _ = decoder.push_bytes(&mut data.as_slice());
803        let err = decoder.end().unwrap_err();
804
805        if let ByteVecDecoderErrorInner::UnexpectedEof(e) = err.0 {
806            assert_eq!(e.missing, 1);
807        } else {
808            panic!("Expected UnexpectedEof error");
809        }
810    }
811
812    #[test]
813    #[cfg(feature = "alloc")]
814    fn byte_vec_decoder_incomplete_0xfd_prefix() {
815        let mut decoder = ByteVecDecoder::new();
816        let data = [0xFD];
817        let _ = decoder.push_bytes(&mut data.as_slice());
818        let err = decoder.end().unwrap_err();
819
820        if let ByteVecDecoderErrorInner::UnexpectedEof(e) = err.0 {
821            assert_eq!(e.missing, 2);
822        } else {
823            panic!("Expected UnexpectedEof error");
824        }
825    }
826
827    #[test]
828    #[cfg(feature = "alloc")]
829    fn byte_vec_decoder_incomplete_0xfe_prefix() {
830        let mut decoder = ByteVecDecoder::new();
831        let data = [0xFE];
832        let _ = decoder.push_bytes(&mut data.as_slice());
833        let err = decoder.end().unwrap_err();
834
835        if let ByteVecDecoderErrorInner::UnexpectedEof(e) = err.0 {
836            assert_eq!(e.missing, 4);
837        } else {
838            panic!("Expected UnexpectedEof error");
839        }
840    }
841
842    #[test]
843    #[cfg(feature = "alloc")]
844    fn byte_vec_decoder_incomplete_0xff_prefix() {
845        let mut decoder = ByteVecDecoder::new();
846        let data = [0xFF];
847        let _ = decoder.push_bytes(&mut data.as_slice());
848        let err = decoder.end().unwrap_err();
849
850        if let ByteVecDecoderErrorInner::UnexpectedEof(e) = err.0 {
851            assert_eq!(e.missing, 8);
852        } else {
853            panic!("Expected UnexpectedEof error");
854        }
855    }
856
857    #[test]
858    #[cfg(feature = "alloc")]
859    fn byte_vec_decoder_reserves_in_batches() {
860        // A small number of extra bytes so we extend exactly by the remainder
861        // instead of another full batch.
862        let tail_length: usize = 11;
863
864        let total_len = MAX_VECTOR_ALLOCATE + tail_length;
865        let total_len_le = u32::try_from(total_len).expect("total_len fits u32").to_le_bytes();
866        let mut decoder = ByteVecDecoder::new();
867
868        let mut prefix = vec![0xFE]; // total_len_le is a compact size of four bytes.
869        prefix.extend_from_slice(&total_len_le);
870        prefix.push(0xAA);
871        let mut prefix_slice = prefix.as_slice();
872        decoder.push_bytes(&mut prefix_slice).expect("length plus first element");
873        assert!(prefix_slice.is_empty());
874
875        assert_eq!(decoder.buffer.capacity(), MAX_VECTOR_ALLOCATE);
876        assert_eq!(decoder.buffer.len(), 1);
877        assert_eq!(decoder.buffer[0], 0xAA);
878
879        let fill = vec![0xBB; MAX_VECTOR_ALLOCATE - 1];
880        let mut fill_slice = fill.as_slice();
881        decoder.push_bytes(&mut fill_slice).expect("fills to batch boundary, full capacity");
882        assert!(fill_slice.is_empty());
883
884        assert_eq!(decoder.buffer.capacity(), MAX_VECTOR_ALLOCATE);
885        assert_eq!(decoder.buffer.len(), MAX_VECTOR_ALLOCATE);
886        assert_eq!(decoder.buffer[MAX_VECTOR_ALLOCATE - 1], 0xBB);
887
888        let mut tail = vec![0xCC];
889        tail.extend([0xDD].repeat(tail_length - 1));
890        let mut tail_slice = tail.as_slice();
891        decoder.push_bytes(&mut tail_slice).expect("fills the remaining bytes");
892        assert!(tail_slice.is_empty());
893
894        assert_eq!(decoder.buffer.capacity(), MAX_VECTOR_ALLOCATE + tail_length);
895        assert_eq!(decoder.buffer.len(), total_len);
896        assert_eq!(decoder.buffer[MAX_VECTOR_ALLOCATE], 0xCC);
897
898        let result = decoder.end().unwrap();
899        assert_eq!(result.len(), total_len);
900        assert_eq!(result[total_len - 1], 0xDD);
901    }
902
903    #[cfg(feature = "alloc")]
904    #[derive(Clone, Debug, PartialEq, Eq)]
905    pub struct Inner(u32);
906
907    /// The decoder for the [`Inner`] type.
908    #[cfg(feature = "alloc")]
909    #[derive(Clone, Default)]
910    pub struct InnerDecoder(ArrayDecoder<4>);
911
912    #[cfg(feature = "alloc")]
913    impl Decoder for InnerDecoder {
914        type Output = Inner;
915        type Error = UnexpectedEofError;
916
917        fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<DecoderStatus, Self::Error> {
918            self.0.push_bytes(bytes)
919        }
920
921        fn end(self) -> Result<Self::Output, Self::Error> {
922            let n = u32::from_le_bytes(self.0.end()?);
923            Ok(Inner(n))
924        }
925
926        fn read_limit(&self) -> usize { self.0.read_limit() }
927    }
928
929    #[cfg(feature = "alloc")]
930    impl Decode for Inner {
931        type Decoder = InnerDecoder;
932    }
933
934    #[cfg(feature = "alloc")]
935    #[derive(Clone, Debug, PartialEq, Eq)]
936    pub struct Test(Vec<Inner>);
937
938    /// The decoder for the [`Test`] type.
939    #[cfg(feature = "alloc")]
940    #[derive(Clone, Default)]
941    pub struct TestDecoder(VecDecoder<Inner>);
942
943    #[cfg(feature = "alloc")]
944    impl Decoder for TestDecoder {
945        type Output = Test;
946        type Error = VecDecoderError<UnexpectedEofError>;
947
948        fn push_bytes(&mut self, bytes: &mut &[u8]) -> Result<DecoderStatus, Self::Error> {
949            self.0.push_bytes(bytes)
950        }
951
952        fn end(self) -> Result<Self::Output, Self::Error> {
953            let v = self.0.end()?;
954            Ok(Test(v))
955        }
956
957        fn read_limit(&self) -> usize { self.0.read_limit() }
958    }
959
960    #[cfg(feature = "alloc")]
961    impl Decode for Test {
962        type Decoder = TestDecoder;
963    }
964
965    #[test]
966    #[cfg(feature = "alloc")]
967    fn vec_decoder_empty() {
968        // Empty with a couple of arbitrary extra bytes.
969        let encoded = vec![0x00, 0xFF, 0xFF];
970
971        let mut slice = encoded.as_slice();
972        let mut decoder = Test::decoder();
973        assert!(decoder.push_bytes(&mut slice).unwrap().is_ready());
974
975        let got = decoder.end().unwrap();
976        let want = Test(vec![]);
977
978        assert_eq!(got, want);
979    }
980
981    #[test]
982    #[cfg(feature = "alloc")]
983    fn vec_decoder_empty_no_bytes() {
984        // Empty slice. Note the lack of any length prefix compact size.
985        let encoded = &[];
986
987        let mut slice = encoded.as_slice();
988        let mut decoder = Test::decoder();
989        // Should want more bytes since we've provided nothing
990        assert!(decoder.push_bytes(&mut slice).unwrap().needs_more());
991
992        assert!(matches!(
993            decoder.end().unwrap_err(),
994            VecDecoderError(VecDecoderErrorInner::UnexpectedEof(_))
995        ));
996    }
997
998    #[test]
999    #[cfg(feature = "alloc")]
1000    fn vec_decoder_one_item() {
1001        let encoded = vec![0x01, 0xEF, 0xBE, 0xAD, 0xDE];
1002
1003        let mut slice = encoded.as_slice();
1004        let mut decoder = Test::decoder();
1005        decoder.push_bytes(&mut slice).unwrap();
1006
1007        let got = decoder.end().unwrap();
1008        let want = Test(vec![Inner(0xDEAD_BEEF)]);
1009
1010        assert_eq!(got, want);
1011    }
1012
1013    #[test]
1014    #[cfg(feature = "alloc")]
1015    fn vec_decoder_two_items() {
1016        let encoded = vec![0x02, 0xEF, 0xBE, 0xAD, 0xDE, 0xBE, 0xBA, 0xFE, 0xCA];
1017
1018        let mut slice = encoded.as_slice();
1019        let mut decoder = Test::decoder();
1020        decoder.push_bytes(&mut slice).unwrap();
1021
1022        let got = decoder.end().unwrap();
1023        let want = Test(vec![Inner(0xDEAD_BEEF), Inner(0xCAFE_BABE)]);
1024
1025        assert_eq!(got, want);
1026    }
1027
1028    #[test]
1029    #[cfg(feature = "alloc")]
1030    fn vec_decoder_reserves_in_batches() {
1031        // A small number of extra elements so we extend exactly by the remainder
1032        // instead of another full batch.
1033        let tail_length: usize = 11;
1034
1035        let element_size = core::mem::size_of::<Inner>();
1036        let batch_length = MAX_VECTOR_ALLOCATE / element_size;
1037        assert!(batch_length > 1);
1038        let total_len = batch_length + tail_length;
1039        let total_len_le = u32::try_from(total_len).expect("total_len fits u32").to_le_bytes();
1040        let mut decoder = Test::decoder();
1041
1042        let mut prefix = vec![0xFE]; // total_len_le is a compact size of four bytes.
1043        prefix.extend_from_slice(&total_len_le);
1044        prefix.extend_from_slice(&0xAA_u32.to_le_bytes());
1045        let mut prefix_slice = prefix.as_slice();
1046        decoder.push_bytes(&mut prefix_slice).expect("length plus first element");
1047        assert!(prefix_slice.is_empty());
1048
1049        assert_eq!(decoder.0.buffer.capacity(), batch_length);
1050        assert_eq!(decoder.0.buffer.len(), 1);
1051        assert_eq!(decoder.0.buffer[0], Inner(0xAA));
1052
1053        let fill = 0xBB_u32.to_le_bytes().repeat(batch_length - 1);
1054        let mut fill_slice = fill.as_slice();
1055        decoder.push_bytes(&mut fill_slice).expect("fills to batch boundary, full capacity");
1056        assert!(fill_slice.is_empty());
1057
1058        assert_eq!(decoder.0.buffer.capacity(), batch_length);
1059        assert_eq!(decoder.0.buffer.len(), batch_length);
1060        assert_eq!(decoder.0.buffer[batch_length - 1], Inner(0xBB));
1061
1062        let mut tail = 0xCC_u32.to_le_bytes().to_vec();
1063        tail.extend(0xDD_u32.to_le_bytes().repeat(tail_length - 1));
1064        let mut tail_slice = tail.as_slice();
1065        decoder.push_bytes(&mut tail_slice).expect("fills the remaining bytes");
1066        assert!(tail_slice.is_empty());
1067
1068        assert_eq!(decoder.0.buffer.capacity(), batch_length + tail_length);
1069        assert_eq!(decoder.0.buffer.len(), total_len);
1070        assert_eq!(decoder.0.buffer[batch_length], Inner(0xCC));
1071
1072        let Test(result) = decoder.end().unwrap();
1073        assert_eq!(result.len(), total_len);
1074        assert_eq!(result[total_len - 1], Inner(0xDD));
1075    }
1076}
bitcoin_consensus_encoding/decode/decoders.rs

bitcoin_consensus_encoding/decode/
decoders.rs
