Struct WebSocketClient 

pub struct WebSocketClient { /* private fields */ }

WebSocket client with automatic reconnection.

Handles connection state, callbacks, and rate limiting. See module docs for architecture details.

Implementations

impl WebSocketClient

pub async fn connect_stream( config: WebSocketConfig, keyed_quotas: Vec<(String, Quota)>, default_quota: Option<Quota>, post_reconnect: Option<Arc<dyn Fn() + Send + Sync>>, ) -> Result<(MessageReader, Self), TransportError>

Creates a websocket client in stream mode that returns a MessageReader.

Returns a stream that the caller owns and reads from directly. Automatic reconnection is disabled because the reader cannot be replaced internally. On disconnection, the client transitions to CLOSED state and the caller must manually reconnect by calling connect_stream again.

Use stream mode when you need custom reconnection logic, direct control over message reading, or fine-grained backpressure handling.

See WebSocketConfig documentation for comparison with handler mode.

Errors

Returns an error if the connection cannot be established.

pub async fn connect( config: WebSocketConfig, message_handler: Option<MessageHandler>, ping_handler: Option<PingHandler>, post_reconnection: Option<Arc<dyn Fn() + Send + Sync>>, keyed_quotas: Vec<(String, Quota)>, default_quota: Option<Quota>, ) -> Result<Self, TransportError>

Creates a websocket client in handler mode with automatic reconnection.

The handler is called for each incoming message on an internal task. Automatic reconnection is enabled with exponential backoff. On disconnection, the client automatically attempts to reconnect and replaces the internal reader (the handler continues working seamlessly).

Use handler mode for simplified connection management, automatic reconnection, Python bindings, or callback-based message handling.

See WebSocketConfig documentation for comparison with stream mode.

Errors

Returns an error if:

• The connection cannot be established.
• message_handler is None (use connect_stream instead).

pub async fn connect_with_rate_limiter( config: WebSocketConfig, message_handler: Option<MessageHandler>, ping_handler: Option<PingHandler>, post_reconnection: Option<Arc<dyn Fn() + Send + Sync>>, rate_limiter: Arc<RateLimiter<Ustr, MonotonicClock>>, ) -> Result<Self, TransportError>

Creates a websocket client in handler mode sharing an externally-owned rate limiter.

Use this constructor to share a single RateLimiter across multiple WebSocketClient instances (for example, the WebSocket clients owned by an exchange adapter’s data and execution clients). All quota state lives inside the limiter, so passing the same Arc produces a single shared bucket — the only way to honour a venue’s per-IP / per-account WS message cap when more than one connection is opened in-process.

Behavior otherwise matches Self::connect.

Errors

Returns an error if:

• The connection cannot be established.
• message_handler is None (use connect_stream instead).

pub fn connection_mode(&self) -> ConnectionMode

Returns the current connection mode.

pub fn connection_mode_atomic(&self) -> Arc<AtomicU8>

Returns a clone of the connection mode atomic for external state tracking.

This allows adapter clients to track connection state across reconnections without message-passing delays.

pub fn is_active(&self) -> bool

Check if the client connection is active.

Returns true if the client is connected and has not been signalled to disconnect. The client will automatically retry connection based on its configuration.

pub fn is_disconnected(&self) -> bool

Check if the client is disconnected.

pub fn is_reconnecting(&self) -> bool

Check if the client is reconnecting.

Returns true if the client lost connection and is attempting to reestablish it. The client will automatically retry connection based on its configuration.

pub fn set_auth_tracker( &self, tracker: AuthTracker, reconnect_buffer_waits_for_auth: bool, )

Registers an AuthTracker with the client.

When the controller detects a dead connection and transitions to Reconnect, it calls invalidate() on the tracker so that any pending authenticated sends see the state change immediately. Terminal transitions fail the tracker so pending auth waits can terminate. Set reconnect_buffer_waits_for_auth for clients that must not replay buffered messages until the next session authenticates.

Call this once after construction, before any authenticated sends.

pub fn is_disconnecting(&self) -> bool

Check if the client is disconnecting.

Returns true if the client is in disconnect mode.

pub fn is_closed(&self) -> bool

Check if the client is closed.

Returns true if the client has been explicitly disconnected or reached maximum reconnection attempts. In this state, the client cannot be reused and a new client must be created for further connections.

pub fn notify_closed(&self)

Signals that the caller’s reader has observed EOF or a fatal error.

In stream mode the controller has no visibility into the caller-owned reader. Call this method when reader.next().await returns None or an unrecoverable error so the controller transitions to Closed and dependent tasks shut down.

For peer-initiated close frames (Message::Close), use disconnect instead so the writer can send the close reply before shutting down.

If an AuthTracker is registered, this fails pending auth waits.

This is a no-op if the connection is already closed or disconnecting.

pub async fn disconnect(&self)

Set disconnect mode to true.

Controller task will periodically check the disconnect mode and shutdown the client if it is alive

If an AuthTracker is registered, this fails pending auth waits.

pub async fn send_text( &self, data: String, keys: Option<&[Ustr]>, ) -> Result<(), SendError>

Sends the given text data to the server.

Returns Ok(()) when the message is enqueued to the writer channel. This does NOT guarantee delivery: if a disconnect occurs concurrently, the writer task may drop the message. During reconnection, messages are buffered and replayed on the new connection.

Errors

Returns a websocket error if unable to send.

pub async fn send_pong(&self, data: Vec<u8>) -> Result<(), SendError>

Sends a pong frame back to the server.

Errors

Returns a websocket error if unable to send.

pub async fn send_bytes( &self, data: Vec<u8>, keys: Option<&[Ustr]>, ) -> Result<(), SendError>

Sends the given bytes data to the server.

Returns Ok(()) when the message is enqueued to the writer channel. This does NOT guarantee delivery: if a disconnect occurs concurrently, the writer task may drop the message. During reconnection, messages are buffered and replayed on the new connection.

Errors

Returns a websocket error if unable to send.

pub async fn send_close_message(&self) -> Result<(), SendError>

Sends a close message to the server.

Errors

Returns a websocket error if unable to send.

Trait Implementations

impl Debug for WebSocketClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for WebSocketClient

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.