Client
Debugging
tracing output, redaction, the packet inspector and a troubleshooting table.
Logs
The crate logs through tracing under the socketio_next target:
| Level | What |
|---|---|
info | connected (sid, transport, recovered), reconnecting (attempt, delay), closed (reason) |
warn | disconnected (reason, error), connect / reconnect attempt failed, ping timeout |
debug | engine.io handshake (sid, upgrades, ping interval / timeout, maxPayload), transport chosen / upgraded, every state |
trace | every 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?;
Link info
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
| Symptom | Check |
|---|---|
Engine(InvalidHandshake("... Engine.IO v3 ...")) or IncompatibleServer | The server runs socket.io 2.x. This client needs socket.io 3 or newer. |
ConnectTimeout | Wrong 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 proxy | TransportType::Any (default) falls back to polling; Polling never tries the websocket. |
HttpStatus { status: 400 } after a server restart | The 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 } / CORS | CORS 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 certificate | A 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 proxy | Set HTTPS_PROXY / HTTP_PROXY or call proxy(..); ProxyFailed says what the proxy answered. |
| Token expired, reconnects keep failing | Return the fresh token from auth_with / connect_params_with; after ReconnectFailed call reconnect(). |
TlsNotEnabled | Built with default-features = false; enable rustls or native-tls. |
TlsProviderMissing | Another crate enabled reqwest's rustls-no-provider; enable rustls (TLS). |
| Large messages fail | The server's maxHttpBufferSize (engine.io maxPayload, see link_info().max_payload). |
| Events with no handler | Handlers are matched by exact name; on_any sees everything. |