zudp 0.4.2

Zero-overhead UDP protocol with optional reliability, fragmentation, and relay support
Documentation
use std::fmt;

use crate::PeerAddr;

#[derive(Debug)]
pub enum Error {
    Io(std::io::Error),

    // encode is infallible (bitcode::encode returns Vec<u8>), so no Encode here.
    #[cfg(all(
        feature = "bitcode",
        not(feature = "serde"),
        not(feature = "rkyv"),
        not(feature = "wincode")
    ))]
    Decode(bitcode::Error),

    #[cfg(all(feature = "serde", not(feature = "bitcode")))]
    Encode(postcard::Error),

    #[cfg(all(feature = "serde", not(feature = "bitcode")))]
    Decode(postcard::Error),

    // Covers: wincode or rkyv (alone or with bitcode), serde+bitcode,
    // serde+rkyv, several at once, none.
    #[cfg(not(any(
        all(
            feature = "bitcode",
            not(feature = "serde"),
            not(feature = "rkyv"),
            not(feature = "wincode")
        ),
        all(feature = "serde", not(feature = "bitcode")),
    )))]
    Encode(Box<dyn std::error::Error + Send + Sync + 'static>),

    #[cfg(not(any(
        all(
            feature = "bitcode",
            not(feature = "serde"),
            not(feature = "rkyv"),
            not(feature = "wincode")
        ),
        all(feature = "serde", not(feature = "bitcode")),
    )))]
    Decode(Box<dyn std::error::Error + Send + Sync + 'static>),

    ChannelClosed,
    /// The engine task stopped unexpectedly.  `reason` explains why.
    EngineStopped {
        reason: String,
    },
    MessageTooLarge {
        got: usize,
        max: usize,
    },
    /// Packet had no bytes — frame type byte is missing.
    FrameEmpty,
    /// Packet was cut short: a required field was absent.
    FrameTruncated {
        frame: &'static str,
        field: &'static str,
    },
    /// Nack body length is not a multiple of 8.
    NackInvalidLength {
        len: usize,
    },
    /// Relay address-family tag was neither 0x00 (v4) nor 0x01 (v6).
    UnknownAddrTag {
        tag: u8,
    },
    /// Frame type byte did not match any known variant.
    UnknownFrameType {
        tag: u8,
    },
    /// Noise protocol error (handshake or AEAD failure).
    #[cfg(feature = "security")]
    Security(snow::Error),

    /// Remote's X25519 key didn't match the pinned key.
    #[cfg(feature = "security")]
    KeyMismatch,

    /// The Noise handshake with `peer` did not complete in time.
    #[cfg(feature = "security")]
    HandshakeTimeout {
        peer: PeerAddr,
    },

    /// Packet dropped — source IP exceeded configured rate limit.
    Throttled,

    /// The relay node cannot deliver to the peer with static key `key`: it is not connected
    /// to the relay, or the relay's policy does not let us reach it (the relay does not say
    /// which).
    #[cfg(feature = "security")]
    Unreachable {
        key: [u8; 32],
    },

    /// Nothing was heard from `peer` for the configured peer timeout; its state was dropped.
    PeerTimeout {
        peer: PeerAddr,
    },

    /// Security is configured but there is no established session with `peer` (never
    /// connected, timed out, removed, or being re-established), so nothing was sent.
    NoSession {
        peer: PeerAddr,
    },
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Io(e) => write!(f, "I/O: {e}"),

            #[cfg(all(
                feature = "bitcode",
                not(feature = "serde"),
                not(feature = "rkyv"),
                not(feature = "wincode")
            ))]
            Self::Decode(e) => write!(f, "decode: {e}"),

            #[cfg(all(feature = "serde", not(feature = "bitcode")))]
            Self::Encode(e) => write!(f, "encode: {e}"),
            #[cfg(all(feature = "serde", not(feature = "bitcode")))]
            Self::Decode(e) => write!(f, "decode: {e}"),

            #[cfg(not(any(
                all(
                    feature = "bitcode",
                    not(feature = "serde"),
                    not(feature = "rkyv"),
                    not(feature = "wincode")
                ),
                all(feature = "serde", not(feature = "bitcode")),
            )))]
            Self::Encode(e) => write!(f, "encode: {e}"),
            #[cfg(not(any(
                all(
                    feature = "bitcode",
                    not(feature = "serde"),
                    not(feature = "rkyv"),
                    not(feature = "wincode")
                ),
                all(feature = "serde", not(feature = "bitcode")),
            )))]
            Self::Decode(e) => write!(f, "decode: {e}"),

            Self::ChannelClosed => f.write_str("channel closed"),
            Self::EngineStopped { reason } => write!(f, "engine stopped: {reason}"),
            Self::MessageTooLarge { got, max } => {
                write!(f, "message needs {got} fragments, max is {max}")
            }
            Self::FrameEmpty => f.write_str("frame parse: empty packet"),
            Self::FrameTruncated { frame, field } => {
                write!(f, "frame parse: {frame} missing `{field}`")
            }
            Self::NackInvalidLength { len } => {
                write!(f, "frame parse: nack body {len} B is not a multiple of 8")
            }
            Self::UnknownAddrTag { tag } => {
                write!(f, "frame parse: unknown relay addr tag 0x{tag:02x}")
            }
            Self::UnknownFrameType { tag } => {
                write!(f, "frame parse: unknown frame type 0x{tag:02x}")
            }
            #[cfg(feature = "security")]
            Self::Security(e) => write!(f, "security: {e}"),
            #[cfg(feature = "security")]
            Self::KeyMismatch => f.write_str("security: remote key does not match pinned key"),
            #[cfg(feature = "security")]
            Self::HandshakeTimeout { peer } => {
                write!(f, "security: handshake with {peer} timed out")
            }
            Self::Throttled => f.write_str("packet dropped: rate limit exceeded"),
            #[cfg(feature = "security")]
            Self::Unreachable { key } => {
                write!(f, "relay cannot reach peer ")?;
                key[..4].iter().try_for_each(|b| write!(f, "{b:02x}"))?;
                f.write_str("…")
            }
            Self::NoSession { peer } => write!(f, "no secure session with {peer}"),
            Self::PeerTimeout { peer } => write!(f, "peer {peer} timed out"),
        }
    }
}

