Crate oxia 

Rust client SDK for Oxia, a scalable metadata store and coordination system.

The entry point is OxiaClient. Every operation returns a request builder: chain options onto it and .await it directly.

use oxia::{ComparisonType, OxiaClient};

let client = OxiaClient::connect("localhost:6648").await?;

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

// Options chain onto the builder.
client
    .put("config/a", "1")
    .expected_version_id(res.version.version_id)
    .await?;
client.put("locks/w1", "").ephemeral().await?;
let floor = client.get("config/z").comparison(ComparisonType::Floor).await?;

// Range operations, as a whole result or as an ordered stream.
let keys = client.list("config/", "config/~").await?;
let mut scan = client.range_scan("config/", "config/~").stream().await?;
client.close().await?;

Concepts

• Records are key/value pairs with a Version carrying the record’s version id and timestamps; conditional operations (expected_version_id) implement compare-and-swap.
• Ephemeral records (PutBuilder::ephemeral) live as long as the client’s session and are removed automatically when it closes or expires.
• Partition keys (PutBuilder::partition_key) co-locate related records on one shard, enabling atomic multi-record batches and server-generated sequential keys (PutBuilder::sequence_key_deltas, OxiaClient::sequence_updates).
• Secondary indexes (PutBuilder::secondary_index) provide alternate query paths for gets, lists and scans (GetBuilder::use_index, ListBuilder::use_index).
• Notifications (OxiaClient::notifications) stream every change applied to the database.

Keys are sorted with Oxia’s slash-aware order (/-separated path segments), not plain lexicographic order; range boundaries follow it.

Error handling

Every operation returns OxiaError. Semantic outcomes callers commonly match on are dedicated variants (OxiaError::KeyNotFound, OxiaError::UnexpectedVersionId, …); transient infrastructure failures answer true to OxiaError::is_retryable and are safe to retry — idempotent operations unconditionally, non-idempotent ones (puts without a version condition) with application-level judgment. Each operation on OxiaClient documents the errors it can produce.

The client retries retryable failures internally — re-routing via the leader hints the server attaches to routing errors, re-hashing operations onto the new shard when a shard is split or merged, with exponential backoff, bounded by the request timeout — so the errors you observe are post-retry. One consequence, shared with the reference clients: a write whose batch failed after reaching the wire may be retried even though the server already applied it, so unconditional writes have at-least-once semantics under retries; version-conditioned writes are exactly-once.

Cancellation

Dropping an operation’s future stops waiting but does not recall an operation already submitted to a batch; it may still execute on the server. The recv methods on Notifications and SequenceUpdates are cancel-safe.

Structs

Bytes

A cheaply cloneable and sliceable chunk of contiguous memory.

DeleteBuilder

A pending delete, created with OxiaClient::delete. Chain options and .await it.

DeleteRangeBuilder

A pending delete_range, created with OxiaClient::delete_range. Chain options and .await it.

GetBuilder

A pending get, created with OxiaClient::get. Chain options and .await it.

GetResult

A record returned by get or range_scan.

ListBuilder

A pending list, created with OxiaClient::list.

ListStream

An ordered stream of keys produced by ListBuilder::stream.

Notifications

A subscription to database change notifications, created with OxiaClient::notifications.

NotificationsBuilder

A pending notifications subscription, created with OxiaClient::notifications. .await it to obtain the Notifications stream.

OxiaClient

The Oxia client.

OxiaClientBuilder

Configures and creates an OxiaClient.

PutBuilder

A pending put, created with OxiaClient::put. Chain options and .await it.

PutResult

The result of a successful put.

RangeScanBuilder

A pending range_scan, created with OxiaClient::range_scan.

RangeScanStream

An ordered stream of records produced by RangeScanBuilder::stream.

SequenceUpdates

A subscription to sequence advances, created with OxiaClient::sequence_updates.

SequenceUpdatesBuilder

A pending sequence-updates subscription, created with OxiaClient::sequence_updates. .await it to obtain the SequenceUpdates stream.

Version

Metadata about the state of a record.

Enums

ComparisonType

The key comparison applied by a get operation.

Notification

A change notification streamed from OxiaClient::notifications.

OxiaError

Errors returned by the Oxia client.