Module websocket 

WebSocket transport with runtime backend selection and adapter-facing lifecycle policy.

Architecture

WebSocketClient coordinates a controller, one serialized writer, an optional heartbeat, and either a managed reader or a caller-owned stream. Application text and binary sends can await default or keyed quotas from a shared RateLimiter.

client manages connection lifecycle and concurrent tasks. auth coordinates adapter-driven authentication and optional replay gating, while subscription records adapter-driven subscription intent and acknowledgments. config, types, and proxy define connection policy and transport boundaries.

Operating modes

WebSocketClient supports handler and stream modes. Handler mode owns the reader and replaces it during automatic reconnects. Stream mode returns the reader to the caller and disables automatic reconnects because the client cannot replace caller-owned state.

Liveness

A configured heartbeat sends either a protocol Ping or a text message at a fixed interval; it does not imply a response timeout. Handler mode can separately reconnect when no frame arrives before a heartbeat timeout or when no text or binary application data arrives before the idle timeout. Ping and Pong reset the frame timeout but not the application-data idle timeout.

State reporting and explicit reconnect

An optional crate::SocketStateSink publishes ordered Connected and Disconnected availability edges for initial connection, transport loss, and recovery. It omits retry attempts and deliberate shutdown. WebSocketReconnectHandle lets adapter tasks request transport replacement without owning the client. Handler mode accepts an active request, invalidates registered authentication state, and reports the loss before reconnecting; stream mode returns crate::mode::ReconnectRequestOutcome::Unsupported.

Reconnection and sends

The writer task serializes sends and is the sole owner of the active sink. Ordinary application sends retain FIFO buffering and replay across reconnects. A control frame belongs to the connection it was issued on, so a failed Ping, Pong, or Close is dropped instead of replayed. Ownership-bound sends carry an expected connection epoch and never enter that replay buffer.

The initial connection has epoch 0. The writer advances the epoch when it installs a replacement sink. Epoch-aware handlers receive that epoch on messages from the replacement reader and on its reconnect notification. Epochs identify transport ownership; they do not order application authentication or subscription recovery.

Transport backends

The backend-neutral Message and TransportError types keep lifecycle code independent of the concrete library. tokio-tungstenite is always available. sockudo-ws is enabled and selected by default through the transport-sockudo feature. Both accept custom upgrade headers. Proxy connections use Tungstenite; selecting Sockudo with a proxy falls back to that backend.

Re-exports

pub use auth::AuthTracker;

pub use client::ReconnectHeaders;

pub use client::WebSocketClient;

pub use client::WebSocketClientInner;

pub use client::WebSocketReconnectHandle;

pub use config::InitialConnectRetryPolicy;

pub use config::TransportBackend;

pub use config::WebSocketConfig;

pub use consts::AUTHENTICATION_TIMEOUT_SECS;

pub use consts::TEXT_PING;

pub use consts::TEXT_PONG;

pub use subscription::SubscriptionSnapshot;

pub use subscription::SubscriptionState;

pub use subscription::split_topic;

pub use types::EpochMessageHandler;

pub use types::EpochPingHandler;

pub use types::MessageHandler;

pub use types::MessageReader;

pub use types::PingHandler;

pub use types::channel_epoch_message_handler;

pub use types::channel_message_handler;

Modules

auth

Adapter authentication state independent of the WebSocket transport state.

client

Connection lifecycle and task coordination for WebSocketClient.

config

Static transport and lifecycle configuration for WebSocket connections.

consts

Shared protocol values and WebSocket connection lifecycle timings.

proxy

HTTP CONNECT tunneling for outbound WebSocket connections.

subscription

Adapter-managed subscription intent and acknowledgment tracking.

types

Shared transport halves, message handlers, and writer commands.