Crate tsoracle_server 

tsoracle-server

Embeddable gRPC server for the tsoracle timestamp oracle.

Wires four pieces together: the sync window allocator from tsoracle-core, a user-supplied ConsensusDriver (leadership state + durable high-water persistence), the tonic-generated TsoService from tsoracle-proto, and the internal leader-watch pipeline + failover fence that keep timestamps strictly monotonic across leader transitions.

What’s in the box

• Server + ServerBuilder — the embedding entry point. Provide a ConsensusDriver impl, optional TLS config, optional metrics recorder, and serve on a SocketAddr or pre-bound TcpListener.
• BuildError — surfaces invalid configurations at build time (missing driver, conflicting TLS settings, …).
• ServerError — runtime errors from the serving task.
• ServingState — observability snapshot for the leader-watch state machine.

Usage shape

use tsoracle_server::Server;
use tsoracle_driver_file::FileDriver;

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    let driver = FileDriver::open_or_init("./tsoracle-data")?;
    let server = Server::builder()
        .consensus_driver(driver)
        .build()?;

    server.serve("127.0.0.1:50051".parse()?).await?;
    Ok(())
}

See examples/embedded-server for graceful Ctrl-C shutdown, and the HA examples (openraft-standalone, openraft-piggyback, paxos-standalone, paxos-piggyback, paxos-embedded) for swapping the file driver out for a replicated one.

Follower behavior

Followers respond to RPCs with FAILED_PRECONDITION and a tsoracle-leader-hint-bin binary trailer. tsoracle-client consumes the hint to redirect transparently — no extra round trip.

Feature flags

• tls-rustls (default) — TLS via rustls (tonic/tls-aws-lc).
• tls-native — TLS via the platform’s native trust roots (tonic/tls-native-roots). Mutually exclusive with tls-rustls at the consumer level; pick one.
• tracing (default) — emit tracing spans/events through the tracing facade.
• metrics — emit allocator, leader, and request metrics through the metrics facade.
• failpoints — enables fail crate injection for chaos coverage.
• yieldpoints — enables tsoracle-yieldpoint injection sites (async sibling of failpoints; off by default since production carries zero overhead).
• test-fakes / test-support — test-only fixtures for downstream integration suites.

Documentation

• docs/key-subsystems.md — the leader-watch + failover fence pipeline in depth.
• docs/operations.md — deployment guidance, TLS, metrics shape.
• docs/consensus-integration.md — picking and implementing a ConsensusDriver.

Modules

docs

tsoracle guide

Structs

Server

ServerBuilder

WatchGuard

RAII handle to the leader-watch task spawned by Server::into_router.

Enums

BuildError

ServerError

ServingState

Functions

shutdown_signal

Resolves when the process receives an OS request to terminate.