Crate shardd 

shardd

Official Rust client for shardd, a globally distributed credit ledger. The client probes the three prod edge regions on first use, sticks to the closest healthy one, and fails over to the next-best on transient errors — all transparently.

Quickstart

use shardd::{Client, CreateEventOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("SHARDD_API_KEY")?;
    let client = Client::new(api_key)?;

    // Credit $5 to user 42 in the `my-app` bucket.
    let result = client
        .create_event("my-app", "user:42", 500, Default::default())
        .await?;
    println!("event {} → balance {}", result.event.event_id, result.balance);

    // Retrieve it.
    let balances = client.get_balances("my-app").await?;
    for row in balances.accounts {
        println!("  {} = {}", row.account, row.balance);
    }
    Ok(())
}

Failover

The client defaults to the three prod regions (use1, euc1, ape1). On construction it does nothing; on the first request it parallel-probes /gateway/health on all three, picks the lowest- latency healthy one, and sticks with it. If that edge returns 503/ 504/timeouts, the client fails over once to the next-best candidate, re-using the same idempotency_nonce so a partially-landed first attempt collapses into a single event on the server.

See Client::builder to override edges, timeout, or the HTTP client.

Structs

AccountBalance

AccountDetail

Collapsed snapshot for a single (bucket, account), returned by Client::get_account.

AckInfo

Balances

Client

Thread-safe handle to the shardd API. Cloning is cheap (Arc bump).

ClientBuilder

Builder for a Client. Use this to override the default prod bootstrap list, plug in a custom reqwest::Client, or change the request timeout.

CreateEventOptions

Optional knobs for Client::create_event. Leave everything unset for the common case of “charge or credit an account”.

CreateEventResult

Result of a successful Client::create_event.

EdgeHealth

Health snapshot returned by Client::health.

EdgeInfo

One row of Client::edges. Matches the gateway’s /gateway/edges response shape.

Event

A ledger event — the atomic unit of state in shardd. Every event is immutable and globally identified by (bucket, origin_node_id, origin_epoch, origin_seq).

EventList

Reservation

Handle returned by Client::reserve. Pass reservation_id to Client::settle for one-shot capture or Client::release to cancel.

Enums

ShardError

Everything a shardd SDK call can fail with.