bitcoin_consensus_encoding/decode/
decoders.rs

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

bitcoin_consensus_encoding/decode/
decoders.rs
