Distributed systems often struggle to maintain a consistent 'happens-before' relationship because per-host wall clocks are not monotonic enough for reliable event ordering. Tsoracle solves this by acting as a timestamp oracle (TSO), a service that hands out strictly increasing integer IDs to synchronize events across multiple machines, a mechanism utilized by major databases like Spanner and CockroachDB.

A code listing showing the Rust implementation of the Tsoracle library.
Example Rust code demonstrating the Tsoracle library's interface for requesting timestamps and sequences.tsoracle.rs

This code snippet provides a concrete example of how the library is used in a Rust application as described in the introduction.

Ordering vs. Contiguity

While many systems require ordered events, some specific use cases—such as invoice numbers, ledger lines, or surrogate keys—require contiguous, gapless sequences where no numbers are skipped. Tsoracle distinguishes between these needs by offering `get_ts()` for ordered timestamps and `get_seq()` for dense, gapless runs.

A timestamp only needs to be strictly greater than the previous one, meaning some values can be skipped. In contrast, a sequence must be contiguous (e.g., ..., 41, 42, 43, ...). Tsoracle manages these via a durable counter per named key, ensuring that no IDs are reused or skipped even across system crashes or failovers.

Consensus and Batch Allocation

To maintain high availability and fault tolerance, Tsoracle uses a consensus layer to replicate its state. The system is designed so that the leader advances a high-water mark, fsyncs that change to disk, and replicates it through a consensus protocol (like Raft) before the range is released to the client.

To optimize performance, the system allocates IDs in batches of size N. Clients receive a block of IDs and hand them out locally, allowing for millions of IDs per second on commodity hardware while minimizing the number of network round-trips to the oracle.

A diagram illustrating how one round-trip allocates a batch of N IDs from the Tsoracle oracle.
The Tsoracle system optimizes performance by allocating IDs in batches, allowing clients to handle millions of IDs per second with minimal network overhead.tsoracle.rs

This figure illustrates the batch allocation mechanism described in the text, showing how the system minimizes network round-trips.

Idempotency and Failure Handling

The requirement for gapless sequences introduces a specific technical trade-off regarding idempotency. Because a gapless advance cannot be 'un-spent,' an ambiguous network failure during a request makes it impossible to know if the counter was successfully advanced.

Tsoracle handles this by surfacing a `SeqUncertain` error rather than silently retrying the request. This forces the caller to reconcile the state, preventing the accidental creation of 'holes' in a sequence that must remain perfectly contiguous.