Client

Configuration

Every ClientBuilder option, with its socket.io-client counterpart and default.

ClientBuilder::new(url) takes the server URL, then options, then .connect().await.

use std::time::Duration;
use serde_json::json;
use socketio_next::{ClientBuilder, TransportType};

let client = ClientBuilder::new("https://chat.example.com/admin") // namespace /admin
    .path("/socket.io/")
    .query("v", "2")
    .header("x-app", "demo")
    .auth(json!({ "token": "abc" }))
    .transport_type(TransportType::Any)
    .timeout(Duration::from_secs(10))
    .reconnection_attempts(10)
    .connect()
    .await?;

Options

Optionsocket.io-clientDefault
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"), no_proxy()—HTTPS_PROXY / HTTP_PROXY / ALL_PROXY, NO_PROXY
transport_type(Any | Polling | Websocket | WebsocketUpgrade)transportspolling + upgrade, polling fallback
tls_config(TlsConfig | rustls::ClientConfig | native_tls::TlsConnector)ca, rejectUnauthorizeddefault roots
timeout(d)timeout20 s for handshake + upgrade + CONNECT
reconnection(bool), reconnection_attempts(n)sameon, unlimited
reconnection_delay(d), reconnection_delay_max(d), randomization_factor(f)same1 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| ..)——

Handlers can be added on the builder (on, once, on_any, on_state_change) so that they see the first events after the connect, or later on the Client. See Events and acks.

Namespace and path

The URL's path is the namespace, as in socket.io-client: http://host/admin joins /admin. namespace(..) sets it explicitly. The engine.io endpoint is path(..), default /socket.io/.

builder.engine_url() returns the engine.io URL connect() will use (before connect_params_with), normalized the way the connection normalizes it (/v1/../x/ is /x/). Use it to check where a connection goes, for example against an allow-list.

Auth and values per attempt

auth(json) sends a JSON object with the namespace CONNECT (the server reads it as socket.handshake.auth). A value that is not an object fails connect() with InvalidAuth.

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.

use socketio_next::{ClientBuilder, ConnectParams};

let client = ClientBuilder::new(url)
    .auth_with(|| async { json!({ "token": fetch_token().await }) })
    .connect_params_with(|| async {
        ConnectParams::new()
            .header("authorization", format!("Bearer {}", fetch_token().await))
            .query("ts", now().to_string())
    })
    .connect()
    .await?;

Reconnection

After a connection existed, a lost connection is retried with socket.io-client's backoff: reconnection_delay doubled per attempt up to reconnection_delay_max, with randomization_factor jitter, a delay before every attempt, at most reconnection_attempts attempts. When the attempts are used up the client is Closed { reason: ReconnectFailed }.

A server-side disconnect (socket.disconnect() on the server) is final in socket.io-client. reconnect_on_disconnect(true) reconnects after it too.

A closed client can be connected again with client.reconnect().await, see Connection state.

Offline emits

By default emit while disconnected fails with Error::NotConnected: nothing is queued behind your back. buffer_while_disconnected(true) queues emits and sends them after the next connect, like socket.io-client's send buffer; acks of queued emits keep their timeout. link_info().buffered_emits shows the queue length.

Redaction

Query values are shown as *** in logs and Debug output; only EIO, transport, sid and t stay visible. redact_query(false) turns that off. Error messages never contain the URL or query values either way.