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_socketiosocketio-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::ErrorError::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(..).awaitemit(..) (not async)
emit_with_ack(ev, data, timeout, callback).awaitemit_with_ack(ev, data, timeout).await -> Result<Payload>
ack payload Text(vec![Array(args)])Text(args)
Payload::String (deprecated), From<String> parsed JSONremoved; 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 themPayload::Mixed keeps them
URL path /socket.io/ = engine pathURL path = namespace (socket.io-client); engine path is .path(..)
rust_engineio cratesocketio_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 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.
  • 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.
  • blocking API on top of the async client (one implementation).
  • Differential tests against socket.io-client 4.8 on the wire.