rust-bitcoin-unsafe-fast/io/src/lib.rs

//! Rust-Bitcoin IO Library
//!
//! Because the core `std::io` module is not yet exposed in `no-std` Rust, building `no-std`
//! applications which require reading and writing objects via standard traits is not generally
//! possible. While there is ongoing work to improve this situation, this module is not likely to
//! be available for applications with broad rustc version support for some time.
//!
//! Thus, this library exists to export a minmal version of `std::io`'s traits which `no-std`
//! applications may need. With the `std` feature, these traits are also implemented for the
//! `std::io` traits, allowing standard objects to be used wherever the traits from this crate are
//! required.
//!
//! This traits are not one-for-one drop-ins, but are as close as possible while still implementing
//! `std::io`'s traits without unnecessary complexity.

// Experimental features we need.
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(any(feature = "alloc", feature = "std"))]
extern crate alloc;

mod macros;

/// Standard I/O stream definitions which are API-equivalent to `std`'s `io` module. See
/// [`std::io`] for more info.
#[cfg(any(feature = "alloc", feature = "std"))]
use alloc::boxed::Box;
use core::convert::TryInto;
use core::fmt::{Debug, Display, Formatter};

#[cfg(all(feature = "alloc", not(feature = "std")))]
mod sealed {
    use alloc::boxed::Box;
    use alloc::string::String;
    use core::fmt::Debug;
    pub trait IntoBoxDynDebug {
        fn into(self) -> Box<dyn Debug + Send + Sync + 'static>;
    }
    impl IntoBoxDynDebug for &str {
        fn into(self) -> Box<dyn Debug + Send + Sync + 'static> { Box::new(String::from(self)) }
    }
    impl IntoBoxDynDebug for String {
        fn into(self) -> Box<dyn Debug + Send + Sync + 'static> { Box::new(self) }
    }
}

#[derive(Debug)]
pub struct Error {
    kind: ErrorKind,

    #[cfg(feature = "std")]
    error: Option<Box<dyn std::error::Error + Send + Sync + 'static>>,
    #[cfg(all(feature = "alloc", not(feature = "std")))]
    error: Option<Box<dyn Debug + Send + Sync + 'static>>,
}
impl Error {
    #[cfg(feature = "std")]
    pub fn new<E>(kind: ErrorKind, error: E) -> Error
    where
        E: Into<Box<dyn std::error::Error + Send + Sync + 'static>>,
    {
        Self { kind, error: Some(error.into()) }
    }
    #[cfg(all(feature = "alloc", not(feature = "std")))]
    pub fn new<E: sealed::IntoBoxDynDebug>(kind: ErrorKind, error: E) -> Error {
        Self { kind, error: Some(error.into()) }
    }

    pub fn kind(&self) -> ErrorKind { self.kind }
}

impl From<ErrorKind> for Error {
    fn from(kind: ErrorKind) -> Error {
        Self {
            kind,
            #[cfg(any(feature = "std", feature = "alloc"))]
            error: None,
        }
    }
}

impl Display for Error {
    fn fmt(&self, fmt: &mut Formatter) -> core::result::Result<(), core::fmt::Error> {
        fmt.write_fmt(format_args!("I/O Error: {}", self.kind.description()))?;
        #[cfg(any(feature = "alloc", feature = "std"))]
        if let Some(e) = &self.error {
            fmt.write_fmt(format_args!(". {:?}", e))?;
        }
        Ok(())
    }
}

#[cfg(feature = "std")]
impl std::error::Error for Error {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        self.error.as_ref().and_then(|e| e.as_ref().source())
    }
    #[allow(deprecated)]
    fn description(&self) -> &str {
        match self.error.as_ref() {
            Some(e) => e.description(),
            None => self.kind.description(),
        }
    }
    #[allow(deprecated)]
    fn cause(&self) -> Option<&dyn std::error::Error> {
        self.error.as_ref().and_then(|e| e.as_ref().cause())
    }
}

