Connection state
States
pub enum ConnectionState {
Connecting { attempt },
Connected { sid, recovered },
Disconnected { reason, error },
Reconnecting { attempt, delay, error },
Closed { reason, error },
}
| Read it | How |
|---|---|
| now | client.state(), client.connected(), client.id(), client.recovered() |
| wait | client.wait_for(|s| s.is_connected()).await |
| watch | client.state_watch() (a tokio::sync::watch::Receiver) |
| every transition, in order with the events | on_state_change(|state, client| ..) |
Connected { recovered: true } means the server restored the session (connection state recovery: the missed packets were replayed, the socket id kept).
Disconnect reasons
DisconnectReason has socket.io-client's reasons plus three of its own; reason.as_str() gives the string.
| Reason | String | When |
|---|---|---|
IoServerDisconnect | io server disconnect | the server called socket.disconnect() |
IoClientDisconnect | io client disconnect | client.disconnect() |
PingTimeout | ping timeout | no ping within pingInterval + pingTimeout |
TransportClose | transport close | the connection was closed |
TransportError | transport error | the connection failed |
ParseError | parse error | the server sent an undecodable packet |
ConnectRejected | connect rejected | the namespace refused the CONNECT (no retry) |
ReconnectFailed | reconnect failed | reconnection attempts used up |
Dropped | client dropped | the last Client was dropped |
Disconnected { reason, error } and Closed { reason, error } carry the error that ended the connection, such as WebsocketClosed { code, reason } from a close frame.
Link info
client.link_info() returns a LinkInfo snapshot:
| Field | What |
|---|---|
sid, engine_sid | socket id and engine.io session id while connected |
transport | TransportKind in use |
ping_interval, ping_timeout, max_payload | from the last handshake |
connected_at, last_packet_at, last_ping_at, last_attempt_at | Instants |
reconnect_attempts | since the last successful connect |
pending_acks, buffered_emits | waiting acks, queued offline emits |
packets_in, packets_out, bytes_in, bytes_out | traffic counters |
sessions | successful connects (the first one and every reconnect) |
Heartbeat and sleep
The client fails the connection with PingTimeout when no ping arrives within pingInterval + pingTimeout. It also compares the wall clock with the deadline: when the wall clock says the deadline passed but the monotonic clock does not (the machine slept, or NTP stepped the clock forward), the client probes the link (a noop POST over polling, a websocket ping) and gives it pingTimeout to show life; only then is it a PingTimeout. A backward clock step has no effect.
Reconnect after close
client.reconnect().await connects a closed client again (after ConnectRejected, ReconnectFailed, a server disconnect or disconnect()) with the same handlers; auth_with / connect_params_with run again first.
if let ConnectionState::Closed { reason: DisconnectReason::ReconnectFailed, .. } = client.state() {
client.reconnect().await?;
}
Shutdown
client.disconnect().await leaves the namespace and closes the connection. It is bounded (on a dead link: 1 s to send what is queued and the goodbye, 1 s for the engine.io close) and no handler starts after it returns. Dropping the last Client closes the connection too (Dropped).