ember-client

async Rust client for ember, a high-performance distributed cache.

features

• typed API for all common commands (strings, keys, lists, hashes, sets, sorted sets, server, pub/sub, slowlog)
• pipelining — batch commands into a single round-trip
• optional TLS via the tls cargo feature (enabled by default)
• optional vector commands via the vector cargo feature
• binary-safe values: inputs accept &str, String, Vec<u8>, or bytes::Bytes
• outputs return Bytes — zero-copy where possible
• Subscriber type for pub/sub with typed message frames

quick start

[dependencies]
ember-client = "0.1"
tokio = { version = "1", features = ["full"] }

use ember_client::Client;

#[tokio::main]
async fn main() -> Result<(), ember_client::ClientError> {
    let mut client = Client::connect("127.0.0.1", 6379).await?;

    client.set("greeting", "hello").await?;
    if let Some(value) = client.get("greeting").await? {
        println!("{}", String::from_utf8_lossy(&value));
    }

    Ok(())
}

pipelining

Send multiple commands in a single network round-trip:

use ember_client::{Client, Pipeline};

#[tokio::main]
async fn main() -> Result<(), ember_client::ClientError> {
    let mut client = Client::connect("127.0.0.1", 6379).await?;

    let frames = client.execute_pipeline(
        Pipeline::new()
            .set("a", "1")
            .set("b", "2")
            .get("a")
            .get("b")
            .incr("counter")
            .zadd("scores", &[(9.5, "alice"), (8.0, "bob")])
            .hset("user:1", &[("name", "alice"), ("age", "30")]),
    ).await?;

    println!("{} responses", frames.len());
    Ok(())
}

commands

strings

keys

lists

hashes

sets

sorted sets

bitmaps

server

slowlog

pub/sub

raw

client.send(&["COMMAND", "arg1", "arg2"]).await?;

pub/sub

subscribe and psubscribe consume the Client, returning a dedicated Subscriber handle. This prevents accidentally mixing pub/sub and regular commands on the same connection.

use ember_client::{Client, Message};

let client = Client::connect("127.0.0.1", 6379).await?;
let mut sub = client.subscribe(&["events", "alerts"]).await?;

loop {
    match sub.recv().await? {
        Some(Message { channel, payload, .. }) => {
            println!("[{}] {}", channel, String::from_utf8_lossy(&payload));
        }
        None => break,
    }
}

Pattern subscriptions work the same way via psubscribe. The Message type also carries the pattern field when using pattern subscriptions.

vector commands

Requires the vector cargo feature:

ember-client = { version = "0.1", features = ["vector"] }

use ember_client::Client;

let mut client = Client::connect("127.0.0.1", 6379).await?;

// index vectors
client.vadd("embeddings", "doc-1", &[0.1, 0.9, 0.2]).await?;
client.vadd("embeddings", "doc-2", &[0.8, 0.1, 0.5]).await?;

// similarity search
let results = client.vsim("embeddings", &[0.1, 0.8, 0.3], 5).await?;
for r in results {
    println!("{}: {:.4}", r.element, r.score);
}

public types

ScanPage

pub struct ScanPage {
    pub cursor: u64,  // 0 means iteration is complete
    pub keys: Vec<Bytes>,
}

SlowlogEntry

pub struct SlowlogEntry {
    pub id: i64,
    pub timestamp: i64,
    pub duration_us: i64,
    pub args: Vec<Bytes>,
}

Message

pub struct Message {
    pub kind: String,    // "message" or "pmessage"
    pub pattern: Option<Bytes>,
    pub channel: Bytes,
    pub payload: Bytes,
}

SimResult

pub struct SimResult {
    pub element: String,
    pub score: f32,
}

pipeline builder

All pipeline methods mirror the async API. The builder is chainable and zero-alloc until execute_pipeline is called.

errors

ClientError covers six cases:

tls

ember-client = { version = "0.1", features = ["tls"] }

use ember_client::{Client, tls::TlsClientConfig};

let tls = TlsClientConfig::default(); // uses native root certs
let mut client = Client::connect_tls("my-ember-host", 6380, &tls).await?;