Struct Client 

pub struct Client { /* private fields */ }

Implementations

impl Client

pub async fn connect(endpoints: Vec<String>) -> Result<Self, ClientError>

pub fn cached_leader(&self) -> Option<String>

The endpoint the client currently believes is the leader, or None if no leader has been observed yet or the cached entry has aged past the configured leader_ttl.

Read-only diagnostic surface for ops dashboards and integration tests asserting that a client has converged to the expected leader. It reflects the cache as last updated by a completed RPC — it neither triggers nor waits on any network round-trip, and the TTL check is lazy (an expired entry reads as None).

pub async fn get_ts(&self) -> Result<Timestamp, ClientError>

pub async fn get_ts_batch( &self, count: u32, ) -> Result<Vec<Timestamp>, ClientError>

pub async fn get_seq( &self, key: &str, count: u32, ) -> Result<SeqBlock, ClientError>

Request a contiguous block of count dense ordinals for the given sequence key.

Non-idempotent: if this call returns ClientError::SeqUncertain it means a commit may or may not have occurred on the server — do NOT silently retry, as that would risk spending a second block. The caller must resolve the ambiguity (e.g. by reading back the current counter with a coordinator-level read) before re-issuing.

All other errors are pre-commit-certain (the server rejected the request before any durable advance) and are safe to retry.

The client only pre-rejects universally-invalid inputs — an empty/oversized key and a zero count (a block always covers at least one ordinal). The upper bound on count is the server’s configured ServerBuilder::max_seq_count, which is deployment-specific, so the client does not second-guess it: an over-cap count is forwarded and the server rejects it with INVALID_ARGUMENT (surfaced as ClientError::Rpc). This keeps a client built against one cap correct against a server configured with another.

pub async fn get_seq_batch( &self, entries: &[(&str, u32)], ) -> Result<Vec<SeqBlock>, ClientError>

Atomically request contiguous dense blocks for several DISTINCT keys in one round-trip. Returns one SeqBlock per entry, in request order.

Non-idempotent (whole batch): on ClientError::SeqUncertain the entire batch may or may not have committed — do NOT retry; reconcile first (the atomic server contract means it is all-or-nothing, so there is never a partial mix to untangle). All other errors are pre-commit-certain.

Client-side pre-checks reject only universally-invalid input: an empty batch, a duplicate key, an empty/oversized key, or a zero count. The per-entry count cap and the batch-size cap are server-side and are forwarded for the server to reject, so a client built against one configuration stays correct against a server with another.

pub async fn get_current_max_safe(&self) -> Result<MaxSafe, ClientError>

Read the leader’s current safe-point in physical-millisecond units.

Targets the cached leader if known, otherwise the first configured endpoint. Followers return MaxSafe::max_safe_physical_ms == 0 rather than erroring, matching the proto contract; pollers needing freshness should target the leader endpoint.

Single-shot by design — the proto contract is “followers return 0” rather than NOT_LEADER, so there is no hint to chase and no worklist to drain; a caller polling for freshness retries the next tick rather than the next endpoint. The one (connect, RPC) pair is bounded by RetryPolicy::per_attempt_deadline (shared across both phases via PairBudget, exactly like one get_ts attempt), and a transport-class failure evicts the cached channel so a half-open / black-holing connection is dropped before the next poll lands on it.

pub async fn acquire_lease( &self, holder: &[u8], holder_epoch: u64, ttl: Duration, ) -> Result<Lease, ClientError>

Acquire a stamping lease for an opaque holder group.

Single-attempt control-plane call: callers own retry and re-route policy. Retrying an ambiguous acquire is safe for the same (holder, holder_epoch) because the server treats that pair idempotently while the lease is live.

pub async fn renew_lease( &self, lease_id: u64, ) -> Result<LeaseRenewal, ClientError>

Renew a live lease, re-arming its acquire-time TTL.

Single-attempt control-plane call; callers own retry and re-route policy.

pub async fn release_lease(&self, lease_id: u64) -> Result<(), ClientError>

Release a lease. The server treats unknown or already-released leases as success, making graceful surrender idempotent.

pub async fn get_safe_frontier(&self) -> Result<SafeFrontier, ClientError>

Read the lease-aware safe frontier in physical-millisecond units.