Skip to main content

socketio_next/engineio/
client.rs

1use std::fmt::Debug;
2use std::pin::Pin;
3
4use futures_util::{Stream, StreamExt};
5use tokio::time::Instant;
6
7use crate::engineio::error::Result;
8use crate::engineio::generator::{StreamGenerator, end_after_error};
9use crate::engineio::socket::Socket as InnerSocket;
10use crate::engineio::{HandshakePacket, Packet, TransportKind};
11
12/// An engine.io client: a [`Stream`] of received packets plus `emit`.
13///
14/// Clones share one session (no need for an `Arc`): emit from any clone, but read the stream
15/// from one task at a time; two tasks polling concurrently would steal each other's wakeups.
16#[derive(Clone)]
17pub struct Client {
18    socket: InnerSocket,
19    generator: StreamGenerator<Packet>,
20}
21
22impl Client {
23    pub(crate) fn new(socket: InnerSocket) -> Self {
24        Client {
25            socket: socket.clone(),
26            generator: StreamGenerator::new(Self::stream(socket)),
27        }
28    }
29
30    #[cfg(test)]
31    pub(crate) fn socket(&self) -> &InnerSocket {
32        &self.socket
33    }
34
35    /// Closes the session (same as [`disconnect`](Self::disconnect)).
36    pub async fn close(&self) -> Result<()> {
37        self.socket.disconnect().await
38    }
39
40    /// Starts the session after `build*`: the heartbeat deadline runs from here.
41    pub async fn connect(&self) -> Result<()> {
42        self.socket.connect();
43        Ok(())
44    }
45
46    /// Sends a close packet (best effort) and closes the session; the stream then ends.
47    pub async fn disconnect(&self) -> Result<()> {
48        self.socket.disconnect().await
49    }
50
51    /// Sends one packet.
52    pub async fn emit(&self, packet: Packet) -> Result<()> {
53        self.socket.emit(packet).await
54    }
55
56    /// Sends several packets in order: batched into as few polling requests as `maxPayload`
57    /// allows, or one websocket frame each.
58    pub async fn emit_all(&self, packets: Vec<Packet>) -> Result<()> {
59        self.socket.emit_all(packets).await
60    }
61
62    /// Whether the session is open.
63    pub fn is_connected(&self) -> bool {
64        self.socket.is_connected()
65    }
66
67    /// The server's handshake: sid, upgrades, ping interval / timeout, max payload.
68    pub fn handshake(&self) -> &HandshakePacket {
69        self.socket.handshake()
70    }
71
72    /// The transport of this session.
73    pub fn transport(&self) -> TransportKind {
74        self.socket.transport().kind()
75    }
76
77    /// When the last ping arrived (the session start before the first one).
78    pub fn last_ping(&self) -> Instant {
79        self.socket.last_ping()
80    }
81
82    fn stream(socket: InnerSocket) -> Pin<Box<dyn Stream<Item = Result<Packet>> + 'static + Send>> {
83        // Each packet is handled (pong, close, callbacks) before it is passed on; a failed
84        // handling ends the stream like a transport error.
85        let handled = socket.as_stream().then(move |item| {
86            let socket = socket.clone();
87            async move {
88                let packet: Packet = item?;
89                socket.handle_incoming_packet(packet.clone()).await?;
90                Ok(packet)
91            }
92        });
93        end_after_error(handled.boxed()).boxed()
94    }
95}
96
97impl Stream for Client {
98    type Item = Result<Packet>;
99
100    fn poll_next(
101        mut self: Pin<&mut Self>,
102        cx: &mut std::task::Context<'_>,
103    ) -> std::task::Poll<Option<Self::Item>> {
104        self.generator.poll_next_unpin(cx)
105    }
106}
107
108impl Debug for Client {
109    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
110        f.debug_struct("Client")
111            .field("socket", &self.socket)
112            .finish()
113    }
114}
115
116#[cfg(test)]
117mod test {
118
119    use super::*;
120    use crate::engineio::{ClientBuilder, DEFAULT_TIMEOUT as HANDSHAKE_TIMEOUT, Error, PacketId};
121    use bytes::Bytes;
122    use futures_util::StreamExt;
123    use http::HeaderMap;
124    use url::Url;
125
126    /// The purpose of this test is to check whether the Client is properly cloneable or not.
127    /// As the documentation of the engine.io client states, the object needs to maintain it's internal
128    /// state when cloned and the cloned object should reflect the same state throughout the lifetime
129    /// of both objects (initial and cloned).
130    /// Reads until `deadline`; `Some(err)` for an error, `None` when it stayed healthy.
131    async fn watch(
132        socket: &mut Client,
133        deadline: std::time::Duration,
134    ) -> Option<crate::engineio::Error> {
135        let end = tokio::time::Instant::now() + deadline;
136        loop {
137            match tokio::time::timeout_at(end, socket.next()).await {
138                Err(_) => return None,
139                Ok(Some(Err(err))) => return Some(err),
140                Ok(Some(Ok(_))) => continue,
141                Ok(None) => return Some(crate::engineio::Error::NotConnected),
142            }
143        }
144    }
145
146    /// A system sleep on a dead link: the monotonic timer has most of pingInterval +
147    /// pingTimeout (45 s here) to go, the wall clock says the deadline passed. The probe gets
148    /// no answer and the link is declared dead after pingTimeout (20 s), not 45 s.
149    #[tokio::test]
150    async fn a_sleep_on_a_dead_link_is_a_ping_timeout_after_ping_timeout() -> Result<()> {
151        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
152            let tcp = socketio_next_testing::Proxy::start(&socketio_next_testing::host_port(
153                crate::engineio::test::engine_io_server()?.as_str(),
154            ))
155            .await;
156            let mut socket = builder(Url::parse(&tcp.url())?).build_polling().await?;
157            socket.connect().await?;
158            // the link is dead: open connections stall, new ones are refused
159            tcp.refuse(true);
160            tcp.freeze();
161            let started = std::time::Instant::now();
162            socket
163                .socket
164                .shift_wall_clock(std::time::Duration::from_secs(3600), true);
165            let err = watch(&mut socket, std::time::Duration::from_secs(30)).await;
166            assert!(
167                matches!(err, Some(crate::engineio::Error::PingTimeout)),
168                "{err:?}"
169            );
170            let took = started.elapsed();
171            assert!(
172                took >= std::time::Duration::from_secs(19),
173                "probed first: {took:?}"
174            );
175            assert!(took < std::time::Duration::from_secs(25), "{took:?}");
176            tcp.cut();
177            Ok(())
178        })
179        .await
180        .expect("test `a_sleep_on_a_dead_link_is_a_ping_timeout_after_ping_timeout` timed out")
181    }
182
183    /// A forward clock step (NTP on a gateway without RTC) on a live link: the probe is
184    /// answered (a noop POST, or a websocket ping), nothing closes. On the fast-ping server
185    /// (pingInterval 300 ms, pingTimeout 200 ms), stepped right after a ping: the next ping is
186    /// ~300 ms away, so without the probe the 200 ms grace would end the link.
187    #[tokio::test]
188    async fn a_forward_clock_step_on_a_live_link_keeps_it() -> Result<()> {
189        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
190            let mut url = Url::parse(&socketio_next_testing::fast_ping_server())?;
191            url.set_path("/socket.io/");
192            for websocket in [false, true] {
193                let mut socket = if websocket {
194                    builder(url.clone()).build_websocket().await?
195                } else {
196                    builder(url.clone()).build_polling().await?
197                };
198                socket.connect().await?;
199                // a ping arrived: the clock is stepped right after it
200                loop {
201                    let packet =
202                        tokio::time::timeout(std::time::Duration::from_secs(5), socket.next())
203                            .await
204                            .expect("a ping")
205                            .expect("open")?;
206                    if packet.packet_id == crate::engineio::PacketId::Ping {
207                        break;
208                    }
209                }
210                socket
211                    .socket
212                    .shift_wall_clock(std::time::Duration::from_secs(3600), true);
213                // longer than pingTimeout (200), shorter than pingInterval (300)
214                let err = watch(&mut socket, std::time::Duration::from_millis(260)).await;
215                assert!(err.is_none(), "websocket={websocket}: {err:?}");
216                assert!(socket.is_connected());
217                socket.disconnect().await?;
218            }
219            Ok(())
220        })
221        .await
222        .expect("test `a_forward_clock_step_on_a_live_link_keeps_it` timed out")
223    }
224
225    /// A backward step changes nothing.
226    #[tokio::test]
227    async fn a_backward_clock_step_has_no_effect() -> Result<()> {
228        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
229            let url = crate::engineio::test::engine_io_server()?;
230            let mut socket = builder(url).build_polling().await?;
231            socket.connect().await?;
232            socket
233                .socket
234                .shift_wall_clock(std::time::Duration::from_secs(3600), false);
235            assert!(
236                watch(&mut socket, std::time::Duration::from_secs(1))
237                    .await
238                    .is_none()
239            );
240            socket.disconnect().await?;
241            Ok(())
242        })
243        .await
244        .expect("test `a_backward_clock_step_has_no_effect` timed out")
245    }
246
247    #[tokio::test]
248    async fn test_client_cloneable() -> Result<()> {
249        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
250            let url = crate::engineio::test::engine_io_server()?;
251
252            let mut sut = builder(url).build().await?;
253            let mut cloned = sut.clone();
254
255            sut.connect().await?;
256
257            // when the underlying socket is connected, the
258            // state should also change on the cloned one
259            assert!(sut.is_connected());
260            assert!(cloned.is_connected());
261
262            // both clients should reflect the same messages.
263            assert_eq!(
264                sut.next().await.unwrap()?,
265                Packet::new(PacketId::Message, "hello client")
266            );
267
268            sut.emit(Packet::new(PacketId::Message, "respond")).await?;
269
270            assert_eq!(
271                cloned.next().await.unwrap()?,
272                Packet::new(PacketId::Message, "Roger Roger")
273            );
274
275            cloned.disconnect().await?;
276
277            // when the underlying socket is disconnected, the
278            // state should also change on the cloned one
279            assert!(!sut.is_connected());
280            assert!(!cloned.is_connected());
281
282            Ok(())
283        })
284        .await
285        .expect("test `test_client_cloneable` timed out")
286    }
287
288    /// A polling response bigger than one HTTP body chunk must still be decoded as one payload.
289    #[tokio::test]
290    async fn test_polling_large_message() -> Result<()> {
291        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
292            let url = crate::engineio::test::engine_io_polling_server()?;
293            let mut socket = builder(url).build_polling().await?;
294            socket.connect().await?;
295
296            assert_eq!(
297                socket.next().await.unwrap()?,
298                Packet::new(PacketId::Message, "hello client")
299            );
300
301            socket
302                .emit(Packet::new(PacketId::Message, "respond_large"))
303                .await?;
304
305            assert_eq!(
306                socket.next().await.unwrap()?,
307                Packet::new(PacketId::Message, "x".repeat(64 * 1024))
308            );
309
310            socket.disconnect().await
311        })
312        .await
313        .expect("test `test_polling_large_message` timed out")
314    }
315
316    /// A peer that accepts TCP but never answers (blackholed proxy, half-open link) must not hang
317    /// the polling handshake forever.
318    #[tokio::test(start_paused = true)]
319    async fn test_polling_handshake_times_out() {
320        let silent = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
321        let url = Url::parse(&format!("http://{}/", silent.local_addr().unwrap())).unwrap();
322
323        let result = tokio::time::timeout(
324            HANDSHAKE_TIMEOUT * 2,
325            ClientBuilder::new(url).build_polling(),
326        )
327        .await
328        .expect("polling handshake hung past its timeout");
329        assert!(result.is_err());
330    }
331
332    /// After disconnect() the packet stream ends instead of polling a closed session.
333    #[tokio::test]
334    async fn test_stream_ends_after_disconnect() {
335        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
336            for url in [
337                crate::engineio::test::engine_io_polling_server().unwrap(),
338                crate::engineio::test::engine_io_server().unwrap(),
339            ] {
340                let mut socket = builder(url).build().await.unwrap();
341                socket.connect().await.unwrap();
342                socket.disconnect().await.unwrap();
343                assert!(!socket.is_connected());
344
345                let next = tokio::time::timeout(std::time::Duration::from_secs(5), socket.next())
346                    .await
347                    .expect("stream still waiting after disconnect");
348                assert!(next.is_none(), "stream yielded {next:?} after disconnect");
349            }
350        })
351        .await
352        .expect("test `test_stream_ends_after_disconnect` timed out")
353    }
354
355    #[tokio::test(start_paused = true)]
356    async fn test_websocket_connect_times_out() {
357        let silent = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
358        let url = Url::parse(&format!("http://{}/", silent.local_addr().unwrap())).unwrap();
359
360        let result = tokio::time::timeout(
361            HANDSHAKE_TIMEOUT * 2,
362            ClientBuilder::new(url).build_websocket(),
363        )
364        .await
365        .expect("websocket connect hung past its timeout");
366        assert!(result.is_err());
367    }
368
369    #[tokio::test]
370    async fn test_illegal_actions() -> Result<()> {
371        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
372            let url = crate::engineio::test::engine_io_server()?;
373            let mut sut = builder(url.clone()).build().await?;
374
375            assert!(
376                sut.emit(Packet::new(PacketId::Close, Bytes::new()))
377                    .await
378                    .is_err()
379            );
380
381            sut.connect().await?;
382
383            assert!(sut.next().await.unwrap().is_ok());
384
385            assert!(
386                builder(Url::parse("fake://fake.fake").unwrap())
387                    .build_websocket()
388                    .await
389                    .is_err()
390            );
391
392            sut.disconnect().await?;
393
394            Ok(())
395        })
396        .await
397        .expect("test `test_illegal_actions` timed out")
398    }
399
400    use reqwest::header::HOST;
401
402    fn builder(url: Url) -> ClientBuilder {
403        ClientBuilder::new(url)
404            .on_open(|_| async {
405                println!("Open event!");
406            })
407            .on_packet(|packet| async move {
408                println!("Received packet: {:?}", packet);
409            })
410            .on_data(|data| async move {
411                println!("Received data: {:?}", std::str::from_utf8(&data));
412            })
413            .on_close(|_| async {
414                println!("Close event!");
415            })
416            .on_error(|error| async move {
417                println!("Error {}", error);
418            })
419    }
420
421    async fn test_connection(socket: Client) -> Result<()> {
422        let mut socket = socket;
423
424        socket.connect().await.unwrap();
425
426        assert_eq!(
427            socket.next().await.unwrap()?,
428            Packet::new(PacketId::Message, "hello client")
429        );
430        println!("received msg, about to send");
431
432        socket
433            .emit(Packet::new(PacketId::Message, "respond"))
434            .await?;
435
436        println!("send msg");
437
438        assert_eq!(
439            socket.next().await.unwrap()?,
440            Packet::new(PacketId::Message, "Roger Roger")
441        );
442        println!("received 2");
443
444        socket.close().await
445    }
446
447    #[tokio::test]
448    async fn test_connection_long() -> Result<()> {
449        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
450            // Long lived socket to receive pings
451            let url = crate::engineio::test::engine_io_server()?;
452            let mut socket = builder(url).build().await?;
453
454            socket.connect().await?;
455
456            // hello client
457            assert!(matches!(
458                socket.next().await.unwrap()?,
459                Packet {
460                    packet_id: PacketId::Message,
461                    ..
462                }
463            ));
464            // Ping
465            assert!(matches!(
466                socket.next().await.unwrap()?,
467                Packet {
468                    packet_id: PacketId::Ping,
469                    ..
470                }
471            ));
472
473            socket.disconnect().await?;
474
475            assert!(!socket.is_connected());
476
477            Ok(())
478        })
479        .await
480        .expect("test `test_connection_long` timed out")
481    }
482
483    #[tokio::test]
484    async fn test_connection_dynamic() -> Result<()> {
485        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
486            let url = crate::engineio::test::engine_io_server()?;
487            let socket = builder(url).build().await?;
488            test_connection(socket).await?;
489
490            let url = crate::engineio::test::engine_io_polling_server()?;
491            let socket = builder(url).build().await?;
492            test_connection(socket).await
493        })
494        .await
495        .expect("test `test_connection_dynamic` timed out")
496    }
497
498    #[tokio::test]
499    async fn test_connection_fallback() -> Result<()> {
500        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
501            let url = crate::engineio::test::engine_io_server()?;
502            let socket = builder(url).build_with_fallback().await?;
503            test_connection(socket).await?;
504
505            let url = crate::engineio::test::engine_io_polling_server()?;
506            let socket = builder(url).build_with_fallback().await?;
507            test_connection(socket).await
508        })
509        .await
510        .expect("test `test_connection_fallback` timed out")
511    }
512
513    #[cfg(any(feature = "rustls", feature = "native-tls"))]
514    #[tokio::test]
515    async fn test_connection_dynamic_secure() -> Result<()> {
516        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
517            let url = crate::engineio::test::engine_io_server_secure()?;
518            let mut socket_builder = builder(url);
519            socket_builder = socket_builder.tls_config(crate::engineio::test::tls_config()?);
520            let socket = socket_builder.build().await?;
521            test_connection(socket).await
522        })
523        .await
524        .expect("test `test_connection_dynamic_secure` timed out")
525    }
526
527    #[tokio::test]
528    async fn test_connection_polling() -> Result<()> {
529        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
530            let url = crate::engineio::test::engine_io_server()?;
531            let socket = builder(url).build_polling().await?;
532            test_connection(socket).await
533        })
534        .await
535        .expect("test `test_connection_polling` timed out")
536    }
537
538    #[cfg(any(feature = "rustls", feature = "native-tls"))]
539    #[tokio::test]
540    async fn test_connection_wss() -> Result<()> {
541        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
542            let url = crate::engineio::test::engine_io_polling_server()?;
543            assert!(builder(url).build_websocket_with_upgrade().await.is_err());
544
545            let host =
546                std::env::var("ENGINE_IO_SECURE_HOST").unwrap_or_else(|_| "localhost".to_owned());
547            let mut url = crate::engineio::test::engine_io_server_secure()?;
548
549            let mut headers = HeaderMap::default();
550            headers.insert(HOST, host.parse().unwrap());
551            let mut builder = builder(url.clone());
552
553            builder = builder.tls_config(crate::engineio::test::tls_config()?);
554            builder = builder.headers(headers.clone());
555            let socket = builder.clone().build_websocket_with_upgrade().await?;
556
557            test_connection(socket).await?;
558
559            let socket = builder.build_websocket().await?;
560
561            test_connection(socket).await?;
562
563            url.set_scheme("wss").unwrap();
564
565            let builder = self::builder(url)
566                .tls_config(crate::engineio::test::tls_config()?)
567                .headers(headers);
568            let socket = builder.clone().build_websocket().await?;
569
570            test_connection(socket).await?;
571
572            assert!(builder.build_websocket_with_upgrade().await.is_err());
573
574            Ok(())
575        })
576        .await
577        .expect("test `test_connection_wss` timed out")
578    }
579
580    #[tokio::test]
581    async fn test_connection_ws() -> Result<()> {
582        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
583            let url = crate::engineio::test::engine_io_polling_server()?;
584            assert!(builder(url.clone()).build_websocket().await.is_err());
585            assert!(builder(url).build_websocket_with_upgrade().await.is_err());
586
587            let mut url = crate::engineio::test::engine_io_server()?;
588
589            let builder = builder(url.clone());
590            let socket = builder.clone().build_websocket().await?;
591            test_connection(socket).await?;
592
593            let socket = builder.build_websocket_with_upgrade().await?;
594            test_connection(socket).await?;
595
596            url.set_scheme("ws").unwrap();
597
598            let builder = self::builder(url);
599            let socket = builder.clone().build_websocket().await?;
600
601            test_connection(socket).await?;
602
603            assert!(builder.build_websocket_with_upgrade().await.is_err());
604
605            Ok(())
606        })
607        .await
608        .expect("test `test_connection_ws` timed out")
609    }
610
611    #[tokio::test]
612    async fn test_open_invariants() -> Result<()> {
613        tokio::time::timeout(std::time::Duration::from_secs(90), async move {
614            let url = crate::engineio::test::engine_io_server()?;
615            let illegal_url = "this is illegal";
616
617            assert!(Url::parse(illegal_url).is_err());
618
619            let invalid_protocol = "file:///tmp/foo";
620            assert!(
621                builder(Url::parse(invalid_protocol).unwrap())
622                    .build()
623                    .await
624                    .is_err()
625            );
626
627            let sut = builder(url.clone()).build().await?;
628            let _error = sut
629                .emit(Packet::new(PacketId::Close, Bytes::new()))
630                .await
631                .expect_err("error");
632            assert!(matches!(_error, Error::NotConnected));
633
634            // test missing match arm in socket constructor
635            let mut headers = HeaderMap::default();
636            let host =
637                std::env::var("ENGINE_IO_SECURE_HOST").unwrap_or_else(|_| "localhost".to_owned());
638            headers.insert(HOST, host.parse().unwrap());
639
640            let _ = builder(url.clone()).build().await?;
641            let _ = builder(url).headers(headers).build().await?;
642            Ok(())
643        })
644        .await
645        .expect("test `test_open_invariants` timed out")
646    }
647}