open-net 0.3.5

A cross-platform async networking library for Rust with HTTP and WebSocket clients, network status monitoring, configurable retries, WebSocket reconnection and heartbeats, and managed client lifecycles. Reuse common networking infrastructure across applications to avoid repeated implementation and debugging, helping save development time and AI coding tokens.
Documentation
use crate::error::{ErrorKind, ErrorStage};
use crate::{NetError, Result};
use std::fmt;

/// Validated outbound close frame with a UTF-8 reason of at most 123 bytes.
///
/// `Debug` reports the close code and reason byte count without exposing the reason text.
#[derive(Clone)]
pub struct CloseFrame {
    /// WebSocket wire close code validated by the constructor.
    code: u16,
    /// Reason text sent with the close frame; may be empty.
    reason: String,
}

impl fmt::Debug for CloseFrame {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("CloseFrame")
            .field("code", &self.code)
            .field("reason_len", &self.reason.len())
            .finish()
    }
}

impl CloseFrame {
    /// Validates a wire close code and UTF-8 reason.
    pub fn new(code: u16, reason: impl Into<String>) -> Result<Self> {
        // RFC 6455 ยงยง5.5/7.4 and the IANA WebSocket Close Code registry.
        if !matches!(code, 1000..=1003 | 1007..=1014 | 3000..=4999) {
            return Err(NetError::input(
                "close.code",
                "must be an allowed WebSocket wire close code",
            )
            .with_stage(ErrorStage::Close));
        }
        let reason = reason.into();
        if reason.len() > 123 {
            return Err(
                NetError::input("close.reason", "must be at most 123 UTF-8 bytes")
                    .with_stage(ErrorStage::Close),
            );
        }
        Ok(Self { code, reason })
    }

    /// Returns the validated close code.
    pub fn code(&self) -> u16 {
        self.code
    }

    /// Borrows the close reason.
    pub fn reason(&self) -> &str {
        &self.reason
    }

    pub(crate) fn into_wire(self) -> tokio_tungstenite::tungstenite::protocol::CloseFrame {
        use tokio_tungstenite::tungstenite::protocol::frame::coding::CloseCode;
        // Tungstenite 0.30 maps registered code 1014 to Bad. Preserve its valid
        // numeric wire value using the library's explicit IANA-code variant.
        let code = if self.code == 1014 {
            CloseCode::Iana(self.code)
        } else {
            CloseCode::from(self.code)
        };
        tokio_tungstenite::tungstenite::protocol::CloseFrame {
            code,
            reason: self.reason.into(),
        }
    }
}

/// Peer close information observed by the receiver, including code-less closes.
#[derive(Clone)]
pub struct PeerClose {
    /// Decoded close code; `None` for an empty close frame.
    pub code: Option<u16>,
    /// Complete decoded reason; empty for an empty close frame.
    pub reason: String,
}

impl PeerClose {
    /// Own the decoder's complete UTF-8 reason; an empty Close has no code.
    /// Tungstenite may already have replaced an invalid wire code with its
    /// protocol-error Close before this observation reaches the SDK.
    pub(crate) fn from_frame(
        frame: Option<&tokio_tungstenite::tungstenite::protocol::CloseFrame>,
    ) -> Result<Self> {
        let Some(frame) = frame else {
            return Ok(Self {
                code: None,
                reason: String::new(),
            });
        };
        if frame.reason.len() > 123 {
            // Real network frames are checked by the decoder. Reject malformed
            // internal streams as well, without truncating a UTF-8 sequence.
            return Err(NetError::from(ErrorKind::Protocol).with_stage(ErrorStage::Close));
        }
        let mut reason = String::new();
        reason
            .try_reserve_exact(frame.reason.len())
            .map_err(|error| {
                NetError::with_source(ErrorKind::ResourceExhausted, error)
                    .with_stage(ErrorStage::Close)
            })?;
        reason.push_str(frame.reason.as_str());
        Ok(Self {
            code: Some(u16::from(frame.code)),
            reason,
        })
    }
}

impl fmt::Debug for PeerClose {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("PeerClose")
            .field("code", &self.code)
            .field("reason_len", &self.reason.len())
            .finish()
    }
}

/// I/O notification category that ended a physical connection.
/// An observed peer close is retained even if the close reply write fails.
#[non_exhaustive]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum IoEndKind {
    /// A WebSocket close frame was received from the peer.
    PeerClose,
    /// The stream ended before the expected close handshake completed.
    UnexpectedEof,
    /// The underlying connection was reset.
    ConnectionReset,
    /// A WebSocket protocol error occurred during I/O.
    ProtocolError,
    /// Another I/O, heartbeat, timeout, or internal-channel failure occurred.
    Other,
}

#[cfg(test)]
#[path = "close_tests.rs"]
mod tests;

#[cfg(test)]
#[path = "peer_close_tests.rs"]
mod peer_tests;