Skip to main content

Crate tsoracle_core

Crate tsoracle_core 

Source
Expand description

§tsoracle-core

Sync algorithm core for the tsoracle timestamp oracle.

No I/O, no async, no tokio. Runtime-neutral, property-testable in microseconds. Anything you need to reason about tsoracle’s timestamp generation lives here — the higher layers (tsoracle-server, tsoracle-client, the consensus drivers) are wiring around this core.

§What’s in the box

  • Allocator — the window allocator. Hands out 46/18-bit-packed Timestamps within a granted window, tracks the leader’s epoch, and exposes the WindowGrant lifecycle used by the server’s leader-watch + fence pipeline.
  • Timestamp — the 64-bit packed representation. PHYSICAL_MS_MAX and LOGICAL_MAX document the bit budget; TimestampError covers the narrow space of invalid encodings.
  • Epoch — the leader-watermark identifier the failover fence checks. Persisted alongside the high water by every ConsensusDriver impl.
  • CoreError — the algorithm-level error type. Server, client, and driver crates wrap it in their own variants.

§Feature flags

  • std (default) — enables std-dependent surface (most of it). Disabling gives a no_std core; the public surface shrinks but the allocator + timestamp math still work.
  • serde — derives Serialize / Deserialize on the public types so they cross wire and storage boundaries cleanly.

§Documentation

Re-exports§

pub use seq::DEFAULT_MAX_SEQ_BATCH_KEYS;
pub use seq::DEFAULT_MAX_SEQ_COUNT;
pub use seq::MAX_SEQ_KEY_LEN;
pub use seq::SeqAllocator;
pub use seq::SeqGrant;
pub use seq::SeqKey;

Modules§

docs
Long-form documentation for tsoracle-core.
seq
Keyed dense sequence types: validated keys, contiguous grants, and the leadership/epoch gate. Pure and synchronous, no I/O — the same discipline as allocator.rs. Unlike Allocator, this holds NO per-key counter state: every counter lives in the durable layer and every block start is assigned there.

Structs§

Allocator
Epoch
LeaseRecord
Durable lease state.
LeaseTable
Pure lease table keyed by lease_id.
PeerEndpoint
A scheme-less host:port advertising the tsoracle service address of a peer node.
PhysicalMs
A u64 physical-millisecond value proven <= PHYSICAL_MS_MAX at construction.
Timestamp
TsoPeer
A known peer node and the network endpoint where its TSO service can be reached for follower-redirect hints.
WindowGrant
A contiguous block of count timestamps starting at (physical_ms, logical_start), all sharing one leadership epoch.

Enums§

AcquireDecision
Outcome of prepare_acquire.
CommitOutcome
The result of a try_commit_window_extension that passed range validation.
CoreError
IgnoreReason
Why a CommitOutcome::Ignored commit left the durable bound unchanged.
LeaseError
PeerEndpointError
Error returned when a string fails the PeerEndpoint contract.
TimestampError

Constants§

DEFAULT_LEASE_TTL_CEILING_MS
Default server-enforced upper bound on requested lease TTLs (300 s).
DEFAULT_LEASE_TTL_FLOOR_MS
Default server-enforced lower bound on requested lease TTLs (5 s).
LOGICAL_MAX
MAX_LEASE_HOLDER_LEN
Maximum accepted length of the opaque holder key, in bytes.
PHYSICAL_MS_MAX

Functions§

validate_lease_request
Validate an AcquireLease request against server TTL policy. Floor and ceiling are server configuration.