Module client 

Connection lifecycle and task coordination for WebSocketClient.

Execution model

Handler mode runs a controller, reader, and writer task, plus an optional heartbeat task. The reader dispatches frames, the writer serializes all sink access, and the controller drives reconnect and shutdown from the shared ConnectionMode. Stream mode omits the managed reader task and automatic reconnect.

A read failure ends the reader and wakes the controller; a write failure requests reconnect and also wakes it. The controller establishes a replacement transport with exponential backoff, hands its sink to the writer, replaces the reader, then publishes the reconnect notification. Terminal disconnect and close states stop all tasks instead of starting another reconnect.

Reconnect ordering

An accepted reconnect request first transitions to Reconnect and invalidates registered authentication. The controller may establish the replacement while the synchronous loss callback runs, but cannot restore Active until loss publication completes. A reconnect through WebSocketReconnectHandle releases its controller request fence before invoking the callback, so dropping the client can terminate controller work even if the callback blocks. Terminal states always take precedence.

Send semantics

Ordinary sends return after entering the writer channel. Failed ordinary writes and ordinary messages encountered during reconnect enter a FIFO buffer for replay on an active replacement connection. While that replay is pending, ordinary sends also enter the buffer and queue behind it instead of reaching the replacement sink early. Registered authentication state can hold or discard that replay before it reaches the sink. Control frames are never buffered, so a pong sent while replay waits still writes to the replacement sink directly. WebSocketConfig::writer_capacity bounds ordinary messages across the channel, in-flight writes, and replay. Full capacity rejects a send with SendError::BufferFull before enqueueing. Ownership-bound sends and control traffic use a separate bounded allowance so authentication can unblock replay.

Ownership-bound sends wait for the writer result, require the expected connection epoch, and never enter the reconnect buffer. The writer advances the epoch only when it installs a replacement sink, so inbound attribution and bound sends share one transport ownership boundary.

Structs

ReconnectHeaders

Shared headers used by future automatic WebSocket reconnects.

WebSocketClient

A WebSocket client with rate limiting, heartbeats, and automatic reconnection in handler mode.

WebSocketClientBuilder

Use builder syntax to set the inputs and finish with connect().

WebSocketClientEpochBuilder

Use builder syntax to set the inputs and finish with connect().

WebSocketClientInner

Owns the transport tasks and reconnect state used by WebSocketClient.

WebSocketClientStreamBuilder

Use builder syntax to set the inputs and finish with connect().

WebSocketReconnectHandle

Cloneable controller handle for requesting one transport reconnect.