Use the Rust SDK

Applies to: current development source bundles. Obtain a matched client/server release through early-access support; registry publication is not available yet. Paths below are relative to the supplied source checkout.

Async Tokio application client for SMKV's TCP data protocol. This first release is available from this repository; it has not been published to crates.io. It inherits the workspace's Rust 1.89 minimum and prohibition on unsafe code.

Install and run

Add a path dependency in your application's Cargo.toml (adjust the path):

[dependencies]
smkv-client = { path = "../smkv/crates/smkv-client" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use smkv_client::{Client, Columns, Options, Value, WriteOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new("127.0.0.1:7379", Options::default())?;
    let write = WriteOptions { sync: true, ..WriteOptions::default() };
    client.put(b"greeting", b"hello", write).await?;
    assert_eq!(client.get(b"greeting").await?, b"hello");
    let users = client.table("users")?;
    users.put(b"42", &Columns::from([
        ("name".into(), Value::String("Ada".into())),
        ("visits".into(), Value::Int(1)),
    ]), write).await?;
    println!("{:?}", users.get(b"42", &["name"]).await?);
    client.close();
    Ok(())
}

Run the included example against a disposable node: cargo run -p smkv-client --example basic -- 127.0.0.1:7379.

Cluster and security

Use ClusterClient::connect(vec!["127.0.0.1:7381".into()], options).await? with management seed endpoints. It discovers data endpoints and routes keys to their primary; get_replica explicitly permits stale reads. Cluster tables have the same interface. Call cluster.close().await when finished.

Options.security configures data connections and Options.management_security configures discovery independently. Both default to plaintext/no authentication. Use Security::tls_ca_pem(&std::fs::read("ca.pem")?)? and/or .with_credential(name, token)?. TLS verifies the endpoint hostname/IP against the supplied CA. There is no insecure verification mode or automatic downgrade.

Operations and guarantees

• get, put, delete; table get, put, update, delete, projections, and get_replica. Columns are bytes, string, signed int64, float64, or bool.
• WriteOptions.ttl_ms: omitted means no expiry on put, preserved expiry on update; zero expires immediately. Delete does not accept a TTL.
• sync, replica_ack, durable_replica_ack request the server's corresponding acknowledgment guarantees. The default is not a per-write disk sync.
• Default pool: four connections per node, five-second operation/idle timeouts, 1 KiB key and 1 MiB value limits. Options adjusts these limits; the server's limits must also permit the record. Clones share the pool and close state.
• ErrorKind::NotFound differs from an empty value. Inspect Error.outcome_unknown before considering a retry. A mutation may have completed after a network failure or timeout. Dropping a mutation future has the same risk.
• Only an explicit WrongOwner response triggers automatic rediscovery/retry, within the original deadline. Other failures return to the application.

Scans, batch operations, and a blocking Rust API are not included in this release. See shared contract and test instructions.