Crate tsoracle_driver_openraft 

tsoracle-driver-openraft

ConsensusDriver implementation for tsoracle backed by openraft via tsoracle-openraft-toolkit.

What it provides

• OpenraftDriver — the tsoracle_consensus::ConsensusDriver impl. Wraps an openraft::Raft handle and the bundled HighWaterStateMachine; bridges them to tsoracle’s leadership_events, load_high_water, and persist_high_water contract.
• OpenraftHighWaterHost — the single trait a host service implements to expose its openraft cluster to the driver. Lets a service share one raft log between its own state and the tsoracle HighWaterCommand.
• StandaloneHost — turnkey OpenraftHighWaterHost for services that don’t already run openraft. Bring your RaftLogStorage and RaftNetworkFactory; this crate provides the state machine and the trait bridge.
• HighWaterStateMachine — the RaftStateMachine impl over an in-memory u64 high-water counter. Snapshots use postcard via a pluggable SnapshotStore (in-memory default, plus an optional RocksdbSnapshotStore behind the rocksdb-snapshot-store feature).
• HighWaterCommand — the typed log entry the driver injects into the host’s raft log.
• The RaftTypeConfig (via tsoracle_openraft_toolkit::declare_raft_types_ext!) — TypeConfig and friends.

Patterns

Standalone services

Greenfield path — wire StandaloneHost::new(raft, state_machine) with an openraft::Raft handle you constructed against tsoracle_openraft_toolkit::RocksdbLogStore plus your own RaftNetworkFactory, then hand the resulting OpenraftDriver to Server::builder().consensus_driver(driver). See examples/openraft-standalone for the full wiring with a tonic peer transport.

Piggyback on an existing openraft

If your service already runs an openraft for its own state, implement OpenraftHighWaterHost directly against that handle. HighWaterCommand becomes a tagged variant of your application command type, decided on the same log alongside your own commands; one snapshot covers both halves. See examples/openraft-piggyback for the worked envelope pattern.

Feature flags

• rocksdb-snapshot-store (default) — enables RocksdbSnapshotStore, keyed in a caller-managed RocksDB column family. Pairs naturally with tsoracle_openraft_toolkit::RocksdbLogStore so one Arc<DB> covers both the raft log and the persisted snapshot. Disable with default-features = false if you want a custom snapshot backend.

Documentation

• docs/consensus-integration.md — the ConsensusDriver trait reference, the “Choosing a driver” comparison (file vs openraft vs paxos), and the canonical worked example for the openraft side.
• tsoracle-openraft-toolkit — the reusable openraft glue this crate is built on (RocksDB log store, declare_raft_types_ext! macro, lifecycle helpers).

Re-exports

pub use capabilities::CapabilitySource;

pub use capabilities::FormatActivationError;

pub use capabilities::NodeCapabilities;

pub use capabilities::all_members_can_read;

pub use capabilities::gather_with;

pub use capabilities::report_with;

pub use driver::OpenraftDriver;

pub use host::OpenraftHighWaterHost;

pub use log_codec::OpenraftLogCodec;

pub use log_entry::DenseAdvance;

pub use log_entry::HighWaterCommand;

pub use log_entry::SetFormatVersionPayload;

pub use snapshot_store::RocksdbSnapshotStore;

pub use snapshot_store::InMemorySnapshotStore;

pub use snapshot_store::SnapshotStore;

pub use standalone::StandaloneHost;

pub use state_machine::HighWaterStateMachine;

pub use state_machine::HighWaterStateMachineSnapshot;

pub use type_config::ApplyOutcome;

pub use type_config::HighWaterApplied;

pub use type_config::OpenraftPeer;

pub use type_config::ServiceEndpoint;

pub use type_config::TypeConfig;

Modules

capabilities

Format-migration capability reporting and the leader-side all-members activation gate’s pure logic.

driver

ConsensusDriver impl on top of any OpenraftHighWaterHost.

host

Host abstraction the openraft-backed ConsensusDriver builds on.

log_codec

Concrete LogStoreCodec provider for this driver’s TypeConfig.

log_entry

Log entries replicated by the openraft cluster.

observability

Format-migration observability: the metric-name constants and the emit helpers the activation path and the state-machine apply arm call. Every emission is gated behind the crate’s metrics feature so the metrics dependency stays opt-in (matching tsoracle-server). The helpers are deliberately the single place each tsoracle.schema.* name is written, so the apply arm, the gate, the boot path, and the metrics test cannot drift apart on a name. When the feature is off, every helper compiles to a no-op with an identical signature.

snapshot_store

Persistence backend for HighWaterStateMachine snapshots.

standalone

Bundled host: owns its own raft cluster and the HighWaterStateMachine.

state_machine

RaftStateMachine for the high-water counter with pluggable snapshot persistence.

type_config

RaftTypeConfig for the openraft-backed driver.

Structs

AdvancePayload

Re-export of the cross-backend advance payload that HighWaterCommand::Advance wraps, so consumers can build commands without depending on tsoracle-consensus. The payload of an “advance the high-water to at least at_least” command, shared by every consensus backend’s replicated log entry.

TsoPeer

A known peer node and the network endpoint where its TSO service can be reached for follower-redirect hints.

Constants

DEFAULT_DENSE_CARDINALITY_CAP

The default immutable genesis cardinality cap for dense sequence keys. Every cluster member must be constructed with the same value; the cap is stored in replicated snapshots so replay/restore reproduces the same accept/reject decisions (spec §6.2). Operators that need a larger or smaller key namespace configure this at SM construction time.