Expand description
§OpenKache Rust client
OpenKache is a high-performance cache server designed from the ground up for modern SSDs. Use this async Rust client to store, read, and delete values in a few lines.
crates.io package · docs.rs API reference · GitHub source
§Install
Rust 1.85 or newer and a native C linker are required.
# OpenKache client
cargo add openkacheThe default quic-quinn client uses Tokio internally, so an active Tokio
runtime is required for Client. The example below uses #[tokio::main]; use
the runtime setup already used by your application.
§Quick start
The example below assumes a local OpenKache server at 127.0.0.1:4433.
use openkache::Client;
#[tokio::main]
async fn main() -> openkache::Result<()> {
let client = Client::connect("127.0.0.1:4433").await?;
client.set("greeting", "hello").await?;
println!("{:?}", client.get("greeting").await?);
client.delete("greeting").await?;
client.close().await?;
Ok(())
}The local development TLS profile does not verify the server certificate. Use this example only with a local development server.
Value is the Rust type used for structured values. Writes accept common Rust
values directly and convert them to Value; construct an explicit variant
when float width, raw bits, or model map keys matter.
The Rust client uses OpenKache’s structured value format.
§Serde Rust values
Client::set_serde and Client::get_serde use Serde while retaining the
same lossless structured-value format as set and get. Add Serde to the
application when defining types for these helpers:
cargo add serde --features deriveuse openkache::Client;
use serde::{Deserialize, Serialize};
#[derive(Debug, Deserialize, Serialize)]
struct User {
id: u64,
name: String,
}
async fn example() -> openkache::Result<()> {
let client = Client::connect("127.0.0.1:4433").await?;
client
.set_serde("user:1", &User { id: 7, name: "Ada".into() })
.await?;
let user: User = client.get_serde("user:1").await?.unwrap();
assert_eq!(user.id, 7);
assert_eq!(user.name, "Ada");
client.close().await?;
Ok(())
}get_serde returns Result<Option<T>>; in this example, T is User, so a
hit is Some(User). The final unwrap handles the expected hit in this
small example; production code should decide how a missing key is handled.
None remains distinct from a stored Value::Null for get; a stored null
decodes as Some(None) for get_serde::<Option<T>>. Integers are
range-checked, floating-point values retain their IEEE-754 bits, and map keys
must be scalar and unique. Serde serialization happens before write admission,
so Error::SerdeSerialize cannot produce an unknown mutation. A value that
does not match the requested type returns Error::SerdeDeserialize.
set_serde stores the structured model as StructuredValue-CBOR-v1, not as
an opaque Rust-specific payload. Python and JavaScript clients can therefore
read a value written by set_serde as a structured object, array, scalar, or
null. Keep the schema within the cross-language value model; opaque bytes,
unsupported map keys, and serializer-specific representations remain
application-owned.
§Structured codecs with get_with and set_with
For a non-Serde structured serializer, implement ValueCodec<T> or construct
one with FunctionCodec::new(encode, decode). This complete example maps a
Point struct to a structured Value map:
FunctionCodec is a small adapter around two application functions:
encode(&T) -> Result<Value, EncodeError> runs before a write is admitted, and
decode(Value) -> Result<T, DecodeError> runs after a value is retrieved. The
client does not inspect or invoke the application’s serializer; it only stores
the resulting structured Value. An encode failure is returned as
Error::CodecEncode, and a decode failure as Error::CodecDecode.
use openkache::{Client, FunctionCodec, Value};
#[derive(Debug, PartialEq)]
struct Point {
x: i64,
y: i64,
}
fn encode_point(point: &Point) -> Result<Value, &'static str> {
Value::map(vec![
(Value::text("x"), Value::integer(point.x)),
(Value::text("y"), Value::integer(point.y)),
])
.map_err(|_| "point fields must be unique scalar keys")
}
fn decode_point(value: Value) -> Result<Point, &'static str> {
let entries = value.as_map().ok_or("expected a point object")?;
let mut x = None;
let mut y = None;
for (key, value) in entries {
let key = match key {
Value::TextString(key) => key,
_ => return Err("point fields must be text keys"),
};
let value = match value {
Value::Integer(value) => value.as_i128().ok_or("point must fit in i128")?,
_ => return Err("point fields must be integers"),
};
match key.as_str() {
"x" => x = Some(value),
"y" => y = Some(value),
_ => return Err("unknown point field"),
}
}
Ok(Point {
x: x.ok_or("missing x")?,
y: y.ok_or("missing y")?,
})
}
async fn example() -> openkache::Result<()> {
let client = Client::connect("127.0.0.1:4433").await?;
let point = Point { x: 3, y: 4 };
let point_codec = FunctionCodec::new(encode_point, decode_point);
client.set_with("point:1", &point, &point_codec).await?;
assert_eq!(
client.get_with("point:1", &point_codec).await?.unwrap(),
point,
);
client.close().await?;
Ok(())
}§Custom binary payloads
Use byte payloads when the application owns the serialized format. This example uses bincode 2; pin the serializer major version and configuration because the bytes are an application schema contract:
cargo add bincode@2 --features serde
cargo add serde --features deriveThe client stores and returns the bytes without inspecting them; other language clients receive a byte value and need the same application format to decode it:
use bincode::config;
use openkache::{Client, Value};
use serde::{Deserialize, Serialize};
#[derive(Debug, Deserialize, PartialEq, Serialize)]
struct Session {
user_id: u64,
flags: u8,
}
fn invalid_data(message: &'static str) -> Box<dyn std::error::Error> {
std::io::Error::new(std::io::ErrorKind::InvalidData, message).into()
}
async fn example() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::connect("127.0.0.1:4433").await?;
let session = Session {
user_id: 7,
flags: 0b101,
};
let payload = bincode::serde::encode_to_vec(&session, config::standard())?;
client
.set("session:1", Value::bytes(payload))
.await?;
let stored = client.get("session:1").await?;
let bytes = match &stored {
Some(Value::Bytes(bytes)) => bytes,
Some(_) => return Err(invalid_data("expected opaque bytes")),
None => return Err(invalid_data("session is missing")),
};
let (decoded, _bytes_read): (Session, usize) =
bincode::serde::decode_from_slice(bytes, config::standard())?;
assert_eq!(decoded, session);
client.close().await?;
Ok(())
}Application-owned payloads normally use ordinary get/set. A
ValueCodec can wrap an opaque serializer only when it maps the encoded bytes
to and from Value::Bytes; the client still does not inspect that format.
§Reference
§Client::connect(endpoint)
Opens a connection and returns a Client.
- Input: a
host:portendpoint. IPv6 endpoints use[host]:port. - Returns: an async
Result<Client>. - Errors:
Error::Corewhen the endpoint, TLS handshake, or protocol setup fails.
let client = Client::connect("127.0.0.1:4433").await?;§client.get(key)
Reads one Value.
- Input: anything that converts into
TypedKey: text, bytes, or a signed 64-bit integer. - Returns:
Ok(Some(value))when the key exists, orOk(None)when it does not. A storedValue::NullorValue::Undefinedis stillSome. - Errors:
Error::Corefor connection, protocol, key, or value failures.
match client.get("greeting").await? {
Some(value) => println!("{value:?}"),
None => println!("missing"),
}§client.set(key, value)
Stores one value with an unconditional write.
- Input: a
TypedKey-convertible key and any value that implementsInto<Value>. Common strings, byte slices, booleans, integers, and floats are accepted directly. - Returns:
Ok(SetOutcome::Created)for a new key orOk(SetOutcome::Replaced)for an existing key. - Errors:
Error::UnknownMutationwhen admission happened but the result was not confirmed; do not replay that mutation. Other failures are returned asError::Core.
let outcome = client.set("greeting", "hello").await?;§client.get_serde<T>(key)
Reads one value and decodes it into T: serde::de::DeserializeOwned.
- Returns:
Ok(Some(value))for a matching stored value, orOk(None)when the key does not exist. - Errors:
Error::SerdeDeserializefor a type mismatch, overflow, or unsupported stored value; transport and protocol failures useError::Core.
§client.set_serde(key, value)
Serializes value: impl serde::Serialize and stores it with an unconditional
write. Serde serialization completes before network admission.
- Returns: the same
SetOutcomeasclient.set. - Errors:
Error::SerdeSerializefor values that cannot be represented by the structured model, or the transport and mutation errors fromclient.set.
§client.get_with and client.set_with
Use an application-provided ValueCodec<T> for a non-Serde structured format.
FunctionCodec::new(encode, decode) is the convenient form when two functions
are enough; implement ValueCodec<T> directly when the codec needs state or
more control. The codec operates on Value, so it does not alter wire
admission or mutation semantics. Encoding happens before admission, so a
codec error cannot produce Error::UnknownMutation; decoding happens after
retrieval and leaves None unchanged. The value type is normally inferred from
the codec, so no turbofish is needed. If inference is ambiguous, annotate the
result as Option<Point>.
§client.delete(key)
Deletes one key. Repeating the operation is safe.
- Input: a
TypedKey-convertible key. - Returns:
Ok(true)when a value was removed, orOk(false)when no value existed. - Errors:
Error::UnknownMutationwhen the result of an admitted delete was not confirmed.
let removed = client.delete("greeting").await?;
if removed {
println!("deleted");
}§client.close()
Closes the connection after admitted operations settle. Repeated calls are safe.
- Returns:
Result<()>.
client.close().await?;§Keys
Use TypedKey constructors when you want to make the key type explicit:
TypedKey::text(value)creates a UTF-8 text key.TypedKey::bytes(value)creates an exact byte key.TypedKey::integer(value)creates a signed 64-bit integer key.TypedKey::canonical_bytes()returns the encoded key.
The client also accepts common Rust conversions directly:
client.get("text-key").await?;
client.get(b"bytes-key").await?;
client.get(42_i64).await?;KeyError describes invalid or out-of-range keys.
§Values
Value is the structured value type returned by get and accepted by set:
Undefined | Null | Boolean | Integer | Float | TextString | Bytes | Array | MapConstruct values with:
Value::integer(value)for an exact integer.Value::float16(bits),Value::float32(bits), orValue::float64(bits)for exact IEEE-754 bits.Value::text(value)for UTF-8 text.Value::bytes(value)for exact bytes.Value::array(values)for an ordered array.Value::map(entries)for an ordered map with scalar, unique keys.Value::to_cbor()andValue::from_cbor(bytes)to encode or decode one complete structured value.
For common writes, the client also accepts &str, String, &[u8],
Vec<u8>, booleans, all signed and unsigned integer types, f32, and f64:
client.set("name", "Ada").await?;
client.set("count", 42_u64).await?;
client.set("payload", b"bytes").await?;let value = Value::map(vec![
(Value::text("count"), Value::integer(1_i128)),
])?;
client.set("stats", value).await?;Inspect a structured value with ValueKind and borrowed accessors:
use openkache::{Client, Value, ValueKind};
#[tokio::main]
async fn main() -> openkache::Result<()> {
let client = Client::connect("127.0.0.1:4433").await?;
let profile = Value::map(vec![
(Value::text("name"), Value::text("Ada")),
(Value::text("visits"), Value::integer(3)),
(Value::text("active"), Value::from(true)),
])
.map_err(|error| openkache::Error::Core(error.to_string()))?;
client.set("profile", profile).await?;
let profile = match client.get("profile").await? {
Some(value) => value,
None => {
return Err(openkache::Error::Core("profile is missing".into()));
}
};
assert_eq!(profile.kind(), ValueKind::Map);
assert_eq!(
profile.map_get("name").and_then(Value::as_str),
Some("Ada"),
);
assert_eq!(
profile
.map_get("visits")
.and_then(Value::as_integer)
.and_then(|value| value.as_i128()),
Some(3),
);
assert_eq!(
profile.map_get("active").and_then(Value::as_bool),
Some(true),
);
assert_eq!(profile.map_get("name").and_then(Value::as_bool), None);
client.close().await?;
Ok(())
}map_get and the typed accessors do not coerce values: a missing key or a
mismatched type returns None, so reading the text name with as_bool
above is safe.
For exact integer and float construction, use Integer, Sign,
Float, and FloatWidth. ValueLimits bounds bytes, depth, item count, and
integer magnitude. ValueError reports value validation and encoding errors;
use ValueError::kind() for its stable category.
Result<T> is the result alias returned by client methods.
§Results and errors
- Get methods return
Result<Option<T>>; standardOptionmethods such asunwrap,expect,unwrap_or, andunwrap_or_elsehandle missing keys. SetOutcomeisCreatedorReplaced.SetOutcome::is_createdandSetOutcome::is_replacedinspect the write outcome without matching on its variants.deletereturnstruewhen an item existed andfalseotherwise.Error::UnknownMutationmeans asetordeletemay have reached the server without a confirmed result. ItsMutationidentifies the operation; do not replay it automatically. UseError::is_unknown_mutation,Error::mutation, andError::kindto inspect errors without matching on their payloads.Error::Corereports connection, protocol, key, value, or server failures.Error::SerdeSerializeandError::SerdeDeserializereport Serde conversion failures before and after transport, respectively.Error::CodecEncodeandError::CodecDecodereport applicationValueCodecfailures before and after transport, respectively.Error::UnsupportedSetOutcomereports a server result outside the unconditional-write API.
§More information
Structs§
- Client
- A connected OpenKache client.
- Float
- An IEEE-754 value with its wire width and exact raw bits.
- Function
Codec - A codec assembled from application-provided encode and decode functions.
- Integer
- An exact arbitrary-precision signed integer.
- Serde
Codec - The built-in
ValueCodecbacked by Serde. - Value
Limits - A bounded resource budget for encoding and decoding.
Enums§
- Error
- Errors returned by the client.
- Error
Kind - Stable high-level category for a client error.
- Float
Width - IEEE-754 floating-point widths represented by
Float. - KeyError
- Errors from key conversion or canonical key decoding.
- Mutation
- A mutation whose response was lost after admission.
- SetOutcome
- Result of an unconditional
set. - Sign
- The sign of an arbitrary-precision
Integer. - Typed
Key - The v1 key-only logical model.
- Value
- A logical value in the cross-language model.
- Value
Error - Errors produced by value validation and StructuredValue-CBOR-v1.
- Value
Kind - The logical kind of a
Value.
Traits§
- Value
Codec - Converts a native type to and from the public
Valuemodel.
Type Aliases§
- Result
- Result alias for client operations.