socketio-next 0.2.0

Socket.IO v4 / Engine.IO v4 client with socket.io-client 4.8 parity: async (tokio) and blocking, rustls or native-tls
Documentation
use std::fmt::Debug;
use std::pin::Pin;

use futures_util::{Stream, StreamExt};
use tokio::time::Instant;

use crate::engineio::error::Result;
use crate::engineio::generator::{StreamGenerator, end_after_error};
use crate::engineio::socket::Socket as InnerSocket;
use crate::engineio::{HandshakePacket, Packet, TransportKind};

/// An engine.io client: a [`Stream`] of received packets plus `emit`.
///
/// Clones share one session (no need for an `Arc`): emit from any clone, but read the stream
/// from one task at a time; two tasks polling concurrently would steal each other's wakeups.
#[derive(Clone)]
pub struct Client {
    socket: InnerSocket,
    generator: StreamGenerator<Packet>,
}

impl Client {
    pub(crate) fn new(socket: InnerSocket) -> Self {
        Client {
            socket: socket.clone(),
            generator: StreamGenerator::new(Self::stream(socket)),
        }
    }

    #[cfg(test)]
    pub(crate) fn socket(&self) -> &InnerSocket {
        &self.socket
    }

    /// Closes the session (same as [`disconnect`](Self::disconnect)).
    pub async fn close(&self) -> Result<()> {
        self.socket.disconnect().await
    }

    /// Starts the session after `build*`: the heartbeat deadline runs from here.
    pub async fn connect(&self) -> Result<()> {
        self.socket.connect();
        Ok(())
    }

    /// Sends a close packet (best effort) and closes the session; the stream then ends.
    pub async fn disconnect(&self) -> Result<()> {
        self.socket.disconnect().await
    }

    /// Sends one packet.
    pub async fn emit(&self, packet: Packet) -> Result<()> {
        self.socket.emit(packet).await
    }

    /// Sends several packets in order: batched into as few polling requests as `maxPayload`
    /// allows, or one websocket frame each.
    pub async fn emit_all(&self, packets: Vec<Packet>) -> Result<()> {
        self.socket.emit_all(packets).await
    }

    /// Whether the session is open.
    pub fn is_connected(&self) -> bool {
        self.socket.is_connected()
    }

    /// The server's handshake: sid, upgrades, ping interval / timeout, max payload.
    pub fn handshake(&self) -> &HandshakePacket {
        self.socket.handshake()
    }

    /// The transport of this session.
    pub fn transport(&self) -> TransportKind {
        self.socket.transport().kind()
    }

    /// When the last ping arrived (the session start before the first one).
    pub fn last_ping(&self) -> Instant {
        self.socket.last_ping()
    }

    fn stream(socket: InnerSocket) -> Pin<Box<dyn Stream<Item = Result<Packet>> + 'static + Send>> {
        // Each packet is handled (pong, close, callbacks) before it is passed on; a failed
        // handling ends the stream like a transport error.
        let handled = socket.as_stream().then(move |item| {
            let socket = socket.clone();
            async move {
                let packet: Packet = item?;
                socket.handle_incoming_packet(packet.clone()).await?;
                Ok(packet)
            }
        });
        end_after_error(handled.boxed()).boxed()
    }
}

impl Stream for Client {
    type Item = Result<Packet>;

    fn poll_next(
        mut self: Pin<&mut Self>,
        cx: &mut std::task::Context<'_>,
    ) -> std::task::Poll<Option<Self::Item>> {
        self.generator.poll_next_unpin(cx)
    }
}

impl Debug for Client {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Client")
            .field("socket", &self.socket)
            .finish()
    }
}

#[cfg(test)]
mod test {

    use super::*;
    use crate::engineio::ClientBuilder;
    use futures_util::StreamExt;
    use url::Url;

    /// Reads until `deadline`; `Some(err)` for an error, `None` when it stayed healthy.
    async fn watch(
        socket: &mut Client,
        deadline: std::time::Duration,
    ) -> Option<crate::engineio::Error> {
        let end = tokio::time::Instant::now() + deadline;
        loop {
            match tokio::time::timeout_at(end, socket.next()).await {
                Err(_) => return None,
                Ok(Some(Err(err))) => return Some(err),
                Ok(Some(Ok(_))) => continue,
                Ok(None) => return Some(crate::engineio::Error::NotConnected),
            }
        }
    }

