Changelog
All notable changes to socketio-next.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Unreleased
0.2.0 - 2026-11-21
Breaking changes
engineio::Transport::set_base_url(and the transports' own) is removed: on polling it moved the POSTs but not the long-poll GETs, on websocket it changed nothing. The transport URL is fixed at construction.
Added
WeakClient(Client::downgrade): a handle that does not keep the connection open, for handlers and other things the client owns (a handler holding aClientkept it alive forever).- The blocking API has the async client's
proxy,no_proxy,connect_params_with,engine_url,on_any,on_state_change,off_anyandrecovered.
Changed
- One connection task owns the client's whole life across
reconnect(): one command channel and one event task for the client's lifetime.reconnect()anddisconnect()take effect in the order they are called;connected(),id()and the emit checks follow the published state, and a loss is published before the (bounded) engine teardown. disconnect()from a handler: theClosedstate still reacheson_state_change(it was dropped), events received after it start no handler. "Inside a handler" is per client: a handler of client A that disconnects client B waits for B's handlers as from outside.- engine.io callbacks (
on_open,on_data,on_packet,on_error,on_close) run one at a time in the order of the events (they were each a task of their own). - A polling handshake body with packets after the open packet (python-engineio sends what the connect handler emitted) is accepted; those packets come first on the stream.
- Documentation site at https://s00d.github.io/rust-socketio/; the README is short and links to it.
- Polling POSTs are bounded like the long-poll GET (pingInterval + pingTimeout): a POST stuck
on a half-open connection no longer holds
emitanddisconnectuntil the kernel gives up.PollingTransport::newbounds both by 60 s. engineio::ClientBuilder::buildstays on polling when the websocket upgrade fails (a proxy that dropsUpgrade:), like engine.io-client.- The engine.io query parameters (
EIO,transport,sid,t,b64) are the client's own: a caller's values for them (query(..),connect_params_with, the URL) are dropped. - The
wssconnection offers only HTTP/1.1 in ALPN, also with aTlsConfigshared with an HTTP/2 client.
Fixed
- A panic in the synchronous part of an async handler (the closure body before its future) stopped the event task for good; it is contained like a panic inside the future.
- A panic in the synchronous part of
auth_with/connect_params_withended the connection task instead of failing the attempt. In the blocking API a panickingauth_withbecame a misleadingInvalidAuth("must be a JSON object"); it is "the auth_with function panicked". AckSender::sendwith a payload that cannot be encoded counted the ack as sent; a valid retry sent nothing.reconnect()left the old event task running when a handler was stuck past the drain bound: two event tasks broke the in-order guarantee. It is stopped likedisconnect()does.redact_query(false)showeduser:password@of the URL in the logs; it is masked always.- engine.io: a transport that failed or ended (a websocket closed without a close packet,
Session ID unknownafter a server restart) left the session marked open;on_closefires once for any way the session ends. - engine.io: a ping answered after
disconnect()no longer reports an error.
Testing
socketio-next-testing::fake: in-process Engine.IO v4 / Socket.IO v4 servers with the fixtures ofci/*.js, written from the protocol. Most tests need no Node any more; Node stays for the differential tests, connection state recovery, cookies and TLS.- CI on Linux, macOS and Windows for every push and pull request; Rust 1.100. Releases run from
the CI workflow with crates.io trusted publishing (
PUBLISHING.md).
0.1.0 - 2026-11-08
First release of socketio-next, the successor of the s00d/rust-socketio fork of
rust_socketio 0.6.0 (its history is in that
repository). See "Differences from rust_socketio" in the README for the migration table.
Added
- One crate: the socket.io client,
engineio(transport layer) andprotocol(codecs, no I/O). - Socket.IO client with socket.io-client 4.8 behaviour: connection task + ordered event task,
ConnectionState/DisconnectReason/LinkInfo, awaitable acks with timeout, server acks answered (Event::ack), runtimeon/once/on_any/off, sync or async handlers without boxing,buffer_while_disconnected(opt-in send buffer), connection state recovery,auth_with, query and headers, packet inspector, typed cloneable errors. - socket.io-parser binary encoding: several attachments, nested placeholders (
Payload::Mixed); maxAttachments 10; numeric and argument-less event names. - socket.io-client reconnection backoff (backo2, randomizationFactor 0.5, delay before every
attempt);
reconnection_attemptsis final (ReconnectFailed). - TLS as a feature:
rustls(default, ring + webpki roots),native-tls, or none;TlsConfigwithwith_root_certificates_pem. blockingfeature: the async client on a private runtime.TlsProviderMissinginstead of a reqwest panic when another crate enabled reqwest'srustls-no-provider(found integrating with a Tauri app usingtauri-plugin-updater).- tracing with spans per client and redacted query values; errors never carry URLs.
- Differential tests against socket.io-client 4.8 (
ci/conformance), Node test servers without Docker (ci/servers.sh),justfile, CI on Linux, macOS and Windows. tauri-plugin-socketio(crate) andtauri-plugin-socketio-api(npm): a Tauri 2 plugin with named clients shared by Rust and the webviews; its own changelog is crates/tauri-plugin-socketio/CHANGELOG.md.ClientBuilder::connect_params_with: query parameters and headers computed before every connect attempt (inside its timeout, panics contained), likeauth_with.Client::reconnect()(and blocking): connect a closed client again with the same handlers.ClientBuilder::proxy(..)andHTTPS_PROXY/HTTP_PROXY/ALL_PROXY/NO_PROXYfor the websocket too (aCONNECTtunnel with basic auth);engineio::Error::ProxyFailed.cookiesfeature: one cookie jar per client for polling and the websocket handshake.platform-verifierfeature: rustls with the OS trust store (not on Android).engineio::Error::WebsocketClosed { code, reason }from close frames (also during the upgrade probe), aTransportClose;ConnectionState::Disconnectedcarries the error.HttpStatushas engine.io's error message (message) when the body is its{"code", "message"}JSON (at most 4 KiB read, 200 characters kept, URLs and queries removed); any other body (HTML, text, other JSON) givesNone, since it may echo the request, a header or a token.LinkInfo:packets_in/packets_out,bytes_in/bytes_out,sessions.
Changed
- Breaking (pre-release):
ConnectionState::Disconnectedhas anerrorfield andengineio::Error::HttpStatusamessagefield; the struct-like variants ofConnectionState,Error::ConnectRejected,engineio::Error::HttpStatusandWebsocketClosedare#[non_exhaustive](match them with..), so fields can be added later without a break. Code ported from rust_socketio matches states with..anyway. - Environment proxies (
HTTPS_PROXY,HTTP_PROXY,ALL_PROXY,NO_PROXY) now also apply to the websocket,ws://included, with the same matcher reqwest uses for polling; a proxy that refusesCONNECTto non-443 ports refuses the websocket (withTransportType::Anythe client stays on polling).ClientBuilder::no_proxy()turns proxies off for both transports.https://and SOCKS proxies are aProxyFailederror for the websocket. - Redirects are not followed (a 3xx is an
HttpStatuserror without the target). - The wall-clock check of the heartbeat probes the link and waits pingTimeout instead of closing at once, so an NTP step on a live link does not disconnect.
- A refused websocket handshake (3xx, 4xx) is
HttpStatus { status }; the response (with aLocationthat may carry the query) is not kept in the error. - Environment proxies are read once, when the client is built; both transports use that decision for the client's life.
ClientBuilder::engine_url(): the engine.io URL a connect will use (path normalized).- One reqwest client per socket.io client, shared by every transport and reconnect (it was two per connect attempt); only long-poll GETs are bounded by pingInterval + pingTimeout, so slow POST uploads are no longer cut.
Fixed
- The heartbeat also checks the wall clock: after a system sleep a dead link is detected on wake-up instead of after the remaining monotonic time.
- The websocket reader could miss a wakeup when another task held the receiver (a lock future polled once and dropped); the receiver is now polled under a short std lock.
- The wall-clock liveness probe over polling goes through the normal write lock (a POST next to another one made engine.io close the session with "data request overlap").
reconnect()racingdisconnect(): a disconnect always wins (no revived client, no hang).- The caller's
Cookieheader and the cookie jar are merged (user; jar) on polling and on the websocket handshake (cookiesfeature). - IPv6 servers and proxies through the
CONNECTtunnel ([::1]). connect().awaitcould return before the client was connected:connected()false,state()Connecting,id()None andemit()failing withNotConnectedon a multi-thread runtime or with the blocking client. The connected state is now set beforeconnect()returns and after every reconnect.- Carried over from the fork, each with a regression test:
- Whole long-polling bodies; bounded handshakes; non-200 polling answers; websocket frames as
single packets; unique ack ids;
disconnect()stops reconnects and hung attempts; the engine closes after namespace disconnect, CONNECT_ERROR and decode errors; emits before CONNECT are buffered; BINARY_EVENT for binary emits with ack; socket.io-parser validation rules; no unsolicited PONG.
- Whole long-polling bodies; bounded handshakes; non-200 polling answers; websocket frames as
single packets; unique ack ids;
Removed
- The sync engine.io client and transports;
Payload::String; thebackoff,adler32,async-stream,async-traitand directnative-tlsdependencies.