Guides
Migration from rust_socketio
What changed from rust_socketio 0.6, the fixes and additions, and a mapping table.
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 changes below.
API mapping
| 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) |
Before and after
// rust_socketio 0.6
use futures_util::FutureExt;
use rust_socketio::{Payload, asynchronous::{Client, ClientBuilder}};
let client = ClientBuilder::new("http://localhost:3000/")
.namespace("/chat")
.on("message", |payload: Payload, _: Client| async move {
println!("{payload:?}");
}.boxed())
.connect()
.await?;
client.emit("message", "hi").await?;
// socketio-next
use socketio_next::{Client, ClientBuilder, Event};
let client = ClientBuilder::new("http://localhost:3000/chat")
.on("message", |event: Event, _: Client| async move {
println!("{:?}", event.payload());
})
.connect()
.await?;
client.emit("message", "hi")?;
Fixes
Each with a regression test:
- Long-polling responses are read whole (a message larger than one HTTP chunk broke, upstream #516 / #517).
- Polling and websocket handshakes are 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
0x1ebroke, #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.
- The reconnect attempt limit is final; the reconnect loop never spins after the backoff 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), private CAs, OS trust store.
- Per-attempt query and headers, cookies, HTTP proxies,
reconnect()after close. blockingAPI on top of the async client (one implementation).- Differential tests against socket.io-client 4.8 on the wire.