Struct RaftNode 

pub struct RaftNode<S: LogStorage> { /* private fields */ }

A single Raft group’s state machine.

This is a deterministic, event-driven core. It does NOT own any threads or timers — the caller drives it via tick() and RPC handler methods, and reads output via take_ready().

Implementations

impl<S: LogStorage> RaftNode<S>

pub fn new(config: RaftConfig, storage: S) -> Self

Create a new Raft node. Call restore() before ticking.

If config.starts_as_learner is true, the node boots in the Learner role and will never run an election timeout or become a leader until it is promoted via promote_self_to_voter.

pub fn restore(&mut self) -> Result<()>

Restore state from persistent storage. Must be called before ticking.

pub fn node_id(&self) -> u64

pub fn group_id(&self) -> u64

pub fn role(&self) -> NodeRole

pub fn leader_id(&self) -> u64

pub fn current_term(&self) -> u64

pub fn commit_index(&self) -> u64

pub fn last_applied(&self) -> u64

pub fn election_deadline_override(&mut self, deadline: Instant)

Override election deadline (for testing).

pub fn take_ready(&mut self) -> Ready

Take the pending Ready output. Caller must execute messages, persist hard state, and apply committed entries.

pub fn advance_applied(&mut self, applied_to: u64)

Advance last_applied after the caller has applied entries.

pub fn match_index_for(&self, peer: u64) -> Option<u64>

Query a peer’s match_index from the leader’s replication state. Returns None if this node is not the leader or the peer is unknown.

pub fn log_snapshot_index(&self) -> u64

pub fn log_snapshot_term(&self) -> u64

pub fn log_entries_range(&self, lo: u64, hi: u64) -> Result<&[LogEntry]>

Return committed log entries in the inclusive range [lo, hi].

Clamps hi to commit_index so callers that pass u64::MAX never read uncommitted entries. Returns Err(RaftError::LogCompacted) if lo has already been compacted into a snapshot.

pub fn peers(&self) -> &[u64]

Current voter peer list (excluding self).

pub fn voters(&self) -> &[u64]

Current voter peer list — alias for peers(), clearer at call sites that need to distinguish voters from learners.

pub fn learners(&self) -> &[u64]

Current learner peer list (excluding self).

pub fn observers(&self) -> &[u64]

Current observer peer list tracked by this leader (excluding self).

pub fn is_learner_peer(&self, peer: u64) -> bool

Whether peer is currently tracked as a learner in this group.

pub fn tick(&mut self)

Drive time-based events: election timeout, heartbeat.

pub fn propose(&mut self, data: Vec<u8>) -> Result<u64>

Propose a new entry (leader only). Returns the log index.

impl<S: LogStorage> RaftNode<S>

pub fn add_peer(&mut self, peer: u64)

Add a single voter peer to this group.

No-op if peer is self, already a voter, or currently a learner (use promote_learner to convert a learner into a voter).

pub fn remove_peer(&mut self, peer: u64)

Remove a voter peer from this group.

pub fn add_learner(&mut self, peer: u64)

Add a non-voting learner peer.

Learners receive replicated log entries but do not vote and do not count toward the commit quorum. If this node is currently the leader, the learner is immediately added to LeaderState replication tracking so the next heartbeat ships entries to it.

No-op if peer is self, already a voter, or already a learner.

pub fn remove_learner(&mut self, peer: u64)

Remove a learner peer (e.g., join was rolled back before promotion).

pub fn promote_learner(&mut self, peer: u64) -> bool

Promote an existing learner to a full voter.

Called on the leader after observing the learner has caught up (its match_index >= the group’s commit_index). The LeaderState entry is left in place — it already tracks the peer’s next/match index — but the peer now counts toward the commit quorum.

Returns true if the promotion happened, false if peer was not a learner.

pub fn promote_self_to_voter(&mut self)

Promote this node from learner to voter role.

Used when a follow-up conf change committed the local node’s promotion — the node transitions out of Learner role so its subsequent ticks will run election timeouts like a normal follower.

impl<S: LogStorage> RaftNode<S>

pub fn handle_append_entries( &mut self, req: &AppendEntriesRequest, ) -> AppendEntriesResponse

Handle incoming AppendEntries RPC.

pub fn handle_append_entries_response( &mut self, peer: u64, resp: &AppendEntriesResponse, )

Handle AppendEntries response from a peer (leader only).

For voter peers: update match/next index and attempt commit advancement. For learner peers: update match/next index only (no quorum contribution). For observer peers: update observer state advisorily — no quorum contribution, no commit advancement. Observer acks release backpressure so the leader resumes sending to that observer.

impl<S: LogStorage> RaftNode<S>

pub fn handle_install_snapshot( &mut self, req: &InstallSnapshotRequest, ) -> InstallSnapshotResponse

Handle incoming InstallSnapshot RPC (Raft paper Figure 13).

Called on followers (and learners) that are too far behind for log-based catch-up. The leader sends its snapshot; the receiver replaces its log and state.

impl<S: LogStorage> RaftNode<S>

pub fn handle_request_vote( &mut self, req: &RequestVoteRequest, ) -> RequestVoteResponse

Handle incoming RequestVote RPC.

Learners and observers never grant votes: by definition they are not members of the voting set for this term, and granting a vote could let an incorrect quorum form.

pub fn handle_request_vote_response( &mut self, peer: u64, resp: &RequestVoteResponse, )

Handle RequestVote response (candidate only).