socketio-next 0.1.0

Socket.IO v4 / Engine.IO v4 client with socket.io-client 4.8 parity: async (tokio) and blocking, rustls or native-tls
Documentation

socketio-next

crates.io docs.rs CI MSRV license

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, auth, acks in both directions, binary data anywhere in the arguments, the same reconnection backoff, connection state recovery, polling and websocket transports, TLS through rustls or native-tls. Async (tokio) with an optional blocking API.

It started as a fork of rust_socketio and is a rewrite of its client on top of the same protocol work; see Differences from rust_socketio.

[dependencies]
socketio-next = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
use std::time::Duration;
use serde_json::json;
use socketio_next::{Client, ClientBuilder, ConnectionState, Event};

#[tokio::main]
async fn main() -> socketio_next::Result<()> {
    let client = ClientBuilder::new("http://localhost:3000")
        .auth(json!({ "token": "abc" }))
        .on("chat", |event: Event, _client: Client| async move {
            println!("chat: {:?}", event.payload());
        })
        .on_state_change(|state: ConnectionState, _client: Client| async move {
            println!("{state:?}");
        })
        .connect()
        .await?;

    client.emit("chat", "hello")?;
    let reply = client
        .emit_with_ack("add", vec![json!(1), json!(2)], Duration::from_secs(5))
        .await?;
    println!("1 + 2 = {}", reply.arg::<i64>(0)?);

    client.disconnect().await
}

Features

Cargo feature Default What
rustls yes TLS with rustls (ring provider, Mozilla roots from webpki-roots). Pure Rust: no OpenSSL, builds for Android/iOS.
native-tls no TLS with the platform library: OpenSSL on Linux, Security.framework on macOS, SChannel on Windows.
blocking no socketio_next::blocking: the same client with blocking methods and plain-closure handlers.
cookies no One cookie jar per client: cookies set by polling answers go back on later requests and on the websocket handshake (sticky sessions behind a load balancer).
platform-verifier no rustls checks certificates with the operating system's trust store (enterprise and user-installed CAs) through rustls-platform-verifier, instead of the bundled Mozilla roots. Not on Android (it needs JVM setup there), which keeps the bundled roots.

Without rustls and native-tls (default-features = false) the crate builds without any TLS code; https/wss URLs then fail with TlsNotEnabled. If another crate in your build turns on reqwest 0.13's rustls-no-provider (for example tauri-plugin-updater), reqwest needs a rustls provider even for plain http: connecting then fails with TlsProviderMissing; enable rustls here (it hands reqwest a ring-based config, no global provider needed). With both, rustls is the default and a native_tls::TlsConnector passed to tls_config selects native-tls.

The API in short

Connect. ClientBuilder::new(url) → options → .connect().await resolves once the server answered the namespace CONNECT, or fails with the error of that first attempt.

