Getting started

Introduction

What socketio-next is, what it does like socket.io-client, and what lives in this repository.

socketio-next is a Socket.IO v4 client for Rust that behaves like the reference JavaScript client (socket.io-client 4.8 / engine.io-client 6.6):

  • namespaces and auth (a JSON object, or a closure that runs before every attempt);
  • acks in both directions: awaitable acks with a timeout, and answers to the server's callbacks;
  • binary data anywhere in the arguments, with the socket.io-parser encoding;
  • reconnection with the same backoff (delay, maximum, jitter) and connection state recovery;
  • polling and websocket transports, upgrade or websocket only, HTTP proxies;
  • TLS through rustls (default) or native-tls, private CAs, the operating system's trust store.

The client is async (tokio). The blocking feature adds the same client with blocking methods. State and errors are typed: ConnectionState, DisconnectReason, LinkInfo and one cloneable Error.

use socketio_next::{Client, ClientBuilder, ConnectionState, Event};

let client = ClientBuilder::new("http://localhost:3000")
    .on("chat", |event: Event, _: Client| async move {
        println!("chat: {:?}", event.payload());
    })
    .on_state_change(|state: ConnectionState, _: Client| async move {
        println!("{state:?}");
    })
    .connect()
    .await?;
client.emit("chat", "hello")?;

What is in the repository

PackageWhereWhat
socketio-nextcrates/socketio-nextThe client, engineio (transport layer) and protocol (packet codecs, no I/O).
tauri-plugin-socketiocrates/tauri-plugin-socketioA Tauri 2 plugin: named clients shared by Rust and the webviews.
tauri-plugin-socketio-apicrates/tauri-plugin-socketio/guest-jsThe plugin's JavaScript API, close to socket.io-client.

Where it comes from

socketio-next started as a fork of rust_socketio 0.6.0 (Bastian Kersting and contributors). The protocol code was kept and corrected; the client was rewritten. It is a different crate: code that uses rust_socketio needs the migration.

Checked against the reference client

The socket.io-parser and engine.io-parser test vectors are ported, the connection and socket cases of socket.io-client and engine.io-client run against Node servers, and differential tests run one scenario with the Node client and with this client against a recording server and compare what went over the wire. What is deliberately not implemented is listed in Comparison.

Next