RaftNode
The runtime interface for a single Raft cluster member.
Obtain an instance via CoroutineScope.raftNode. The node starts running immediately and remains active until close is called or the owning CoroutineScope is cancelled.
Testing multi-node clusters? Use MultiNodeRaftSim from :kuilt-raft-test — it handles the ceremony (in-process network, per-node seeded RaftConfig.random for symmetry-breaking, child scopes on backgroundScope, bounded await helpers) so you don't hand-roll it per test.
Properties
The index of the highest log entry known to be committed by a quorum.
The lastIncludedIndex of the most recent compaction, or 0 if nothing has been compacted.
The effective cluster membership this node is currently operating under: the ClusterConfig of the latest config entry in its log, committed or not.
The current RaftRole of this node — RaftRole.Leader, RaftRole.Follower, RaftRole.Candidate, or RaftRole.Learner.
The outbound snapshot channel. The consumer publishes its latest durable state-machine snapshot here on its own clock (snapshots.value = Snapshot(appliedIndex, bytes)); raft samples it on its own clock to compact the log prefix and to serve a lagging follower. Conflated — only the newest snapshot matters. Leaving it null disables compaction (the pre-compaction behavior).
Hot Flow of RaftTraceEvents — one event per engine state transition.
Functions
Suspends until this node is observed in the RaftRole.Leader role.
Linearizable read barrier: confirms the read index via RaftNode.readIndex, then suspends until applied reaches it, returning that index. applied is the caller's own monotonic applied-index flow, advanced as it consumes RaftNode.committed.
Aborts an in-flight transferLeadership and re-enables proposal acceptance.
Applies a membership change to this node, retrying while a prior change is still settling.
Shuts down this node: stops the actor command loop, cancels the leader's election/heartbeat/ quorum-check/lease timer coroutines, and fails every in-flight or still-buffered request (propose/readIndex/changeMembership/transferLeadership and the internal commit-cut) so no caller's await() hangs.
Proposes command for replication and suspends until a quorum commits it.
Confirms this leader still holds a voter-quorum at its current term, then returns a read index: a commit index ri such that any state machine that has applied through ri reflects every write committed before this call. The read is linearizable once the caller's apply loop reaches ri. The leader does not write to the log.
Initiates a graceful leadership transfer to target per Raft §3.10, and suspends until the transfer is confirmed or fails. It returns normally only when this node observes a leader-authored message from target — an AppendEntries/InstallSnapshot sent by target at a term above the transfer's start term — proof the target actually won an election. An intervening step-down does not resolve the call (the sender of the first higher-term message identifies neither the winner nor even a campaigner): the transfer stays pending until the confirmation arrives or the one-election-timeout auto-abandon fires. Failure still means only that the transfer could not be confirmed within the window: on a degraded/partitioned network the target may have won without its first leader message reaching this node in time.