impl Error {
    #[cfg(feature = "std")]
    pub fn get_ref(&self) -> Option<&(dyn std::error::Error + Send + Sync + 'static)> {
        self.error.as_deref()
    }
    #[cfg(all(feature = "alloc", not(feature = "std")))]
    pub fn get_ref(&self) -> Option<&(dyn Debug + Send + Sync + 'static)> { self.error.as_deref() }
}

#[cfg(feature = "std")]
impl From<std::io::Error> for Error {
    fn from(o: std::io::Error) -> Error {
        Self { kind: ErrorKind::from_std(o.kind()), error: o.into_inner() }
    }
}

#[cfg(feature = "std")]
impl From<Error> for std::io::Error {
    fn from(o: Error) -> std::io::Error {
        if let Some(err) = o.error {
            std::io::Error::new(o.kind.to_std(), err)
        } else {
            o.kind.to_std().into()
        }
    }
}

macro_rules! define_errorkind {
    ($($kind: ident),*) => {
        #[non_exhaustive]
        #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
        /// A minimal subset of [`std::io::ErrorKind`] which is used for [`Error`]. Note that, as with
        /// [`std::io`], only [`Self::Interrupted`] has defined semantics in this crate, all other
        /// variants are provided here only to provide higher-fidelity conversions to and from
        /// [`std::io::Error`].
        pub enum ErrorKind {
            $($kind),*
        }

        impl ErrorKind {
            fn description(&self) -> &'static str {
                match self {
                    $(Self::$kind => stringify!($kind)),*
                }
            }
            #[cfg(feature = "std")]
            fn to_std(self) -> std::io::ErrorKind {
                match self {
                    $(Self::$kind => std::io::ErrorKind::$kind),*
                }
            }
            #[cfg(feature = "std")]
            fn from_std(o: std::io::ErrorKind) -> ErrorKind {
                match o {
                    $(std::io::ErrorKind::$kind => ErrorKind::$kind),*,
                    _ => ErrorKind::Other
                }
            }
        }
    }
}

define_errorkind!(
    NotFound,
    PermissionDenied,
    ConnectionRefused,
    ConnectionReset,
    ConnectionAborted,
    NotConnected,
    AddrInUse,
    AddrNotAvailable,
    BrokenPipe,
    AlreadyExists,
    WouldBlock,
    InvalidInput,
    InvalidData,
    TimedOut,
    WriteZero,
    Interrupted,
    UnexpectedEof,
    // Note: Any time we bump the MSRV any new error kinds should be added here!
    Other
);

pub type Result<T> = core::result::Result<T, Error>;

/// A generic trait describing an input stream. See [`std::io::Read`] for more info.
pub trait Read {
    fn read(&mut self, buf: &mut [u8]) -> Result<usize>;
    #[inline]
    fn read_exact(&mut self, mut buf: &mut [u8]) -> Result<()> {
        while !buf.is_empty() {
            match self.read(buf) {
                Ok(0) => return Err(ErrorKind::UnexpectedEof.into()),
                Ok(len) => buf = &mut buf[len..],
                Err(e) if e.kind() == ErrorKind::Interrupted => {}
                Err(e) => return Err(e),
            }
        }
        Ok(())
    }
    #[inline]
    fn take(&mut self, limit: u64) -> Take<Self> { Take { reader: self, remaining: limit } }
}

pub struct Take<'a, R: Read + ?Sized> {
    reader: &'a mut R,
    remaining: u64,
}
impl<'a, R: Read + ?Sized> Read for Take<'a, R> {
    #[inline]
    fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
        let len = core::cmp::min(buf.len(), self.remaining.try_into().unwrap_or(buf.len()));
        let read = self.reader.read(&mut buf[..len])?;
        self.remaining -= read.try_into().unwrap_or(self.remaining);
        Ok(read)
    }
}

#[cfg(feature = "std")]
impl<R: std::io::Read> Read for R {
    #[inline]
    fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
        Ok(<R as std::io::Read>::read(self, buf)?)
    }
}

