Skip to content

README.md

Latest commit

 

History

History
119 lines (91 loc) · 4.28 KB

README.md

File metadata and controls

119 lines (91 loc) · 4.28 KB
Raw

oxia-client-rust

Crates.io Docs.rs CI MSRV License

The native Rust client SDK for Oxia, a distributed key-value and metadata store. Built on the Tokio asynchronous runtime, it offers an idiomatic, comprehensive API — plus an optional C FFI for use from other languages.

Quickstart

[dependencies]
oxia-client = "0.1"
use oxia::{ComparisonType, OxiaClient};

#[tokio::main]
async fn main() -> Result<(), oxia::OxiaError> {
    let client = OxiaClient::connect("localhost:6648").await?;

    client.put("greeting", "hello").await?;
    let record = client.get("greeting").await?;
    assert_eq!(record.value.as_deref(), Some(b"hello".as_ref()));

    client.close().await?;
    Ok(())
}

Every operation returns a builder you chain options onto and .await:

client.put("locks/w1", "").ephemeral().await?;
let floor = client.get("config/z").comparison(ComparisonType::Floor).await?;
let keys = client.list("users/", "users/~").await?;

See the API documentation for the full guide, and the runnable examples.

Features

Data-plane feature parity with the reference Go and Java clients:

Feature Rust Go Java
Put / Get / Delete / Delete-range ✅ ✅ ✅
Conditional writes (compare-and-swap) ✅ ✅ ✅
Partition keys ✅ ✅ ✅
Sequential keys ✅ ✅ ✅
Secondary indexes ✅ ✅ ✅
Ephemeral records & sessions ✅ ✅ ✅
Notifications ✅ ✅ ✅
Sequence updates ✅ ✅ ✅
Floor / Ceiling / Lower / Higher get ✅ ✅ ✅
List / Range scan (streaming) ✅ ✅ ✅
Adaptive request batching ✅ ✅ ✅
Automatic retries & shard re-routing ✅ ✅ ✅
TLS ✅¹ ✅ ✅
Token authentication ✅ ✅ ✅
OpenTelemetry metrics ✅¹ ✅ ✅

✅ supported

¹ Behind an off-by-default Cargo feature (tls and otel, respectively).

Compatibility

The client speaks Oxia's io.oxia.proto.v1 gRPC protocol and requires a server that serves it (current Oxia releases; CI runs against the oxia/oxia:main image). It does not support the legacy io.streamnative.oxia.proto service.

oxia-client Oxia server Rust toolchain
0.1.x serves io.oxia.proto.v1 (recent releases) 1.85+ (edition 2024)

Crates

  • oxia-client — the core async Rust client (published to crates.io as oxia-client, imported as use oxia::…).
  • oxia-client-ffi — a C Foreign Function Interface over oxia-client, exposing it to C/C++ applications.
  • oxia-perf — a load-generation and latency-measurement CLI (like the Go and Java SDKs' perf tools): drives a configurable read/write mix at a target rate and reports throughput and latency percentiles. Run cargo run -p oxia-perf -- --help.

Documentation

Contributing

Contributions are welcome — see CONTRIBUTING.md for how to build, test, and submit changes, and RELEASING.md for the release process. To report a security issue, see SECURITY.md.

License

Licensed under the Apache License 2.0.