Skip to main content

Crate tsoracle_client

Crate tsoracle_client 

Source
Expand description

§tsoracle-client

gRPC client driver for the tsoracle timestamp oracle.

The client never retains pre-fetched timestamps. Every timestamp returned to a caller was allocated by the server after that caller’s request entered the client driver. RPC efficiency comes from request coalescing (multiple concurrent waiters batch into one outgoing GetTs), not pre-fetching. This guarantees that no timestamp is ever handed out by the client unless the server actually issued it — there is no scenario where the client speculatively serves a timestamp that the server hasn’t (or won’t) commit.

§What’s in the box

  • Client — the gRPC client. Methods to issue single timestamps and batches; handles leader discovery, request coalescing, reconnection, and LeaderHint follower-redirect for you.
  • ClientBuilder — configure endpoints, retry policy, TLS, optional metrics recorder.
  • RetryPolicy — declarative retry config (max attempts, backoff parameters). Defaults are tuned for typical raft-like leader transitions.
  • ClientError — error variants surface transport failures, leader-unavailable, and timeout cleanly so callers can distinguish them.

§Usage shape

use tsoracle_client::ClientBuilder;

let client = ClientBuilder::endpoints(vec![
    "http://127.0.0.1:50051".into(),
    "http://127.0.0.1:50052".into(),
    "http://127.0.0.1:50053".into(),
])
.build()
.await?;

let ts = client.get_ts().await?;
println!("got timestamp: {ts:?}");

Pass every cluster endpoint you can — the client cycles through them on transport failure and follows LeaderHint redirects on FAILED_PRECONDITION responses to land on whichever node is currently leader.

§TLS

Configured via ClientBuilder::tls_config(ClientTlsConfig). The endpoint URL scheme determines whether TLS is engaged (http:// = plaintext, https:// = TLS). See docs/client-api-and-usage.md for the scheme rule and worked examples.

§Feature flags

  • tls-rustls (default) — TLS via rustls.
  • tls-native — TLS via the platform’s native trust roots. Pick one.
  • tracing (default) — emit tracing spans/events through the tracing facade.
  • metrics — emit per-call metrics (latency, retry, leader-hint) through the metrics facade.
  • bt — backtrace capture in ClientError variants.

Structs§

Client
ClientBuilder
MaxSafe
The leader’s view of the durable safe-point, returned by Client::get_current_max_safe.
RetryPolicy
Retry and deadline knobs for client RPCs.

Enums§

ClientError

Type Aliases§

BoxError
Boxed error returned by user-supplied connector closures.