# waymaker-client (Rust)

Official Rust client for [waymaker](https://git.awesomike.com/dev/waymaker).

```toml
[dependencies]
waymaker-client = { git = "https://git.awesomike.com/pub/waymaker-client", tag = "v0.1.27" }
# (the crate lives in the rust/ subdir; cargo resolves it automatically)
```

Proto stubs are generated from `../proto` at build time via `build.rs` — no
dependency on the waymaker server workspace.

## Surfaces

- `lock` — read/write locks, leader election, TTL leases. The `Lock` handle
  keeps a background task that **transparently re-binds** its event stream
  across a primary bounce (reusing the `request_id`) and exposes live state:
  `lock.fence_token()`, `lock.watch()` (a `watch::Receiver<LockState>`),
  `lock.is_lost()`. Re-read the fence before every fenced side effect.
- `stream` — JetStream-lite publish + pull/push consumers.
- `kv` — Put/Get/Create/Update(CAS)/Delete/Keys/History/Watch.
- `cache` — Redis-shape Hash / Set / Queue (collections).
- `probabilistic` — Bloom / HLL / CMS / TopK / t-digest.
- `object` — chunked object Put/Get.

Raw generated stubs are available under `server` / `streams_server` /
`kv_server` / `collections_server` / `sketches_server` / `cache_server`.

## Leader election

```rust
use std::time::Duration;
use waymaker_client::{Client, lock};

let client = Client::connect("http://127.0.0.1:8818").await?;
let lock = client.acquire_lock("leader:reports", lock::Config {
    max_wait: Duration::ZERO,            // try-acquire
    lease_ttl: Duration::from_secs(30),
    scope: lock::Scope::Quorum,          // Raft-replicated fence
    ..Default::default()
}).await?;
let _renewal = lock.spawn_renewal(Duration::from_secs(15));

// Re-read the fence before each fenced write; stop if leadership is lost.
let mut state = lock.watch();
loop {
    if lock.is_lost() { break; }
    do_fenced_write(lock.fence_token()).await?;
    state.changed().await.ok();
}
```