kuilt-raft-test/us.tractat.kuilt.raft.test/FakeRaftNode

FakeRaftNode

class FakeRaftNode(val selfId: NodeId = NodeId("self"), initialRole: RaftRole = RaftRole.Follower, initialLeader: NodeId? = null, initialCommitIndex: Long = 0, val clientId: ClientId = ClientId.auto(selfId, Random(selfId.value.hashCode()))) : RaftNode

A test double for RaftNode with driver helpers for driving role transitions, injecting committed entries, emitting trace events, and inspecting outgoing proposals.

Defaults make FakeRaftNode() ready to use in one line:

val node = FakeRaftNode()
node.setRole(RaftRole.Leader)
val entry = node.propose("set x=1".encodeToByteArray())
val committed = node.committed.first() as Committed.Entry
// committed.entry.command == "set x=1".encodeToByteArray()

Stream semantics — a deliberate divergence from the real RaftNode. The real RaftNode documents committed and trace as hot, no-replay flows (late collectors miss history). For test ergonomics this double backs them with unbounded-buffering channels instead, so pushCommitted(...) followed by committed.first() works without racing a collector. Two consequences a consumer should not encode as RaftNode guarantees:

entries/events emitted before collection are buffered and replayed here, whereas the real RaftNode would drop them;
close completes committed/trace (channel close), whereas the real engine cancels its backing scope without completing the flows.

Constructors

FakeRaftNode

constructor(selfId: NodeId = NodeId("self"), initialRole: RaftRole = RaftRole.Follower, initialLeader: NodeId? = null, initialCommitIndex: Long = 0, clientId: ClientId = ClientId.auto(selfId, Random(selfId.value.hashCode())))

Properties

clientId

val clientId: ClientId

This node's Raft §8 dedup identity, stamped onto the LogEntry returned by propose. Defaults to a deterministic auto id derived from selfId (distinct per node id, stable per instance); pass a fixed ClientId to assert exact dedup keys.

closed

val closed: Boolean

Whether close has been called.

commitIndex

open override val commitIndex: StateFlow<Long>

committed

open override val committed: Flow<Committed>

compactionFloor

open override val compactionFloor: StateFlow<Long>

leader

open override val leader: StateFlow<NodeId?>

proposals

val proposals: List<ByteArray>

All commands passed to propose, in call order.

proposeBehavior

var proposeBehavior: suspend (ByteArray) -> LogEntry

Behavior of propose. Defaults to contract-faithful: throws NotLeaderException unless role is RaftRole.Leader, otherwise appends the command to committed and returns the resulting LogEntry.

role

open override val role: StateFlow<RaftRole>

selfId

val selfId: NodeId

Stable identifier for this node — exposed as a convenience field, not on RaftNode.

snapshots

open override val snapshots: MutableStateFlow<Snapshot?>

Snapshot publish channel — present to satisfy RaftNode. This double runs no real compaction loop, so setting it has no functional effect; drive setCompactionFloor to simulate a floor and pushInstall to inject a Committed.Install on the committed stream.

trace

open override val trace: Flow<RaftTraceEvent>

Functions

awaitLeadership

open suspend fun awaitLeadership()

cancelTransfer

open fun cancelTransfer()

changeMembership

open suspend fun changeMembership(target: ClusterConfig): ClusterConfig

open suspend override fun close()

committedFrom

open override fun committedFrom(fromIndex: Long): Flow<Committed>

emitTrace

suspend fun emitTrace(event: RaftTraceEvent)

Push event onto trace.

propose

open suspend override fun propose(command: ByteArray): LogEntry

open suspend override fun propose(command: ByteArray, requestId: Long): LogEntry

pushCommitted

suspend fun pushCommitted(command: ByteArray): LogEntry

Convenience: create a LogEntry at the next auto-incremented index (term=1) with command, push it onto committed, and return it.

suspend fun pushCommitted(entry: LogEntry): LogEntry

Push entry onto committed and advance commitIndex to entry's index.

pushInstall

suspend fun pushInstall(snapshot: Snapshot)

Push a Committed.Install onto committed, advancing compactionFloor and commitIndex to snapshot's throughIndex — the test-double analogue of the engine accepting an InstallSnapshot.

readIndex

open suspend fun readIndex(): Long

setCommitIndex

fun setCommitIndex(index: Long)

Set commitIndex to index. Does not push any entry onto committed.

setCompactionFloor

fun setCompactionFloor(index: Long)

Set compactionFloor to index without emitting a Committed.Install.

setLeader

fun setLeader(newLeader: NodeId?)

Update leader to newLeader.

setRole

fun setRole(newRole: RaftRole)

Transition role to newRole.

transferLeadership

open suspend fun transferLeadership(target: NodeId)