Skip to content

DEV.md

Latest commit

 

History

History
168 lines (115 loc) · 4.82 KB

DEV.md

File metadata and controls

168 lines (115 loc) · 4.82 KB
Raw

kalam-client — Developer Notes

This document is for contributors working on the Rust SDK in link/sdks/rust/.

For usage documentation, see README.md.

Architecture

The Rust SDK is a native Tokio client built on the shared link implementation:

Application (Rust service, CLI, worker)
  └─ kalam-client (crates.io, source in link/sdks/rust/)
      └─ link/link-common/src/             ← shared transport, auth, live rows, consumer
          └─ backend/crates/kalamdb-commons ← protocol types and shared IDs

The same link-common core also powers:

  • @kalamdb/client (WASM via kalam-link-wasm)
  • @kalamdb/consumer (separate WASM entry crate kalam-consumer-wasm)
  • kalam_link (Dart via kalam-link-dart)
  • kalamdb (Python via PyO3 in link/sdks/python)

TypeScript splits consumer into @kalamdb/consumer. Rust keeps topic workers in the same crate behind the consumer Cargo feature.

Repository Layout

Path Purpose
link/sdks/rust/README.md Canonical user-facing SDK readme (referenced by the crate manifest)
link/sdks/rust/QUICKSTART.md Short onboarding guide
link/sdks/rust/examples/ Runnable example binaries
link/sdks/rust/ The kalam-client crate published to crates.io
link/sdks/rust/tests/ Offline API tests (no server)
link/sdks/rust-e2e/tests/ Server-backed integration tests
link/sdks/rust/publish.sh crates.io publish helper
link/link-common/ Shared implementation (path dependency today)

Prerequisites

Tool Version
Rust 1.99.1 (workspace MSRV)
Tokio via native-sdk feature (default)

Build From Source

Compile the library crate from the link workspace:

cd link
cargo build -p kalam-client --features native-sdk

Build all link workspace members:

cd link
cargo build --workspace

Enable consumer or file uploads in dependent crates:

cargo build -p topic-consumer

Running Examples

Examples live under link/sdks/rust/examples/ and depend on kalam-client via path.

cd link/sdks/rust

# Terminal 1: start a KalamDB server
cd ../../../backend && cargo run --bin kalamdb-server

# Terminal 2: run examples
export KALAMDB_SERVER_URL=http://localhost:2900
export KALAMDB_ROOT_PASSWORD=kalamdb123

cargo run -p quickstart
cargo run -p file-attachments
cargo run -p live-inbox
cargo run -p topic-consumer

topic-consumer requires the consumer feature and topic routing support on the server.

Running Tests

SDK-focused tests:

cd link/sdks/rust
NO_SERVER=true ./test.sh          # offline API tests only
./test.sh                         # offline + integration + quickstart example

Server-backed integration tests compile separately in kalam-client-e2e (includes the full server graph only when you run them):

cd link
cargo nextest run -p kalam-client-e2e --test e2e

CI uses the release-server harness:

KALAMDB_SERVER_BIN=./kalamdb-server ./scripts/test-rust-sdk-release.sh

Feature Flags

Feature Enables
native-sdk (default) tokio-runtime, auth-flows
consumer TopicConsumer, client.consumer(), consume/ack APIs
file-uploads Multipart SQL upload helpers
healthcheck Cached health endpoint helper
setup Bootstrap/setup helpers
cluster Cluster health inspection

Recommended app dependency:

kalam-client = { version = "0.5", features = ["native-sdk"] }

Workers that consume topics:

kalam-client = { version = "0.5", features = ["native-sdk", "consumer"] }

Publishing to crates.io

The published crate name is kalam-client. Source, docs, examples, and tests all live under link/sdks/rust/.

Today the crate depends on path-only workspace crates (link-common, kalamdb-commons, …). Before the first public release, publish or vendor those dependencies so cargo publish --dry-run succeeds without path references.

Use the helper script:

cd link/sdks/rust
./publish.sh --dry-run

Environment:

  • CARGO_REGISTRY_TOKEN — crates.io API token (required except for --dry-run)

Options mirror the TypeScript SDK publish script:

  • --dry-run — validate packaging without uploading
  • --skip-check — skip cargo test gate
  • --version VERSION — override version written into link/sdks/rust/Cargo.toml

Versioning

Release versions are tracked in the repo-root Cargo.toml workspace and mirrored in versions.json under packages.rust.kalam-client.

When bumping SDK versions, keep kalam-client, TypeScript packages, Dart, and Python cohorts aligned via python3 scripts/versions.py verify.

License

Apache-2.0. See LICENSE.