Client

Debugging

tracing output, redaction, the packet inspector and a troubleshooting table.

Logs

The crate logs through tracing under the socketio_next target:

LevelWhat
infoconnected (sid, transport, recovered), reconnecting (attempt, delay), closed (reason)
warndisconnected (reason, error), connect / reconnect attempt failed, ping timeout
debugengine.io handshake (sid, upgrades, ping interval / timeout, maxPayload), transport chosen / upgraded, every state
traceevery packet in and out (type, namespace, ack id, size)
RUST_LOG=socketio_next=debug cargo run
tracing_subscriber::fmt()
    .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
    .init();

Every event carries a socketio{nsp, url} span. Query values are shown as *** (only EIO, transport, sid, t stay visible); redact_query(false) turns that off.

Only socketio_next targets are redacted. tungstenite logs the full websocket handshake request (URL with query, headers) with the log crate at trace level; if you bridge log into tracing, keep tungstenite=info or higher when the query carries secrets.

Packet inspector

inspect_packets sees every socket.io packet in and out, after decoding / before encoding. It runs on the connection task, so keep it quick; a panicking inspector is logged, not fatal.

use socketio_next::{ClientBuilder, Direction};

let client = ClientBuilder::new(url)
    .inspect_packets(|direction: Direction, packet| match direction {
        Direction::Incoming => println!("<- {packet:?}"),
        Direction::Outgoing => println!("-> {packet:?}"),
    })
    .connect()
    .await?;

client.link_info() shows the transport, the sids, ping interval / timeout, the last ping and packet, attempts, pending acks, traffic counters and sessions; see Connection state.

Troubleshooting

SymptomCheck
Engine(InvalidHandshake("... Engine.IO v3 ...")) or IncompatibleServerThe server runs socket.io 2.x. This client needs socket.io 3 or newer.
ConnectTimeoutWrong host / port / path, a proxy that swallows the request, or a server that is not socket.io. Try transport_type(TransportType::Polling) and RUST_LOG=socketio_next=debug.
Websocket blocked by a proxyTransportType::Any (default) falls back to polling; Polling never tries the websocket.
HttpStatus { status: 400 } after a server restartThe old session id is gone; the client reconnects with a new one.
HttpStatus { status: 400, message: "Session ID unknown" }The server forgot the session (restart, or another node behind a load balancer without sticky sessions: enable cookies if the balancer pins by cookie).
HttpStatus { status: 403 } / CORSCORS does not apply to non-browser clients; a 403 comes from a proxy or the server's allowRequest.
ConnectRejected { message, data }The namespace middleware refused the auth (next(new Error(message))), or the namespace does not exist (Invalid namespace). The client does not retry.
TLS: invalid peer certificateA private CA: tls_config(TlsConfig::with_root_certificates_pem(&pem)?); or the platform-verifier feature, or native-tls.
WebsocketClosed { code, reason }The server or a proxy closed the websocket on purpose; the code says why (1001 going away, 1008 policy, 4xxx the application's).
Corporate proxySet HTTPS_PROXY / HTTP_PROXY or call proxy(..); ProxyFailed says what the proxy answered.
Token expired, reconnects keep failingReturn the fresh token from auth_with / connect_params_with; after ReconnectFailed call reconnect().
TlsNotEnabledBuilt with default-features = false; enable rustls or native-tls.
TlsProviderMissingAnother crate enabled reqwest's rustls-no-provider; enable rustls (TLS).
Large messages failThe server's maxHttpBufferSize (engine.io maxPayload, see link_info().max_payload).
Events with no handlerHandlers are matched by exact name; on_any sees everything.