latzero 0.1.0

Async Rust client for latzero-server
Documentation

LatZero Rust Client

Async Rust client for latzero-server. It implements the same newline-delimited JSON TCP protocol as the Python server-mode LatZero client.

The Python client's standalone shared-memory implementation is intentionally out of scope. Rust and Python applications interoperate through latzero-server.

Features

  • Tokio-based TCP transport with hello, pool join/switch/leave, request IDs, timeouts, and typed server errors
  • Concurrent request correlation, including two-stage ack and app_result calls
  • JSON buffers, TTL, persistence, listing, client-derived batches and scans
  • Buffer subscriptions and presence/update event streams
  • Targeted and broadcast events, app RPC, third-party response routing
  • Process registration, direct/short-name calls, broadcast, discovery, worker metrics, and server-directed concurrency scaling
  • Namespaced buffers and event emitters
  • Cancellation-safe frame writer and automatic socket cleanup when the final client handle is dropped

Install

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

Start the server first:

latzero-server --headless

Buffers

use std::time::Duration;
use latzero::Client;
use serde_json::{Value, json};

#[tokio::main]
async fn main() -> latzero::Result<()> {
    let client = Client::builder("latzero://rust-api", "app")
        .auth_token("optional-pool-token")
        .connect()
        .await?;

    client.set("config", &json!({"enabled": true})).await?;
    client
        .set_with_options("session", &json!({"user": 42}), Some(Duration::from_secs(60)), false)
        .await?;

    let config: Option<Value> = client.get("config").await?;
    println!("{config:?}");

    let users = client.namespace("users");
    users.set("42", &json!({"name": "Ada"})).await?;

    client.disconnect().await
}

get returns Option<T>, so a missing buffer is distinct from a present JSON null when T can represent null, such as serde_json::Value.

Events And RPC

Handlers receive a JSON object and may return any serializable value.

use latzero::Client;
use serde_json::{Map, Value, json};

#[tokio::main]
async fn main() -> latzero::Result<()> {
    let worker = Client::connect("latzero://worker-1", "app").await?;
    let process = worker
        .on_event("add", |data: Map<String, Value>| async move {
            let value = data["x"].as_i64().unwrap() + data["y"].as_i64().unwrap();
            Ok::<_, String>(value)
        })
        .await;

    let caller = Client::connect("latzero://caller-1", "app").await?;
    let result: i64 = caller
        .call_app("worker-1", "add", &json!({"x": 3, "y": 4}))
        .await?;
    assert_eq!(result, 7);

    caller.disconnect().await?;
    worker.disconnect().await
}

Use Client::events() for unsolicited presence_update, buffer_update, emitted events, third-party app results, scaling commands, disconnects, and unknown forward-compatible protocol messages. CallOutcome::Routed preserves the request ID when response_to sends a result to another client.

Processes

use latzero::{Client, ProcessOptions};
use serde_json::{Map, Value, json};

#[tokio::main]
async fn main() -> latzero::Result<()> {
    let worker = Client::connect("latzero://worker-1", "app").await?;
    worker
        .register_process(
            "multiply",
            ProcessOptions::default(),
            |data: Map<String, Value>| async move {
                Ok::<_, String>(data["x"].as_i64().unwrap() * data["y"].as_i64().unwrap())
            },
        )
        .await?;

    let caller = Client::connect("latzero://caller-1", "app").await?;
    let value: i64 = caller
        .call_process(&process.process_id, &json!({"x": 6, "y": 7}))
        .await?;
    assert_eq!(value, 42);
    Ok(())
}

Calling the canonical process_id works with all released server revisions; current servers additionally accept a short process name and select a worker using round-robin routing.

WorkerKind values are sent as protocol metadata for compatibility. Rust handlers execute as asynchronous Tokio tasks; min_workers and max_workers control local concurrent handler execution. Selecting Process does not move a Rust closure into an operating-system child process.

Compatibility

The client covers every message currently dispatched by latzero-server:

hello, join_pool, switch_pool, leave_pool,
set_buffer, get_buffer, delete_buffer, list_buffers, list_clients,
subscribe_buffer, unsubscribe_buffer,
emit_event, call_app, app_result,
register_process, unregister_process, call_process, broadcast_process,
list_processes, worker_metrics

The server protocol currently has no version negotiation, TLS, reconnection, or resumable sessions. A closed connection fails pending requests; construct a new Client to reconnect and re-register handlers/processes.

Verification

cargo fmt --all -- --check
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
cargo doc --no-deps