zlink-core 0.4.1

//! The low-level Socket read and write traits.

use core::future::Future;

#[cfg(feature = "std")]
use std::os::fd::{AsFd, OwnedFd};

/// Result type for [`ReadHalf::read`] operations.
///
/// With `std` feature: returns `(usize, Vec<OwnedFd>)` - bytes read and file descriptors.
/// Without `std` feature: returns `usize` - just bytes read.
#[cfg(feature = "std")]
pub type ReadResult = (usize, alloc::vec::Vec<OwnedFd>);

/// Result type for [`ReadHalf::read`] operations.
///
/// With `std` feature: returns `(usize, Vec<OwnedFd>)` - bytes read and file descriptors.
/// Without `std` feature: returns `usize` - just bytes read.
#[cfg(not(feature = "std"))]
pub type ReadResult = usize;

/// The socket trait.
///
/// This is the trait that needs to be implemented for a type to be used as a socket/transport.
pub trait Socket: core::fmt::Debug {
    /// The read half of the socket.
    type ReadHalf: ReadHalf;
    /// The write half of the socket.
    type WriteHalf: WriteHalf;

    /// Whether this socket can transfer file descriptors.
    ///
    /// This is `true` for Unix domain sockets and `false` for other socket types.
    const CAN_TRANSFER_FDS: bool = false;

    /// Split the socket into read and write halves.
    fn split(self) -> (Self::ReadHalf, Self::WriteHalf);
}

/// The read half of a socket.
pub trait ReadHalf: core::fmt::Debug {
    /// Read from a socket.
    ///
    /// On completion, the number of bytes read and any file descriptors received are returned.
    ///
    /// Notes for implementers:
    ///
    /// * The future returned by this method must be cancel safe.
    /// * While there is no explicit `Unpin` bound on the future returned by this method, it is
    ///   expected that it provides the same guarantees as `Unpin` would require. The reason `Unpin`
    ///   is not explicitly required is that it would force boxing (and therefore allocation) on the
    ///   implementation that use `async fn`, which is undesirable for embedded use cases. See [this
    ///   issue](https://github.com/rust-lang/rust/issues/82187) for details.
    fn read(&mut self, buf: &mut [u8]) -> impl Future<Output = crate::Result<ReadResult>>;
}

/// The write half of a socket.
pub trait WriteHalf: core::fmt::Debug {
    /// Write to the socket.
    ///
    /// The `fds` parameter contains file descriptors to send along with the data (std only).
    ///
    /// The returned future has the same requirements as that of [`ReadHalf::read`].
    fn write(
        &mut self,
        buf: &[u8],
        #[cfg(feature = "std")] fds: &[impl AsFd],
    ) -> impl Future<Output = crate::Result<()>>;
}

/// Trait for fetching peer credentials from a socket.
///
/// This trait provides the low-level capability to fetch credentials from a socket's underlying
/// file descriptor. It is typically implemented by socket read halves that support credentials.
#[cfg(feature = "std")]
pub trait FetchPeerCredentials {
    /// Fetch the peer credentials for this socket.
    ///
    /// This is the low-level method that socket implementations should override to provide peer
    /// credentials. Higher-level APIs should use [`super::Connection::peer_credentials`] instead.
    fn fetch_peer_credentials(&self) -> impl Future<Output = std::io::Result<super::Credentials>>;
}

/// Trait for Unix Domain Sockets.
///
/// Implementing this trait signals that the type is a Unix Domain Socket (UDS) where credentials
/// fetching through a file descriptor will work correctly. [`FetchPeerCredentials`] is implemented
/// for all types that implement this trait.
#[cfg(feature = "std")]
pub trait UnixSocket: AsFd {}

#[cfg(feature = "std")]
impl<T> FetchPeerCredentials for T
where
    T: UnixSocket,
{
    async fn fetch_peer_credentials(&self) -> std::io::Result<super::Credentials> {
        // Assume peer credentials fetching never blocks so it's fine to call this synchronous
        // method from an async context.
        crate::unix_utils::get_peer_credentials(self)
    }
}

/// Documentation-only socket implementations for doc tests.
///
/// These types exist only to make doc tests compile and should never be used in real code.
#[doc(hidden)]
pub mod impl_for_doc {

    /// A mock socket for documentation examples.
    #[derive(Debug)]
    pub struct Socket;

    impl super::Socket for Socket {
        type ReadHalf = ReadHalf;
        type WriteHalf = WriteHalf;

        fn split(self) -> (Self::ReadHalf, Self::WriteHalf) {
            (ReadHalf, WriteHalf)
        }
    }

    /// A mock read half for documentation examples.
    #[derive(Debug)]
    pub struct ReadHalf;

    impl super::ReadHalf for ReadHalf {
        async fn read(&mut self, _buf: &mut [u8]) -> crate::Result<super::ReadResult> {
            unreachable!("This is only for doc tests")
        }
    }

    /// A mock write half for documentation examples.
    #[derive(Debug)]
    pub struct WriteHalf;

    impl super::WriteHalf for WriteHalf {
        async fn write(
            &mut self,
            _buf: &[u8],
            #[cfg(feature = "std")] _fds: &[impl super::AsFd],
        ) -> crate::Result<()> {
            unreachable!("This is only for doc tests")
        }
    }
}