Struct ConnectionOptions 

pub struct ConnectionOptions {
    pub http_version: HttpVersion,
    pub auto_reconnect: bool,
    pub reconnect_delay_ms: u64,
    pub max_reconnect_delay_ms: u64,
    pub max_reconnect_attempts: Option<u32>,
    pub timestamp_format: TimestampFormat,
    pub ping_interval_ms: u64,
    pub ws_local_bind_addresses: Vec<String>,
    pub disable_compression: bool,
    pub ws_lazy_connect: bool,
    pub protocol: ProtocolOptions,
}

Connection-level options for the WebSocket/HTTP client.

These options control connection behavior including:

• HTTP protocol version (HTTP/1.1 or HTTP/2)
• Automatic reconnection on connection loss
• Reconnection timing and retry limits

Separate from SubscriptionOptions which control individual subscriptions.

Example

use kalam_client::{ConnectionOptions, HttpVersion};

let options = ConnectionOptions::default()
    .with_http_version(HttpVersion::Http2)
    .with_auto_reconnect(true)
    .with_reconnect_delay_ms(2000)
    .with_max_reconnect_attempts(Some(10));

Fields

http_version: HttpVersion

HTTP protocol version to use for connections Default: Http1 (HTTP/1.1) for maximum compatibility Use Http2 for better performance with multiple concurrent requests

auto_reconnect: bool

Enable automatic reconnection on connection loss Default: true - automatically attempts to reconnect

reconnect_delay_ms: u64

Initial delay in milliseconds between reconnection attempts Default: 1000ms (1 second) Uses exponential backoff up to max_reconnect_delay_ms

max_reconnect_delay_ms: u64

Maximum delay between reconnection attempts (for exponential backoff) Default: 30000ms (30 seconds)

max_reconnect_attempts: Option<u32>

Maximum number of reconnection attempts before giving up Default: None (infinite retries) Set to Some(0) to disable reconnection entirely

timestamp_format: TimestampFormat

Timestamp format to use for displaying timestamp columns Default: Iso8601 (2024-12-14T15:30:45.123Z) This allows clients to control how timestamps are displayed

ping_interval_ms: u64

Application-level keepalive ping interval in milliseconds.

Browser WebSocket APIs do not expose protocol-level Ping frames, so the WASM client sends a JSON {"type":"ping"} message at this interval to prevent the server-side heartbeat timeout from firing on idle connections.

Set to 0 to disable. Default: 5_000 (5 seconds).

ws_local_bind_addresses: Vec<String>

Optional local source IP addresses for outbound WebSocket connections.

When non-empty, each subscription connection binds to one of these addresses before dialing the server. This enables source-IP sharding (for example 127.0.0.1,127.0.0.2,...) to increase per-host concurrency under local ephemeral-port limits.

Values must be IP literals (IPv4 or IPv6), not hostnames.

disable_compression: bool

Disable server-side gzip compression on this WebSocket connection.

When true the client appends ?compress=false to the WebSocket URL. The server will then send all messages as plain JSON text frames instead of gzip-compressed binary frames, making traffic inspectable in browser DevTools or packet-capture tools.

Do not enable in production — compression reduces bandwidth by ~70% for large payloads. Default: false.

ws_lazy_connect: bool

Defer the WebSocket connection until the first live stream is opened.

When true (the default), calling connect() is not required — the client will automatically open the shared WebSocket connection the first time live_events() (or live_events_with_config()) is called. The same AuthProvider used for HTTP queries is reused for the WebSocket handshake.

When false, the caller is expected to establish the WebSocket connection explicitly by calling connect() before opening live streams.

Default: true.

protocol: ProtocolOptions

Protocol options for the WebSocket connection.

Controls the serialization format (JSON or MessagePack) and compression (None or Gzip) used for WebSocket messages after authentication.

Authentication messages are always sent as JSON text frames regardless of this setting. The negotiated protocol takes effect after the server confirms it in the AuthSuccess response.

Default: JSON serialization + Gzip compression.

Implementations

impl ConnectionOptions

pub fn new() -> ConnectionOptions

Create new connection options with defaults

pub fn with_http_version(self, version: HttpVersion) -> ConnectionOptions

Set the HTTP protocol version to use

• HttpVersion::Http1 - HTTP/1.1 (default, maximum compatibility)
• HttpVersion::Http2 - HTTP/2 (better performance for concurrent requests)
• HttpVersion::Auto - Let the client negotiate with the server

pub fn with_auto_reconnect(self, enabled: bool) -> ConnectionOptions

Set whether to automatically reconnect on connection loss

pub fn with_reconnect_delay_ms(self, delay_ms: u64) -> ConnectionOptions

Set the initial delay between reconnection attempts (in milliseconds)

pub fn with_max_reconnect_delay_ms(self, max_delay_ms: u64) -> ConnectionOptions

Set the maximum delay between reconnection attempts (in milliseconds)

pub fn with_max_reconnect_attempts( self, max_attempts: Option<u32>, ) -> ConnectionOptions

Set the maximum number of reconnection attempts Pass None for infinite retries, Some(0) to disable reconnection

pub fn with_timestamp_format(self, format: TimestampFormat) -> ConnectionOptions

Set the timestamp format for displaying timestamp columns

pub fn create_formatter(&self) -> TimestampFormatter

Create a timestamp formatter from this configuration

pub fn with_ping_interval_ms(self, ms: u64) -> ConnectionOptions

Set the application-level keepalive ping interval in milliseconds.

Set to 0 to disable pings.

pub fn with_ws_local_bind_addresses( self, addresses: Vec<String>, ) -> ConnectionOptions

Set local source IP addresses for outbound WebSocket connections.

pub fn with_disable_compression(self, disable: bool) -> ConnectionOptions

Disable server-side gzip compression for debugging.

Do not enable in production.

pub fn with_ws_lazy_connect(self, lazy: bool) -> ConnectionOptions

Control lazy WebSocket connections.

When true (the default), the shared WebSocket connection is deferred until the first subscribe() call, removing the need to call connect() explicitly. Authentication uses the same provider configured for HTTP queries.

Set to false to require an explicit connect() call before subscribing.

pub fn with_protocol(self, protocol: ProtocolOptions) -> ConnectionOptions

Set the protocol options for the WebSocket connection.

Trait Implementations

impl Clone for ConnectionOptions

fn clone(&self) -> ConnectionOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ConnectionOptions

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

Formats the value using the given formatter.

impl Default for ConnectionOptions

fn default() -> ConnectionOptions

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ConnectionOptions

fn deserialize<__D>( __deserializer: __D, ) -> Result<ConnectionOptions, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ConnectionOptions

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

where __S: Serializer,

Serialize this value into the given Serde serializer.