Configuration
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
| 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"), no_proxy() | — | 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| ..) | — | — |
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.