    /// A system sleep on a dead link: the monotonic timer has most of pingInterval +
    /// pingTimeout (45 s here) to go, the wall clock says the deadline passed. The probe gets
    /// no answer and the link is declared dead after pingTimeout (20 s), not 45 s.
    #[tokio::test]
    async fn a_sleep_on_a_dead_link_is_a_ping_timeout_after_ping_timeout() -> Result<()> {
        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
            let tcp = socketio_next_testing::Proxy::start(&socketio_next_testing::host_port(
                crate::engineio::test::engine_io_server()?.as_str(),
            ))
            .await;
            let mut socket = builder(Url::parse(&tcp.url())?).build_polling().await?;
            socket.connect().await?;
            // the link is dead: open connections stall, new ones are refused
            tcp.refuse(true);
            tcp.freeze();
            let started = std::time::Instant::now();
            socket
                .socket
                .shift_wall_clock(std::time::Duration::from_secs(3600), true);
            let err = watch(&mut socket, std::time::Duration::from_secs(30)).await;
            assert!(
                matches!(err, Some(crate::engineio::Error::PingTimeout)),
                "{err:?}"
            );
            let took = started.elapsed();
            assert!(
                took >= std::time::Duration::from_secs(19),
                "probed first: {took:?}"
            );
            assert!(took < std::time::Duration::from_secs(25), "{took:?}");
            tcp.cut();
            Ok(())
        })
        .await
        .expect("test `a_sleep_on_a_dead_link_is_a_ping_timeout_after_ping_timeout` timed out")
    }

    /// A forward clock step (NTP on a gateway without RTC) on a live link: the probe is
    /// answered (a noop POST, or a websocket ping), nothing closes. On the fast-ping server
    /// (pingInterval 300 ms, pingTimeout 200 ms), stepped right after a ping: the next ping is
    /// ~300 ms away, so without the probe the 200 ms grace would end the link.
    #[tokio::test]
    async fn a_forward_clock_step_on_a_live_link_keeps_it() -> Result<()> {
        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
            let mut url = Url::parse(&socketio_next_testing::fast_ping_server())?;
            url.set_path("/socket.io/");
            for websocket in [false, true] {
                let mut socket = if websocket {
                    builder(url.clone()).build_websocket().await?
                } else {
                    builder(url.clone()).build_polling().await?
                };
                socket.connect().await?;
                // a ping arrived: the clock is stepped right after it
                loop {
                    let packet =
                        tokio::time::timeout(std::time::Duration::from_secs(5), socket.next())
                            .await
                            .expect("a ping")
                            .expect("open")?;
                    if packet.packet_id == crate::engineio::PacketId::Ping {
                        break;
                    }
                }
                socket
                    .socket
                    .shift_wall_clock(std::time::Duration::from_secs(3600), true);
                // longer than pingTimeout (200), shorter than pingInterval (300)
                let err = watch(&mut socket, std::time::Duration::from_millis(260)).await;
                assert!(err.is_none(), "websocket={websocket}: {err:?}");
                assert!(socket.is_connected());
                socket.disconnect().await?;
            }
            Ok(())
        })
        .await
        .expect("test `a_forward_clock_step_on_a_live_link_keeps_it` timed out")
    }

    /// A backward step changes nothing.
    #[tokio::test]
    async fn a_backward_clock_step_has_no_effect() -> Result<()> {
        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
            let url = crate::engineio::test::engine_io_server()?;
            let mut socket = builder(url).build_polling().await?;
            socket.connect().await?;
            socket
                .socket
                .shift_wall_clock(std::time::Duration::from_secs(3600), false);
            assert!(
                watch(&mut socket, std::time::Duration::from_secs(1))
                    .await
                    .is_none()
            );
            socket.disconnect().await?;
            Ok(())
        })
        .await
        .expect("test `a_backward_clock_step_has_no_effect` timed out")
    }

    fn builder(url: Url) -> ClientBuilder {
        ClientBuilder::new(url)
            .on_open(|_| async {
                println!("Open event!");
            })
            .on_packet(|packet| async move {
                println!("Received packet: {:?}", packet);
            })
            .on_data(|data| async move {
                println!("Received data: {:?}", std::str::from_utf8(&data));
            })
            .on_close(|_| async {
                println!("Close event!");
            })
            .on_error(|error| async move {
                println!("Error {}", error);
            })
    }
}