Struct ConsensusNode 

pub struct ConsensusNode<C>
where
    C: RaftTypeConfig<NodeId = NodeId, Node = BasicNode, Responder = OneshotResponder<C>>,
{ /* private fields */ }

A high-level wrapper around openraft::Raft.

Provides ergonomic methods for common Raft operations: proposing writes, linearizable reads, cluster membership changes, and metrics observation.

Construct via ConsensusNodeBuilder.

Note: this requires C::Responder = OneshotResponder<C> which is the default when using declare_raft_types!. This enables the blocking client_write, add_learner, and change_membership APIs.

Implementations

impl<C> ConsensusNode<C>

where C: RaftTypeConfig<NodeId = NodeId, Node = BasicNode, Responder = OneshotResponder<C>>,

pub fn from_raft(raft: Raft<C>, node_id: NodeId, address: String) -> Self

Create a ConsensusNode directly from an already-constructed Raft instance.

pub fn node_id(&self) -> NodeId

This node’s ID.

pub fn address(&self) -> &str

This node’s address.

pub fn raft(&self) -> &Raft<C>

Get a reference to the inner Raft instance for advanced usage.

pub fn raft_clone(&self) -> Raft<C>

Get a clone of the inner Raft instance (cheap, Arc-based).

pub async fn propose(&self, request: C::D) -> Result<C::R>

Propose a client write to the Raft cluster.

This node must be the leader. The write is replicated to a quorum before the response is returned.

Errors

Returns ConsensusError::Write if the write fails (e.g., not the leader).

pub async fn ensure_linearizable(&self) -> Result<()>

Ensure linearizable reads by confirming this node is still the leader.

Call this before reading from the state machine to guarantee that the data is not stale. Implements the “leader lease read” pattern.

Errors

Returns ConsensusError::Write if the linearizable check fails.

pub fn is_leader(&self) -> bool

Check if this node is the current leader.

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

Get the current leader’s node ID, if known.

pub fn voter_ids(&self) -> BTreeSet<NodeId>

Returns the set of current voter node IDs.

pub fn voter_count(&self) -> usize

Returns the number of current voters.

pub fn learner_ids(&self) -> BTreeSet<NodeId>

Returns the set of current learner node IDs (non-voters).

pub fn all_member_ids(&self) -> BTreeSet<NodeId>

Returns all member node IDs (voters + learners).

pub async fn bootstrap(&self) -> Result<()>

Bootstrap a new single-node cluster.

This must only be called once, on the first node, when creating a new cluster.

Errors

Returns ConsensusError::Init if bootstrap initialization fails.

pub async fn add_learner( &self, node_id: NodeId, address: String, blocking: bool, ) -> Result<()>

Add a learner to the cluster.

A learner receives log entries but does not vote. Use this to pre-sync a node before promoting it to a voter.

If blocking is true, waits until the learner has caught up with the log.

Errors

Returns ConsensusError::Membership if the learner cannot be added.

pub async fn change_membership( &self, voter_ids: BTreeSet<NodeId>, retain: bool, ) -> Result<()>

Change the cluster membership (promote learners to voters, or remove members).

Pass the complete set of voter node IDs. Nodes not in the set will be demoted or removed.

If retain is true, nodes not in voter_ids are kept as learners rather than removed entirely.

Errors

Returns ConsensusError::Membership if the membership change fails.

pub async fn add_voter(&self, node_id: NodeId, address: String) -> Result<()>

Convenience: add a node as learner then promote it to voter.

This performs the full two-step process:

1. Add as learner (blocking, waits for log sync)
2. Change membership to include the new voter

Errors

Returns a ConsensusError if either the learner addition or membership change fails.

pub fn metrics(&self) -> RaftMetrics<NodeId, BasicNode>

Get current Raft metrics (leader, term, log indices, etc.).

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

Gracefully shut down the Raft node.

Errors

Returns ConsensusError::Fatal if shutdown fails.