Merge rust-bitcoin#5030: Add decoder I/O drivers

0ac8e91 consensus_encoding: API update (Nick Johnson)
93a085b consensus_encoding: add read interface for decoders (Nick Johnson)
9fb668e consensus_encoding: add decoder I/O drivers (Nick Johnson)

Pull request description:

  Getting the ball rolling on I/O drivers for the decode side, which I think is going to be more interesting than the encode side since the buffered interface is different.
  
  ## First Patch
  
  The simple drivers for slice and bufreader.
  
  These are water'd down versions of push_decode. Some simplifications were made like making `ReadError` less generic by hard-coding to the std::io error type.
  
  But this does get right to the chase for the decode-side complexity: is it cool to have a separate driver for `BufReader` and `Read`?
  
  ## Second Patch
  
  The complex driver for `Read`.
  
  Following push_decode's design, introduced a new requirement on the `Decoder`'s to expose a `min_bytes_needed`. This allows the read driver to efficiently manage its internal buffer. I just put this requirement straight on `Decoder` because I think we can assume all bitcoin decodables will know their min bytes.


ACKs for top commit:
  tcharding:
    ACK 0ac8e91
  apoelstra:
    ACK 0ac8e91; successfully ran local tests


Tree-SHA512: da5b0ca57e07338db11a1db73370bd21fe06ae699e971f3184780fd5dd7707b8992ea0b2d8a0944e25ebc047c4d93344b16388bace917b009e5007bdd0ef8fed

Author: apoelstra

api/units/all-features.txt

@@ -1893,6 +1893,7 @@ pub fn bitcoin_units::Weight::try_from(s: alloc::boxed::Box<str>) -> core::resul
 pub fn bitcoin_units::Weight::try_from(s: alloc::string::String) -> core::result::Result<Self, Self::Error>
 pub fn bitcoin_units::amount::AmountDecoder::default() -> Self
 pub fn bitcoin_units::amount::AmountDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
+pub fn bitcoin_units::amount::AmountDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::amount::AmountDecoder::new() -> Self
 pub fn bitcoin_units::amount::AmountDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
 pub fn bitcoin_units::amount::Denomination::arbitrary(u: &mut arbitrary::unstructured::Unstructured<'a>) -> arbitrary::error::Result<Self>
@@ -2004,6 +2005,7 @@ pub fn bitcoin_units::block::BlockHeight::try_from(s: alloc::boxed::Box<str>) ->
 pub fn bitcoin_units::block::BlockHeight::try_from(s: alloc::string::String) -> core::result::Result<Self, Self::Error>
 pub fn bitcoin_units::block::BlockHeightDecoder::default() -> Self
 pub fn bitcoin_units::block::BlockHeightDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
+pub fn bitcoin_units::block::BlockHeightDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::block::BlockHeightDecoder::new() -> Self
 pub fn bitcoin_units::block::BlockHeightDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
 pub fn bitcoin_units::block::BlockHeightDecoderError::clone(&self) -> bitcoin_units::block::BlockHeightDecoderError
@@ -2153,6 +2155,7 @@ pub fn bitcoin_units::locktime::absolute::LockTime::try_from(s: alloc::boxed::Bo
 pub fn bitcoin_units::locktime::absolute::LockTime::try_from(s: alloc::string::String) -> core::result::Result<Self, Self::Error>
 pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::default() -> Self
 pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
+pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::new() -> Self
 pub fn bitcoin_units::locktime::absolute::LockTimeDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
 pub fn bitcoin_units::locktime::absolute::LockTimeEncoder::advance(&mut self) -> bool
@@ -2418,6 +2421,7 @@ pub fn bitcoin_units::sequence::Sequence::try_from(s: alloc::boxed::Box<str>) ->
 pub fn bitcoin_units::sequence::Sequence::try_from(s: alloc::string::String) -> core::result::Result<Self, Self::Error>
 pub fn bitcoin_units::sequence::SequenceDecoder::default() -> Self
 pub fn bitcoin_units::sequence::SequenceDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
+pub fn bitcoin_units::sequence::SequenceDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::sequence::SequenceDecoder::new() -> Self
 pub fn bitcoin_units::sequence::SequenceDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
 pub fn bitcoin_units::sequence::SequenceDecoderError::clone(&self) -> bitcoin_units::sequence::SequenceDecoderError
@@ -2429,6 +2433,7 @@ pub fn bitcoin_units::sequence::SequenceEncoder::advance(&mut self) -> bool
 pub fn bitcoin_units::sequence::SequenceEncoder::current_chunk(&self) -> core::option::Option<&[u8]>
 pub fn bitcoin_units::time::BlockTimeDecoder::default() -> Self
 pub fn bitcoin_units::time::BlockTimeDecoder::end(self) -> core::result::Result<Self::Output, Self::Error>
+pub fn bitcoin_units::time::BlockTimeDecoder::min_bytes_needed(&self) -> usize
 pub fn bitcoin_units::time::BlockTimeDecoder::new() -> Self
 pub fn bitcoin_units::time::BlockTimeDecoder::push_bytes(&mut self, bytes: &mut &[u8]) -> core::result::Result<bool, Self::Error>
 pub fn bitcoin_units::time::BlockTimeDecoderError::clone(&self) -> bitcoin_units::time::BlockTimeDecoderError

consensus_encoding/src/decode/decoders.rs

@@ -47,6 +47,9 @@ impl<const N: usize> Decoder for ArrayDecoder<N> {
             Err(UnexpectedEofError { missing: N - self.bytes_written })
         }
     }
+
+    #[inline]
+    fn min_bytes_needed(&self) -> usize { N - self.bytes_written }
 }
 
 /// A decoder which wraps two inner decoders and returns the output of both.
@@ -165,6 +168,17 @@ where
             }
         }
     }
+
+    #[inline]
+    fn min_bytes_needed(&self) -> usize {
+        match &self.state {
+            Decoder2State::First(first_decoder, second_decoder) =>
+                first_decoder.min_bytes_needed() + second_decoder.min_bytes_needed(),
+            Decoder2State::Second(_, second_decoder) => second_decoder.min_bytes_needed(),
+            Decoder2State::Errored => 0,
+            Decoder2State::Transitioning => 0,
+        }
+    }
 }
 
 /// A decoder which decodes three objects, one after the other.
@@ -215,6 +229,9 @@ where
         let ((first, second), third) = self.inner.end()?;
         Ok((first, second, third))
     }
+
+    #[inline]
+    fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
 }
 
 /// A decoder which decodes four objects, one after the other.
@@ -268,6 +285,9 @@ where
         let ((first, second), (third, fourth)) = self.inner.end()?;
         Ok((first, second, third, fourth))
     }
+
+    #[inline]
+    fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
 }
 
 /// A decoder which decodes six objects, one after the other.
@@ -346,6 +366,9 @@ where
         let ((first, second, third), (fourth, fifth, sixth)) = self.inner.end()?;
         Ok((first, second, third, fourth, fifth, sixth))
     }
+
+    #[inline]
+    fn min_bytes_needed(&self) -> usize { self.inner.min_bytes_needed() }
 }
 
 /// Not enough bytes given to decoder.