tsoracle documentation

The long-form prose guide to tsoracle — strictly monotonic timestamps over gRPC.

This directory is the deep dive covering everything from getting started through the allocator's monotonicity proof, consensus integration patterns, deployment topologies, and per-example walkthroughs. Browsable on GitHub and indexed by DeepWiki.

For the reference documentation of the external interface — the gRPC wire surface, the CLI, and the list of published Rust crates — see Interface Reference. The full Rust API reference is generated on docs.rs/tsoracle-server (and the other crates linked from the Interface Reference). A docs.rs-rendered subset of the most critical chapters (algorithm, ConsensusDriver contract, operations) lives inside the published crates — see CONTRIBUTING.md for the policy on which tree owns what.

Chapters

• Overview — what tsoracle is, what it is not, where to go next.
• Getting Started — vocabulary, install & run, calling from Rust, embedding, migration.
• Architecture Deep Dive — crate layering, the clock contract, the epoch type, timestamp packing.
• The Allocator — allocation model, prepare-commit split, monotonic persistence, monotonicity proof.
• Key Subsystems — leader-watch pipeline, failover fence, leader-hint trailer, steady-state window extension.
• Client API and Usage — Client type, GetTs/GetTsBatch, leader discovery, configuration.
• The Client Driver — coalescing vs. pre-fetching, external monotonicity across clients, auto-batching dynamics, flush_interval correctly understood.
• Consensus Integration — the ConsensusDriver trait, per-method recipes, worked openraft example, single-leader requirement.
• Driver Comparison — capability matrix and per-feature deep dive across file, openraft, and paxos; operator decision guidance and contributor-facing internals.
• Operations — sizing window_ahead/failover_advance, monitoring hooks, deployment topologies, client retry behavior.
• Deployment — container images (fat vs lean, multi-arch), Helm chart quick start, values reference, TLS/mTLS setup, and topology notes (file vs openraft vs paxos).
• Testing and Examples — walkthroughs of the runnable example crates plus the workspace testing strategy.
• Failpoint Testing — fault-injection points for crash-recovery, fence, and service-path tests; the feature-gating model and contributor guidance.
• Yield-point Testing — async counterpart of failpoints, for tests that need to park production code in an async path without blocking a tokio worker.
• Interface Reference — reference documentation for the project's external interfaces: the tsoracle.v1.TsoService gRPC wire surface, the tsoracle.admin.v1.MembershipAdmin admin surface, the tsoracle CLI, and the published Rust crates.

Where to start

• New to TSOs or to tsoracle — Overview, then Getting Started.
• Reading the code — pair each crate's lib.rs //! header with the corresponding section of Architecture Deep Dive.
• Plugging tsoracle into your own consensus — Consensus Integration.
• Running it in production — Operations.
• Looking up a specific RPC, CLI flag, or published crate — Interface Reference.