#[cfg(not(feature = "std"))]
impl Read for &[u8] {
    #[inline]
    fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
        let cnt = core::cmp::min(self.len(), buf.len());
        buf[..cnt].copy_from_slice(&self[..cnt]);
        *self = &self[cnt..];
        Ok(cnt)
    }
}

pub struct Cursor<T> {
    inner: T,
    pos: u64,
}
impl<T: AsRef<[u8]>> Cursor<T> {
    #[inline]
    pub fn new(inner: T) -> Self { Cursor { inner, pos: 0 } }
    #[inline]
    pub fn position(&self) -> u64 { self.pos }
    #[inline]
    pub fn into_inner(self) -> T { self.inner }
}
impl<T: AsRef<[u8]>> Read for Cursor<T> {
    #[inline]
    fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
        let inner: &[u8] = self.inner.as_ref();
        let start_pos = self.pos.try_into().unwrap_or(inner.len());
        let read = core::cmp::min(inner.len().saturating_sub(start_pos), buf.len());
        buf[..read].copy_from_slice(&inner[start_pos..start_pos + read]);
        self.pos =
            self.pos.saturating_add(read.try_into().unwrap_or(u64::max_value() /* unreachable */));
        Ok(read)
    }
}

/// A generic trait describing an output stream. See [`std::io::Write`] for more info.
pub trait Write {
    fn write(&mut self, buf: &[u8]) -> Result<usize>;
    fn flush(&mut self) -> Result<()>;

    #[inline]
    fn write_all(&mut self, mut buf: &[u8]) -> Result<()> {
        while !buf.is_empty() {
            match self.write(buf) {
                Ok(0) => return Err(ErrorKind::UnexpectedEof.into()),
                Ok(len) => buf = &buf[len..],
                Err(e) if e.kind() == ErrorKind::Interrupted => {}
                Err(e) => return Err(e),
            }
        }
        Ok(())
    }
}

#[cfg(feature = "std")]
impl<W: std::io::Write> Write for W {
    #[inline]
    fn write(&mut self, buf: &[u8]) -> Result<usize> {
        Ok(<W as std::io::Write>::write(self, buf)?)
    }
    #[inline]
    fn flush(&mut self) -> Result<()> { Ok(<W as std::io::Write>::flush(self)?) }
}

#[cfg(all(feature = "alloc", not(feature = "std")))]
impl Write for alloc::vec::Vec<u8> {
    #[inline]
    fn write(&mut self, buf: &[u8]) -> Result<usize> {
        self.extend_from_slice(buf);
        Ok(buf.len())
    }
    #[inline]
    fn flush(&mut self) -> Result<()> { Ok(()) }
}

#[cfg(not(feature = "std"))]
impl<'a> Write for &'a mut [u8] {
    #[inline]
    fn write(&mut self, buf: &[u8]) -> Result<usize> {
        let cnt = core::cmp::min(self.len(), buf.len());
        self[..cnt].copy_from_slice(&buf[..cnt]);
        *self = &mut core::mem::take(self)[cnt..];
        Ok(cnt)
    }
    #[inline]
    fn flush(&mut self) -> Result<()> { Ok(()) }
}

/// A sink to which all writes succeed. See [`std::io::Sink`] for more info.
pub struct Sink;
#[cfg(not(feature = "std"))]
impl Write for Sink {
    #[inline]
    fn write(&mut self, buf: &[u8]) -> Result<usize> { Ok(buf.len()) }
    #[inline]
    fn write_all(&mut self, _: &[u8]) -> Result<()> { Ok(()) }
    #[inline]
    fn flush(&mut self) -> Result<()> { Ok(()) }
}
#[cfg(feature = "std")]
impl std::io::Write for Sink {
    #[inline]
    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> { Ok(buf.len()) }
    #[inline]
    fn write_all(&mut self, _: &[u8]) -> std::io::Result<()> { Ok(()) }
    #[inline]
    fn flush(&mut self) -> std::io::Result<()> { Ok(()) }
}
/// Returns a sink to which all writes succeed. See [`std::io::sink`] for more info.
pub fn sink() -> Sink { Sink }