Transport & Endpoints

kalam-client is a high-level wrapper over the same public endpoints described in the server API reference.

SQL execution (HTTP)

execute_query(...) → POST /v1/api/sql

See: HTTP API Reference
See: SQL Reference

The client sends params as JSON for $1, $2, … placeholders and optionally sets a namespace header for unqualified table names.

Multipart file uploads (execute_with_files) use the same SQL endpoint with multipart bodies when file-uploads is enabled.

File downloads (HTTP)

SDK method	HTTP endpoint
`download_bound_file(&BoundFileRef, ...)`	`GET /v1/files/{namespace}/{table}/{sub}/{stored_name}`
`download_file(&FileRef, namespace, table, ...)`	same path with explicit namespace/table strings

Downloads reuse the client’s JWT (or basic-auth exchange). Optional target_user_id maps to the user_id query parameter for cross-user USER-table access by privileged roles.

See FILE Columns & Uploads.

Authentication endpoints

Used by the SDK when auth-flows is enabled (default via native-sdk):

SDK method	HTTP endpoint
`login(user, password)`	`POST /v1/api/auth/login`
`refresh_access_token(refresh_token)`	`POST /v1/api/auth/refresh`

Basic credentials on AuthProvider::basic_auth are exchanged through login before authenticated SQL or WebSocket traffic.

Live subscriptions (WebSocket)

live() / live_events() use the shared WebSocket realtime endpoint.

See: WebSocket Protocol
See: Architecture: Live Query

Subscriptions multiplex over one connection per KalamLinkClient. Call connect() to open the socket explicitly, or rely on lazy connect (default) on the first subscription.

Compression

ConnectionOptions controls WebSocket compression. For local debugging you can disable compression so frames are easier to inspect — do not disable in production.

Message serialization

The native Rust client uses the shared link-common protocol. Debug hooks on_receive / on_send on EventHandlers can log wire traffic during development.

Topic consume (HTTP)

With the consumer feature, TopicConsumer::poll() and commit_sync() call the topic consume/ack HTTP APIs documented under Topic Pub/Sub.

Diagnostics endpoints (optional features)

Feature	SDK method	Endpoint
`healthcheck`	`health_check()`	`GET /v1/api/healthcheck`
`cluster`	`cluster_health_check()`	`GET /v1/api/cluster/health`
`setup`	`check_setup_status()`	`GET /v1/api/auth/status`
`setup`	`server_setup(...)`	`POST /v1/api/auth/setup`

See Server Setup & Diagnostics Boundary.

Timeouts and retries

Configured on KalamLinkClient::builder():

RUST

1let client = KalamLinkClient::builder()2    .base_url("http://localhost:2900")3    .auth(AuthProvider::jwt_token(token))4    .timeout(Duration::from_secs(10))5    .max_retries(2)6    .build()?;

timeout — per HTTP request deadline
max_retries — idempotent query retries
timeouts(KalamLinkTimeouts::...) — granular WebSocket and HTTP phases

Environment variables (examples and local dev)

Variable	Typical use
`KALAMDB_SERVER_URL`	Base URL in workspace examples
`KALAMDB_ROOT_PASSWORD`	`system_user_auth` in examples