Struct WebSocketConfig 

pub struct WebSocketConfig {

    pub url: String,
    pub headers: Vec<(String, String)>,
    pub heartbeat_interval_secs: Option<u64>,
    pub heartbeat_payload: Option<String>,
    pub connect_timeout_ms: Option<u64>,
    pub reconnect_delay_initial_ms: Option<u64>,
    pub reconnect_delay_max_ms: Option<u64>,
    pub reconnect_backoff_factor: Option<f64>,
    pub reconnect_jitter_ms: Option<u64>,
    pub reconnect_max_attempts: Option<u32>,
    pub heartbeat_timeout_secs: Option<u64>,
    pub idle_timeout_ms: Option<u64>,
    pub backend: TransportBackend,
    pub proxy_url: Option<String>,
}

Static configuration for WebSocket client connections.

Runtime handlers and rate limiters are passed separately through the client builders.

Connection modes

Handler mode

• Uses WebSocketClient::builder.
• Delivers messages through the supplied callback.
• Runs the reader in an internal task.
• Supports automatic reconnection with exponential backoff.
• Applies reconnect_*, heartbeat_timeout_secs, and idle_timeout_ms settings.
• Suits long-lived connections and callback-based APIs.

Stream mode

• Uses WebSocketClient::stream_builder.
• Returns a MessageReader owned by the caller.
• Does not support automatic reconnection because the client cannot replace the caller’s reader.
• Ignores reconnect_*, heartbeat_timeout_secs, and idle_timeout_ms settings.
• Enters the closed state after disconnection, requiring the caller to create a new connection.

Fields

url: String

The URL to connect to.

headers: Vec<(String, String)>

The default headers.

heartbeat_interval_secs: Option<u64>

The optional heartbeat interval (seconds).

Each timing field carries the coarsest unit that expresses every legitimate value, and quantities compared against each other share a unit: this and Self::heartbeat_timeout_secs are bounded below by whole-second cadences, while reconnect delays and jitter have real sub-second values and stay in milliseconds.

heartbeat_payload: Option<String>

The optional heartbeat payload sent as a text frame.

When None, the heartbeat is an empty Ping control frame instead. A venue that counts only an application-level keepalive needs the text form; the two are not interchangeable.

connect_timeout_ms: Option<u64>

The timeout (milliseconds) for establishing a usable connection. Defaults to 10 seconds.

Bounds three things: the initial connection attempt, each reconnect attempt, and how long a send waits for the client to become active again. A short value therefore makes sends give up early during a reconnect as well as failing a connection attempt faster; keep it above the reconnect backoff.

Only applies to handler mode and must be non-zero when set. Stream mode ignores this field and bounds its connection attempt at 10 seconds.

reconnect_delay_initial_ms: Option<u64>

The initial reconnection delay (milliseconds) for reconnects.

Only applies to handler mode. Stream mode ignores this field.

reconnect_delay_max_ms: Option<u64>

The maximum reconnect delay (milliseconds) for exponential backoff.

Only applies to handler mode. Stream mode ignores this field.

reconnect_backoff_factor: Option<f64>

The exponential backoff factor for reconnection delays.

Only applies to handler mode. Stream mode ignores this field.

reconnect_jitter_ms: Option<u64>

The maximum jitter (milliseconds) added to reconnection delays.

Only applies to handler mode. Stream mode ignores this field.

reconnect_max_attempts: Option<u32>

The maximum number of reconnection attempts before giving up.

Only applies to handler mode. Stream mode ignores this field.

• None: Unlimited reconnection attempts (default, recommended for production).
• Some(n): Transitions to CLOSED once n consecutive reconnect attempts have either failed or established connections active for less than 10 seconds.

heartbeat_timeout_secs: Option<u64>

The dead-peer timeout (seconds) for the read task.

Seconds rather than milliseconds because this is a multiple of Self::heartbeat_interval_secs: it can never sensibly sit below one heartbeat cycle.

When set, the read task stops and triggers reconnection if no inbound frame of any kind arrives within this duration. Ping and Pong both refresh it, so this detects a peer that has gone silent rather than one whose feed is merely quiet. Set it above Self::heartbeat_interval_secs so a healthy connection cannot trip it; three intervals is the usual choice, tolerating two lost replies.

None derives three heartbeat intervals when a heartbeat is configured, and disables detection otherwise. Some(0) is rejected.

Only applies to handler mode; stream mode ignores this field.

idle_timeout_ms: Option<u64>

The idle timeout (milliseconds) for the read task.

When set, the read task stops and triggers reconnection if no Text or Binary frame arrives within this duration. Ping and Pong deliberately do not refresh it, so this detects a feed that has stopped flowing even while the transport is provably alive. Contrast Self::heartbeat_timeout_secs, which any inbound frame refreshes.

None disables this timeout. Some(0) is rejected. Adapters that expose a required integer map 0 to None rather than passing it through.

The raw-socket client has no equivalent: TCP carries no control frames, so there is no transport-level way to tell keepalive traffic from data.

A venue answering the keepalive with a text payload refreshes this timer exactly like real data does, so on those venues the window must sit below Self::heartbeat_interval_secs to mean anything. Prefer Self::heartbeat_timeout_secs unless the venue guarantees periodic inbound data.

Only applies to handler mode; stream mode ignores this field.

backend: TransportBackend

The transport backend to use for the WebSocket connection.

Defaults to TransportBackend::Sockudo when the transport-sockudo Cargo feature is enabled (the default), otherwise TransportBackend::Tungstenite. When the feature is disabled, connect_with_server returns an error if Sockudo is selected. Both backends pass headers into the HTTP upgrade request and both honour Self::proxy_url.

proxy_url: Option<String>

Optional forward proxy URL for the WebSocket connection.

Routes the connection through an HTTP CONNECT tunnel. Accepts http:// and https:// schemes; SOCKS schemes are not yet supported.

Implementations

impl WebSocketConfig

pub fn builder() -> WebSocketConfigBuilder

Create an instance of WebSocketConfig using the builder syntax

impl WebSocketConfig

pub fn validate(&self) -> NetworkConfigResult<()>

Checks whether all WebSocket settings are valid.

Errors

Returns a NetworkConfigError if url is empty, the heartbeat interval or a reconnection timing field is not positive, reconnect_backoff_factor is outside [1.0, 100.0], or reconnect_delay_initial_ms exceeds reconnect_delay_max_ms.

Trait Implementations

impl Clone for WebSocketConfig

fn clone(&self) -> WebSocketConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WebSocketConfig

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for WebSocketConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for WebSocketConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.