Struct RaftControlPlane 

pub struct RaftControlPlane { /* private fields */ }

An openraft-based control plane.

Implementations

impl RaftControlPlane

pub async fn start_single_node( node_id: NodeId, dir: impl AsRef<Path>, ) -> Result<Self, ControlError>

Starts a single-node Raft control plane.

Two redb files live under dir: sm.redb (the state machine) and log.redb (the Raft log) — both the state machine and the log are persisted, so the whole control plane is self-contained and recoverable after a crash.

pub async fn start_cluster_node( node_id: NodeId, dir: impl AsRef<Path>, http_addr: impl Into<String>, ) -> Result<Self, ControlError>

Starts a cluster node: the HTTP network plus its own HTTP server (exposing the Raft RPC and /cluster/join).

• dir: the directory for the redb state machine + log.
• http_addr: the address this node binds and advertises (e.g. 127.0.0.1:7001), i.e. the address that identifies it within the cluster.

pub async fn start_cluster_node_with( node_id: NodeId, dir: impl AsRef<Path>, http_addr: impl Into<String>, tuning: RaftTuning, ) -> Result<Self, ControlError>

Same as start_cluster_node, but with customizable Raft timing (RaftTuning) for high-latency / wide-area clusters.

pub async fn init_cluster( &self, members: BTreeMap<NodeId, String>, ) -> Result<(), ControlError>

Initializes a new cluster (the given {id: addr} becomes the initial voting set; normally called exactly once, on the first core node).

pub async fn add_learner( &self, node_id: NodeId, addr: impl Into<String>, ) -> Result<(), ControlError>

Adds a node as a learner (plan A: a worker starts out as a learner).

pub async fn change_membership( &self, voters: BTreeSet<NodeId>, ) -> Result<(), ControlError>

Changes the voting membership (plan A: a small voting core of 3~5; learners/workers are unaffected).

pub async fn join_cluster( seed_addr: &str, node_id: NodeId, my_addr: &str, ) -> Result<(), ControlError>

Sends a join request from this node to a seed node (adding itself to the cluster as a learner). “Register against any node to join”: seed_addr is the address of any known node in the cluster (it should be the current leader).

pub fn raft(&self) -> &MocraRaft

The underlying openraft handle (membership changes / status queries).

pub fn members(&self) -> Vec<(NodeId, String)>

All members currently configured in the cluster (voters + learners) and their addresses.

Based on the Raft membership configuration (strongly consistent) rather than live liveness probing — good enough for approximate distributed semantics such as “spread rate limits across the member count” and “partition ownership”.

pub fn member_count(&self) -> usize

Total number of cluster members (voters + learners). At least 1.

pub fn voter_count(&self) -> usize

The number of members in the voting core (plan A’s small voting set, typically 3~5).

pub fn current_leader(&self) -> Option<NodeId>

The currently known leader (returns None when unknown / during a leader election).

pub fn status(&self) -> ClusterStatus

A cluster status snapshot (observability / operational monitoring: leader, term, applied position, member count).

pub fn node_id(&self) -> NodeId

This node’s id.

pub fn owned_partitions(&self) -> Vec<u32>

The partitions this node is responsible for under the current membership view (rendezvous assignment, default partition count).

pub fn owns_key(&self, key: &str) -> bool

Whether a given account / session key is handled by this node (rendezvous assignment, default partition count).

No negotiation needed: membership comes from Raft’s strongly consistent view and the hash is deterministic, so every node reaches the same conclusion.

pub async fn acquire_partition( &self, partition: u32, ttl_ms: u64, ) -> Result<Option<u64>, ControlError>

Claims a partition’s ownership lease and returns a monotonic fencing token.

For situations that need a strong guarantee at the moment membership changes: while two nodes’ views briefly disagree, only the node holding the newest token can safely handle the partition; downstream writes from a stale owner can be rejected on their smaller token. Steady-state ownership is decided by owns_key; this method layers a Raft-backed strong guarantee on top of it.

pub async fn release_partition( &self, partition: u32, ) -> Result<(), ControlError>

Releases the partition ownership lease (only if it is still held by this node).

pub async fn shutdown(&self) -> Result<(), ControlError>

Gracefully shuts down this node’s Raft runtime: stops background tasks and releases storage (including the redb file lock).

Call it before crash recovery / restart to make sure the redb database handle is released, so reopening the same directory no longer reports “Database already open”.

pub async fn wait_leader(&self, timeout: Duration) -> Result<(), ControlError>

Waits for this node to become the leader (near-instant on a single node; a multi-node leader election takes one election-timeout window).

Trait Implementations

impl Clone for RaftControlPlane

fn clone(&self) -> RaftControlPlane

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ControlPlane for RaftControlPlane

fn set<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, key: &'life1 [u8], value: &'life2 [u8], ) -> Pin<Box<dyn Future<Output = Result<(), ControlError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

fn get<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 [u8], ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, ControlError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, key: &'life1 [u8], ) -> Pin<Box<dyn Future<Output = Result<(), ControlError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

fn cas<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, key: &'life1 [u8], expect: Option<&'life2 [u8]>, value: &'life3 [u8], ) -> Pin<Box<dyn Future<Output = Result<bool, ControlError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Compare-and-swap; returns whether it succeeded.

fn acquire_lock<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, key: &'life1 str, holder: &'life2 str, ttl_ms: u64, ) -> Pin<Box<dyn Future<Output = Result<Option<u64>, ControlError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Acquire a lock; returns a fencing token on success.

fn renew_lock<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, key: &'life1 str, holder: &'life2 str, ttl_ms: u64, ) -> Pin<Box<dyn Future<Output = Result<bool, ControlError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

fn release_lock<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, key: &'life1 str, holder: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), ControlError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,