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
//! Physical-connection diagnostics, independent of the winning terminal cause.

use crate::ws::{IoEndKind, PeerClose};
use futures_util::Sink;
use std::pin::Pin;
use std::sync::OnceLock;
use std::task::{Context, Poll};
use tokio_tungstenite::tungstenite::{error::ProtocolError, Error as WsError, Message};

/// Each ActiveIo owns a fresh cell. The reader stores its first decoded Close
/// before awaiting the writer. The worker snapshots only after joining both
/// tasks, so queue pressure, cancellation and write failures cannot erase it.
pub(crate) type PeerCloseObservation = OnceLock<PeerClose>;

#[derive(Clone, Default)]
pub(crate) struct ConnectionTerminationDetails {
    pub(crate) peer_close: Option<PeerClose>,
    pub(crate) io_end_kind: Option<IoEndKind>,
}

pub(crate) fn classify_io_error(error: &WsError) -> IoEndKind {
    match error {
        WsError::Io(error) => match error.kind() {
            std::io::ErrorKind::UnexpectedEof => IoEndKind::UnexpectedEof,
            std::io::ErrorKind::ConnectionReset => IoEndKind::ConnectionReset,
            _ => IoEndKind::Other,
        },
        WsError::Protocol(ProtocolError::ResetWithoutClosingHandshake) => IoEndKind::UnexpectedEof,
        WsError::Protocol(_) | WsError::Utf8(_) => IoEndKind::ProtocolError,
        _ => IoEndKind::Other,
    }
}

/// Capture a writer's first raw failure before existing helpers reduce it to
/// NetError. No request-delivery, timeout or retry behavior is changed. Every
/// error from these Sink operations already retires the writer; timeouts and
/// other failures that never reach the sink remain `Other`.
pub(crate) struct ClassifiedSink<W> {
    inner: W,
    first_error: Option<IoEndKind>,
}

impl<W> ClassifiedSink<W> {
    pub(crate) fn new(inner: W) -> Self {
        Self {
            inner,
            first_error: None,
        }
    }

    pub(crate) fn end_kind(&self) -> IoEndKind {
        match self.first_error {
            Some(kind) => kind,
            None => IoEndKind::Other,
        }
    }

    fn observe(&mut self, result: &Result<(), WsError>) {
        if let Err(error) = result {
            if matches!(error, WsError::WriteBufferFull(_)) {
                return;
            }
            self.first_error
                .get_or_insert_with(|| classify_io_error(error));
        }
    }

    fn observe_poll(&mut self, result: Poll<Result<(), WsError>>) -> Poll<Result<(), WsError>> {
        if let Poll::Ready(result) = &result {
            self.observe(result);
        }
        result
    }
}

impl<W: Sink<Message, Error = WsError> + Unpin> Sink<Message> for ClassifiedSink<W> {
    type Error = WsError;

    fn poll_ready(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        let result = Pin::new(&mut self.inner).poll_ready(cx);
        self.observe_poll(result)
    }

    fn start_send(mut self: Pin<&mut Self>, item: Message) -> Result<(), Self::Error> {
        let result = Pin::new(&mut self.inner).start_send(item);
        self.observe(&result);
        result
    }

    fn poll_flush(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        let result = Pin::new(&mut self.inner).poll_flush(cx);
        self.observe_poll(result)
    }