Option socket.io-client Default
namespace("/admin") (or the URL path: http://host/admin) io(url + nsp) /
path("/socket.io/") path /socket.io/
query(k, v) query —
header(k, v) extraHeaders —
auth(json), auth_with(|| async { json }) auth (object / function) —
connect_params_with(|| async { ConnectParams::new().query(k, v).header(k, v) }) query / extraHeaders recomputed per attempt —
proxy("http://user:pass@host:port") — HTTPS_PROXY / HTTP_PROXY / ALL_PROXY, NO_PROXY
transport_type(Any | Polling | Websocket | WebsocketUpgrade) transports polling + upgrade, polling fallback
tls_config(TlsConfig | rustls::ClientConfig | native_tls::TlsConnector) ca, rejectUnauthorized default roots
timeout(d) timeout 20 s for handshake + upgrade + CONNECT
reconnection(bool), reconnection_attempts(n) same on, unlimited
reconnection_delay(d), reconnection_delay_max(d), randomization_factor(f) same 1 s, 5 s, 0.5
reconnect_on_disconnect(bool) — (never) off
buffer_while_disconnected(bool) sendBuffer (always on) off: fail fast
redact_query(bool) — on
inspect_packets(|dir, packet| ..) — —

Emit. client.emit(event, data) never blocks: it queues the packet and returns. Offline it fails with Error::NotConnected (or queues, with buffer_while_disconnected). client.emit_with_ack(event, data, timeout).await returns the ack's arguments, or Error::AckTimeout / Error::Disconnected. data is anything Into<Payload>: a serde_json::Value, a Vec<Value> (several arguments), a string, a number, () (no arguments), Bytes / Vec<u8>, or Payload::serialize(&your_struct)?.

Receive. Handlers get an Event (name, Payload, ack) and the Client. Write them as a plain closure (runs on tokio's blocking pool, may block) or a closure returning a future (runs on the client's event task); no boxing. They run one at a time in arrival order. A handler may emit, await acks, add handlers and call disconnect() without deadlocks.

client.on("question", |event: Event, _: Client| {
    let (text, n): (String, u32) = event.payload().deserialize().unwrap();
    event.ack(json!({ "answer": n + 1 })).unwrap(); // the server's callback
});
client.once("ready", |_: Event, _: Client| println!("ready"));
let id = client.on_any(|event: Event, _: Client| println!("{}", event.name()));
client.off_listener(id);

Binary. A lone buffer arrives as Payload::Binary; buffers anywhere else (several, next to JSON, inside objects) as Payload::Mixed { args, attachments }, where {"_placeholder":true,"num":n} in args stands for attachments[n] — the socket.io wire format. Send the same shapes.

State. ConnectionState: Connecting { attempt }, Connected { sid, recovered }, Disconnected { reason }, Reconnecting { attempt, delay, error }, Closed { reason, error }. Read it with client.state(), wait with client.wait_for(|s| ..), watch it with client.state_watch(), or get every transition in order with on_state_change. DisconnectReason has socket.io-client's reasons (io server disconnect, io client disconnect, ping timeout, transport close, transport error, parse error) plus ConnectRejected, ReconnectFailed and Dropped. client.link_info() gives the transport, sids, ping interval/timeout, last ping, last packet, attempts, pending acks, packets and bytes in and out, and sessions (successful connects). Disconnected { reason, error } carries the error that ended the connection, such as WebsocketClosed { code, reason } from a close frame. The heartbeat also compares the wall clock with the deadline. When the wall clock says the deadline passed but the monotonic clock does not (the machine slept, or the clock was stepped forward by NTP), the client probes the link (a noop POST over polling, a websocket ping) and gives it pingTimeout to show life; only then is it a PingTimeout. A backward step has no effect.

Connect values per attempt. auth_with and connect_params_with run before every connect and reconnect, inside the attempt's timeout (a panic fails the attempt): a refreshed token, a signed timestamp. Their values replace the builder's ones of the same key.

Proxy. Polling requests and the websocket go through the same HTTP proxy: the one given to proxy(..), else the environment's (HTTPS_PROXY for https/wss, HTTP_PROXY for http/ws, ALL_PROXY, minus NO_PROXY). The websocket uses a CONNECT tunnel with basic auth from the proxy URL's user info. Both transports take the same decision (the websocket uses the matcher reqwest uses for polling: NO_PROXY with domains, IPs, CIDR and *). Only http:// proxies are spoken for the websocket: an https:// or SOCKS proxy is a ProxyFailed error, never a silent direct connection. no_proxy() turns proxies off for both. The environment is read once, when the client is built, and that decision holds for its life. If a crate in your build enables reqwest's system-proxy feature (macOS / Windows system settings), only polling sees those settings: call proxy(..) or no_proxy() to make both transports agree. Note that environment proxies apply to ws:// too: a proxy that only allows CONNECT to port 443 then refuses the websocket, and with TransportType::Any the client stays on polling. Redirects are never followed (engine.io does not use them; a 3xx is an HttpStatus error).

One HTTP client per client. The handshake, the polls and the POSTs of one client share one reqwest client (its connection pool and, with cookies, its jar) across reconnects. Long-poll GETs fail after pingInterval + pingTimeout; POSTs have no total bound, so a large upload is not cut by the heartbeat.

Reconnect after close. client.reconnect().await connects a closed client again (ConnectRejected, ReconnectFailed, a server disconnect, disconnect()) with the same handlers; auth_with / connect_params_with run again first.

Shutdown. client.disconnect().await leaves the namespace and closes the connection; it is bounded (1 s for the goodbye packets on a dead link) and no handler starts after it returns. Dropping the last Client closes the connection too.

Errors. One typed, non_exhaustive, cloneable Error: ConnectRejected { message, data } (the server's connect_error), ConnectTimeout, IncompatibleServer, Engine(engineio::Error) (HttpStatus { status, message }, message being engine.io's {"code", "message"} error text and None for any other body, WebsocketClosed { code, reason }, ProxyFailed, Timeout, PingTimeout, UpgradeUnavailable, InvalidHandshake, TlsNotEnabled, ...), NotConnected, Closed, AckTimeout, Disconnected, ReservedEvent. Messages never contain URLs or query values.

Examples for every topic are in examples/: just example basic, auth, reconnect, binary, transports, blocking.

Debugging

The crate logs through tracing under socketio_next:

Level What
info connected (sid, transport, recovered), reconnecting (attempt, delay), closed (reason)
warn disconnected (reason, error), connect / reconnect attempt failed, ping timeout
debug engine.io handshake (sid, upgrades, ping interval/timeout, maxPayload), transport chosen / upgraded, every state
trace every packet in and out (type, namespace, ack id, size)

Every event carries a socketio{nsp, url} span. Query values are shown as *** (only EIO, transport, sid, t stay visible); redact_query(false) turns that off. For the full packets use inspect_packets.

RUST_LOG=socketio_next=debug cargo run

Only socketio_next targets are redacted. tungstenite logs the full websocket handshake request (URL with query, headers) with the log crate at trace level; if you bridge log into tracing, keep tungstenite=info or higher when the query carries secrets.

Troubleshooting

Symptom Check
Engine(InvalidHandshake("... Engine.IO v3 ...")) or IncompatibleServer The server runs socket.io 2.x (Engine.IO v3). This client needs socket.io 3 or newer.
ConnectTimeout Wrong host/port/path, a proxy that swallows the request, or a server that is not socket.io. Try transport_type(TransportType::Polling) and RUST_LOG=socketio_next=debug.
Websocket blocked by a proxy TransportType::Any (default) falls back to polling; Polling never tries websocket.
HttpStatus { status: 400 } after a server restart The old session id is gone; the client reconnects with a new one.
HttpStatus { status: 403 } / CORS CORS does not apply to non-browser clients; a 403 comes from a proxy or the server's allowRequest.
ConnectRejected { message, data } The namespace middleware refused the auth (next(new Error(message))), or the namespace does not exist (Invalid namespace). The client does not retry.
TLS: invalid peer certificate A private CA: tls_config(TlsConfig::with_root_certificates_pem(&pem)?); or the platform-verifier feature (rustls with the OS trust store), or native-tls.
HttpStatus { status: 400, message: "Session ID unknown" } The server forgot the session (restart, another node behind a load balancer without sticky sessions: enable cookies if the balancer pins by cookie).
WebsocketClosed { code, reason } The server or a proxy closed the websocket on purpose; the code says why (1001 going away, 1008 policy, 4xxx the application's).
Corporate proxy Set HTTPS_PROXY / HTTP_PROXY or call proxy(..); ProxyFailed says what the proxy answered.
Token expired, reconnects keep failing Return the fresh token from auth_with / connect_params_with; after ReconnectFailed call reconnect().
TlsNotEnabled Built with default-features = false; enable rustls or native-tls.
TlsProviderMissing Another crate enabled reqwest's rustls-no-provider; enable rustls (see Cargo features).
Large messages fail The server's maxHttpBufferSize (engine.io maxPayload, see link_info().max_payload).
Events with no handler Handlers are matched by exact name; on_any sees everything.

Differences from rust_socketio

socketio-next started as s00d/rust-socketio, 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 (socketio-next); code that uses rust_socketio needs the migration below.

Fixes (each with a regression test):

  • Long-polling responses read whole (a message larger than one HTTP chunk broke, upstream #516/#517).
  • Polling and websocket handshakes bounded by a timeout; a blackholed websocket falls back to polling.
  • A non-200 polling answer is an error, not a payload.
  • A websocket frame is one packet (binary data containing 0x1e broke, #490).
  • Unique ack ids (collisions, a registry panic and a deadlock).
  • disconnect() stops the reconnect loop, a hung reconnect attempt and the poll task (#374, #508).
  • The engine closes after a server namespace disconnect, after CONNECT_ERROR and after a decode error.
  • max_reconnect_attempts is final; the reconnect loop never spins after the backoff crate gave up.
  • Emits before the CONNECT answer are buffered (#502).
  • BINARY_EVENT for binary emits with an ack (#422); binary event names with extra arguments (#426).
  • socket.io-parser validation rules: reserved event names, payload shapes, attachment counts.
  • No unsolicited PONG after the handshake.

New:

  • socket.io-parser binary encoding everywhere: several attachments, nested placeholders (Payload::Mixed).
  • Acks from the server answered (Event::ack, ACK and BINARY_ACK); awaitable acks with timeout.
  • The socket.io-client backoff (jitter 0.5, delay before every attempt), randomization_factor.
  • Connection state recovery (pid/offset, recovered).
  • Typed ConnectionState, DisconnectReason, LinkInfo; tracing with redaction; packet inspector.
  • Runtime on/once/off/on_any/listener_count; handlers without boxing; panics contained.
  • TLS backend as a feature (rustls default, native-tls, none).
  • blocking API on top of the async client (one implementation).
  • Differential tests against socket.io-client 4.8 on the wire.

Breaking changes and migration from rust_socketio 0.6:

rust_socketio socketio-next
rust_socketio::asynchronous::{ClientBuilder, Client} socketio_next::{ClientBuilder, Client}
rust_socketio::{ClientBuilder, RawClient} (sync) socketio_next::blocking::{ClientBuilder, Client} (feature blocking)
.on(Event::Custom("x"), |payload, client| async {}.boxed()) .on("x", |event: Event, client: Client| async move {}) — event.payload()
.on(Event::Connect / Close / Error, ..) .on_state_change(|state, client| ..) or client.state(); errors are typed
"Received an ConnectError frame: ..." in Event::Error Error::ConnectRejected { message, data }, DisconnectReason::ConnectRejected
.on_reconnect(|| async { ReconnectSettings }.boxed()) auth_with(..) for fresh auth; ConnectionState::Reconnecting to observe
.reconnect(b), .reconnect_delay(min_ms, max_ms), .max_reconnect_attempts(n) .reconnection(b), .reconnection_delay(Duration) + .reconnection_delay_max(Duration), .reconnection_attempts(n)
.opening_header(k, v) .header(k, v)
.tls_config(native_tls::TlsConnector) the same with feature native-tls, or TlsConfig / rustls::ClientConfig
emit(..).await emit(..) (not async)
emit_with_ack(ev, data, timeout, callback).await emit_with_ack(ev, data, timeout).await -> Result<Payload>
ack payload Text(vec![Array(args)]) Text(args)
Payload::String (deprecated), From<String> parsed JSON removed; strings are strings, use Value for JSON
server emit("NAME") arrived as message with data "NAME" arrives as event NAME without arguments (socket.io-client)
a binary event with other arguments lost them Payload::Mixed keeps them
URL path /socket.io/ = engine path URL path = namespace (socket.io-client); engine path is .path(..)
rust_engineio crate socketio_next::engineio module (async only)

Parity with socket.io-client 4.8

Ported and tested: the socket.io-parser and engine.io-parser vectors, connection and socket cases of socket.io-client and engine.io-client against Node servers, plus differential runs where the Node client and this client play the same scenario against one recording server (crates/socketio-next/tests/conformance.rs).

Not implemented, on purpose: one Manager multiplexing several namespaces over one connection (each Client has its own; connect several), volatile (offline emits already fail fast), retries/ackTimeout queues, onAnyOutgoing, forceBase64, WebTransport, WASM, Engine.IO v3 (socket.io 2.x servers), permessage-deflate, the msgpack parser (a feature later if a server needs it), derive macros for events, concurrent handler dispatch (handlers run in order), injecting your own reqwest or tungstenite client (it would tie the public API to their versions), browser-only options. connect() returns the first attempt's error instead of retrying silently.

Other Rust clients

rust_socketio 0.6 is where this crate started (see the migration table above). tf-rust-socketio (a fork of it) and sioc/eioc are other clients; per-attempt query and headers, cookies, proxy support, the OS verifier, close codes, HTTP error bodies and reconnect() after close were added after comparing with them and with the upstream branch. What this crate has on top: socket.io-client 4.8 behaviour checked against the reference client on the wire, typed states and errors, binary anywhere in the arguments, connection state recovery, and a Tauri plugin.

Tauri

tauri-plugin-socketio (npm tauri-plugin-socketio-api) shares named clients between Rust and the webviews of a Tauri 2 app, with read-only clients for sockets that Rust code owns.

Minimum Rust version

1.85 (edition 2024), checked with a lockfile resolved for it; see MSRV.md.

Development

just lists the tasks. just servers-setup && just servers starts the Node test servers (ports 4200-4206 and 4210-4211, no Docker), just ci runs what CI runs: fmt, cargo-shear, clippy on every feature set, all tests per feature set, docs, cargo-deny, package, and the Tauri plugin (just plugin: Rust tests and guest-js; pnpm needed).

License

MIT, see LICENSE. Based on rust_socketio by Bastian Kersting and the rust-socketio contributors.