impl std::error::Error for Error {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            Self::Io(e) => Some(e),

            #[cfg(all(
                feature = "bitcode",
                not(feature = "serde"),
                not(feature = "rkyv"),
                not(feature = "wincode")
            ))]
            Self::Decode(e) => Some(e),

            #[cfg(all(feature = "serde", not(feature = "bitcode")))]
            Self::Encode(e) => Some(e),
            #[cfg(all(feature = "serde", not(feature = "bitcode")))]
            Self::Decode(e) => Some(e),

            #[cfg(not(any(
                all(
                    feature = "bitcode",
                    not(feature = "serde"),
                    not(feature = "rkyv"),
                    not(feature = "wincode")
                ),
                all(feature = "serde", not(feature = "bitcode")),
            )))]
            Self::Encode(e) => Some(e.as_ref()),
            #[cfg(not(any(
                all(
                    feature = "bitcode",
                    not(feature = "serde"),
                    not(feature = "rkyv"),
                    not(feature = "wincode")
                ),
                all(feature = "serde", not(feature = "bitcode")),
            )))]
            Self::Decode(e) => Some(e.as_ref()),

            #[cfg(feature = "security")]
            Self::Security(e) => Some(e),
            _ => None,
        }
    }
}

impl From<std::io::Error> for Error {
    fn from(e: std::io::Error) -> Self {
        Self::Io(e)
    }
}

#[cfg(feature = "security")]
impl From<snow::Error> for Error {
    fn from(e: snow::Error) -> Self {
        Self::Security(e)
    }
}