    fn poll_close(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        let result = Pin::new(&mut self.inner).poll_close(cx);
        self.observe_poll(result)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::module::ws_client::test_support::{check, check_eq, TestResult};
    use std::future::poll_fn;

    #[derive(Clone, Copy, PartialEq)]
    enum FailAt {
        Ready,
        Send,
        Flush,
        Close,
    }

    struct ResetSink(FailAt);

    impl ResetSink {
        fn result(&self, operation: FailAt) -> Result<(), WsError> {
            if self.0 == operation {
                Err(WsError::Io(std::io::Error::from(
                    std::io::ErrorKind::ConnectionReset,
                )))
            } else {
                Ok(())
            }
        }
    }

    impl Sink<Message> for ResetSink {
        type Error = WsError;
        fn poll_ready(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), WsError>> {
            Poll::Ready(self.result(FailAt::Ready))
        }
        fn start_send(self: Pin<&mut Self>, _: Message) -> Result<(), WsError> {
            self.result(FailAt::Send)
        }
        fn poll_flush(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), WsError>> {
            Poll::Ready(self.result(FailAt::Flush))
        }
        fn poll_close(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Result<(), WsError>> {
            Poll::Ready(self.result(FailAt::Close))
        }
    }

    #[tokio::test]
    async fn writer_reset_classification_survives_every_sink_error_boundary() -> TestResult {
        for operation in [FailAt::Ready, FailAt::Send, FailAt::Flush, FailAt::Close] {
            let mut sink = ClassifiedSink::new(ResetSink(operation));
            check_eq!(sink.end_kind(), IoEndKind::Other)?;
            let result = match operation {
                FailAt::Ready => poll_fn(|cx| Pin::new(&mut sink).poll_ready(cx)).await,
                FailAt::Send => Pin::new(&mut sink).start_send(Message::Close(None)),
                FailAt::Flush => poll_fn(|cx| Pin::new(&mut sink).poll_flush(cx)).await,
                FailAt::Close => poll_fn(|cx| Pin::new(&mut sink).poll_close(cx)).await,
            };
            check!(
                matches!(result, Err(WsError::Io(ref error)) if error.kind() == std::io::ErrorKind::ConnectionReset)
            )?;
            check_eq!(sink.end_kind(), IoEndKind::ConnectionReset)?;
        }
        Ok(())
    }

    #[tokio::test]
    async fn close_reply_flush_reset_reaches_write_ended_before_error_details_are_lost(
    ) -> TestResult {
        use crate::module::ws_client::{
            heartbeat_state::HeartbeatState,
            io_event::IoEvent,
            write::{
                control_message::ControlMessage, priority_write_queue::PriorityWriteQueue,
                write_loop_context::WriteLoopContext,
            },
            ws_write::run_write_loop,
        };
        use std::{sync::Arc, time::Duration};
        use tokio::sync::{mpsc, oneshot};
        use tokio_util::sync::CancellationToken;

        let (control_tx, control_rx) = mpsc::channel(1);
        let (done_tx, done_rx) = oneshot::channel();
        control_tx.send(ControlMessage::PeerClose(done_tx)).await?;
        let (io_event_tx, mut events) = mpsc::channel(1);
        tokio::time::timeout(
            Duration::from_secs(1),
            run_write_loop(
                ResetSink(FailAt::Flush),
                WriteLoopContext {
                    cancel_domain_gate: None,
                    queue: PriorityWriteQueue::new(1, 64)?,
                    urgent_queue: PriorityWriteQueue::new(1, 64)?,
                    control_rx,
                    pending_requests: crate::module::ws_client::v2_test_support::pending(1)?,
                    io_event_tx,
                    generation: 17,
                    cancel: CancellationToken::new(),
                    data_frame_payload_size: None,
                    max_write_buffer_size: 4 * 1024 * 1024,
                    control_write_timeout: Duration::from_secs(1),
                    data_frame_write_timeout: Duration::from_secs(1),
                    heartbeat_config: Some(crate::ws::HeartbeatConfig {
                        interval: Duration::from_secs(60),
                        pong_timeout: Duration::from_secs(5),
                        ..Default::default()
                    }),
                    heartbeat: Arc::new(HeartbeatState::new(17)),
                },
                CancellationToken::new(),
            ),
        )
        .await?;
        let acknowledgement = done_rx.await?;
        check!(
            matches!(acknowledgement, Err(error) if error.kind() == crate::error::ErrorKind::Io && error.io_kind() == Some(std::io::ErrorKind::ConnectionReset))
        )?;
        check!(matches!(
            events.try_recv()?,
            IoEvent::WriteEnded {
                generation: 17,
                error,
                kind: IoEndKind::ConnectionReset,
            } if matches!(error.kind(), crate::error::ErrorKind::Io)))?;
        check!(events.try_recv().is_err())?;
        Ok(())
    }

    #[test]
    fn raw_io_classification_separates_eof_reset_and_protocol_errors() -> TestResult {
        for (error, kind) in [
            (
                WsError::Protocol(ProtocolError::ResetWithoutClosingHandshake),
                IoEndKind::UnexpectedEof,
            ),
            (
                WsError::Io(std::io::Error::from(std::io::ErrorKind::UnexpectedEof)),
                IoEndKind::UnexpectedEof,
            ),
            (
                WsError::Io(std::io::Error::from(std::io::ErrorKind::ConnectionReset)),
                IoEndKind::ConnectionReset,
            ),
            (
                WsError::Protocol(ProtocolError::FragmentedControlFrame),
                IoEndKind::ProtocolError,
            ),
            (
                WsError::Io(std::io::Error::from(std::io::ErrorKind::TimedOut)),
                IoEndKind::Other,
            ),
            (WsError::ConnectionClosed, IoEndKind::Other),
        ] {
            check_eq!(classify_io_error(&error), kind)?;
        }
        Ok(())
    }

    #[test]
    fn write_buffer_full_does_not_hide_a_later_terminal_io_classification() -> TestResult {
        let mut sink = ClassifiedSink::new(ResetSink(FailAt::Send));
        let buffered = Err(WsError::WriteBufferFull(Box::new(Message::Ping(
            bytes::Bytes::from_static(b"probe"),
        ))));
        sink.observe(&buffered);
        check_eq!(sink.end_kind(), IoEndKind::Other)?;
        let reset = Err(WsError::Io(std::io::Error::from(
            std::io::ErrorKind::ConnectionReset,
        )));
        sink.observe(&reset);
        check_eq!(sink.end_kind(), IoEndKind::ConnectionReset)?;
        Ok(())
    }
}