Client Lifecycle

Creating a client

1use std::{sync::Arc, time::Duration};2use kalam_client::{AuthProvider, EventHandlers, KalamLinkClient};3 4let handlers = EventHandlers::new()5    .on_connect(|| println!("connected"))6    .on_disconnect(|reason| println!("disconnected: {reason}"))7    .on_error(|error| eprintln!("connection error: {}", error.message));8 9let client = KalamLinkClient::builder()10    .base_url("http://localhost:2900")11    .auth(AuthProvider::jwt_token(token))12    .timeout(Duration::from_secs(30))13    .max_retries(3)14    .event_handlers(handlers)15    .build()?;

Notes:

• build() returns a ready client handle. HTTP queries work immediately.
• Live subscriptions additionally use the shared WebSocket.
• base_url is required; everything else has defaults.

WebSocket lazy connect (default: true)

ConnectionOptions::ws_lazy_connect defaults to true. The shared WebSocket opens on the first live() or live_events() call, not at build() time.

Eager connect:

1use kalam_client::ConnectionOptions;2 3let client = KalamLinkClient::builder()4    .base_url("http://localhost:2900")5    .auth(AuthProvider::jwt_token(token))6    .connection_options(ConnectionOptions::default().with_ws_lazy_connect(false))7    .build()?;8 9client.connect().await?; // opens socket immediately

Explicit connect and disconnect

1client.connect().await?;2assert!(client.is_connected().await);3 4client.disconnect().await;

Call connect() before multiple subscriptions so they share one socket and one auth context.

Auth refresh model

• Static AuthProvider on the builder is resolved at build time.
• DynamicAuthProvider re-runs on connect/reconnect via fresh_auth().
• auth_refresher handles TOKEN_EXPIRED during query/subscription operations.
• set_auth / update_shared_auth push new credentials without rebuilding the client.

See Authentication and Auth-Aware Client.

Event handlers

EventHandlers callbacks:

Handlers are Arc-backed and safe to share across cloned clients.

Timeouts and retries

1use kalam_client::KalamLinkTimeouts;2 3let client = KalamLinkClient::builder()4    .base_url("http://localhost:2900")5    .timeout(Duration::from_secs(10))6    .max_retries(2)7    .timeouts(KalamLinkTimeouts::builder().receive_timeout(Duration::from_secs(15)).build())8    .build()?;

• timeout — HTTP request timeout (default 30s)
• max_retries — retries for idempotent HTTP queries (default 3)
• timeouts(...) — finer-grained send/receive limits for HTTP and WebSocket

Shutdown checklist

1. live.close().await? / events.close().await? for each open subscription
2. consumer.close().await? for each topic consumer
3. client.disconnect().await to close the shared WebSocket

Long-running services should always close streams before dropping the client.

Cloning and sharing

KalamLinkClient is cloneable (Arc internally). Clone handles share connection state — useful for spawning multiple subscription tasks from one service.

Next

• Realtime Subscriptions
• Transport & Endpoints
• Auth-Aware Client