kuilt-raft/us.tractat.kuilt.raft

Package-level declarations

Types

ClientId

@Serializable

@JvmInline

value class ClientId(val value: String)

Opaque, comparable client identity for Raft §8 client-serial dedup.

ClientIdCollisionException

class ClientIdCollisionException(message: String) : IllegalStateException

Thrown by a node using a caller-supplied durable ClientId when it observes another live writer committing under that same identity (Raft §8 collision). Indicates an operational error — two processes were handed one durable id. Fail loud; do not retry under the same id.

ClientIdentity

sealed interface ClientIdentity

How a RaftNode obtains its Raft §8 client identity for proposal dedup.

ClientSessionTable

class ClientSessionTable

The authoritative client-serial dedup table for a consumer's state machine (Raft §8).

ClusterConfig

@Serializable

data class ClusterConfig(val voters: Set<NodeId>, val learners: Set<NodeId> = emptySet())

Describes the membership of a Raft cluster.

Committed

sealed interface Committed

One ordered instruction in the committed stream delivered to a consumer's state machine.

ConfigPayload

@Serializable

data class ConfigPayload(val old: ClusterConfig?, val new: ClusterConfig)

The membership payload carried by a config log entry (§6 joint consensus).

CorruptDurableStateException

class CorruptDurableStateException(message: String) : IllegalStateException

Thrown during a node's start-up restore when the RaftStorage it was given returns durable state that violates the storage contract — currently, a persisted term outside the plausible range (issue #1855).

DedupKey

@Serializable

data class DedupKey(val clientId: ClientId, val requestId: Long)

A proposal's end-to-end dedup identity: a clientId plus a per-client monotonic requestId.

DenyReason

enum DenyReason : Enum<DenyReason>

Why a candidate's RequestVote or PreVote was denied by the responding node.

InMemoryRaftStorage

class InMemoryRaftStorage : RaftStorage

An in-memory RaftStorage implementation.

LeaderForTerm

data class LeaderForTerm(val term: Long, val leaderId: NodeId)

The node §5.2 Election Safety established as the leader of term — a fact about that term, which is why the two travel together and are meaningless apart.

LeadershipLostException

class LeadershipLostException(message: String = "leadership lost while proposal was in flight") : Exception

Thrown by RaftNode.propose when this node loses leadership while waiting for the proposal to be committed by a quorum.

LeadershipTransferAbandonReason

enum LeadershipTransferAbandonReason : Enum<LeadershipTransferAbandonReason>

Why a leadership transfer was abandoned without completing.

LeadershipTransferException

class LeadershipTransferException(message: String) : Exception

Thrown by RaftNode.transferLeadership when the transfer could not complete.

LogEntry

@Serializable

data class LogEntry(val index: Long, val term: Long, val command: ByteArray, val isNoOp: Boolean = false, val config: ConfigPayload? = null, val dedupKey: DedupKey? = null)

One entry in the replicated Raft log.

MembershipChangeInProgressException

class MembershipChangeInProgressException(message: String = "a membership change is already in progress — wait for it to commit before starting another") : Exception

Thrown by RaftNode.changeMembership when a membership change is already in progress (a config entry is uncommitted).

NodeId

@Serializable

@JvmInline

value class NodeId(val value: String)

A stable, unique identifier for a Raft cluster member.

NotLeaderException

class NotLeaderException(message: String = "not the current leader") : Exception

Thrown by RaftNode.propose when this node is not the current leader.

RaftConfig

data class RaftConfig(val electionTimeoutMin: Duration = 150.milliseconds, val electionTimeoutMax: Duration = 300.milliseconds, val heartbeatInterval: Duration = 50.milliseconds, val strictTestGuard: Boolean = false, val expectVirtualTime: Boolean = false, val slowProposeThreshold: Duration = 100.milliseconds, val snapshotChunkCeiling: Int = 16 * 1024, val snapshotTotalCeiling: Int = 64 * 1024 * 1024, val maxTermJump: Long, val random: Random = Random.Default)

Tuning parameters for a Raft node's timing behaviour.

RaftEnvelope

data class RaftEnvelope(val from: NodeId, val bytes: ByteArray)

A raw message from another cluster member, as received by the transport.

RaftMessageType

enum RaftMessageType : Enum<RaftMessageType>

The Raft wire vocabulary, as a value a trace consumer can hold and compare.

RaftMetric

sealed interface RaftMetric

A structured metric event emitted by a RaftNode at key state-machine transitions.

RaftNode

interface RaftNode

The runtime interface for a single Raft cluster member.

RaftRole

sealed interface RaftRole

The role a node holds at a given instant in Raft's state machine.

RaftStorage

interface RaftStorage

Durable state that a Raft node must persist to survive restarts.

RaftTraceEvent

sealed interface RaftTraceEvent

One engine state transition, emitted on RaftNode.trace.

RaftTransport

interface RaftTransport

The messaging seam between the Raft engine and any underlying network layer.

RefusalGate

enum RefusalGate : Enum<RefusalGate>

Which guard refused an inbound frame — the gate of RaftTraceEvent.FrameRefused.

SeamRaftTransport

class SeamRaftTransport(seam: Seam) : RaftTransport

Adapts a kuilt-core Seam to the RaftTransport interface.

Snapshot

class Snapshot(val throughIndex: Long, val state: ByteArray)

A state-machine snapshot. Opaque to kuilt-raft — it never deserializes state; only the consumer can collapse many log entries into compact state. The same payload flows both directions: the consumer publishes it via RaftNode.snapshots (outbound), and a lagging node receives it wrapped in Committed.Install (inbound).

SnapshotMeta

data class SnapshotMeta(val lastIncludedIndex: Long, val lastIncludedTerm: Long, val config: ConfigPayload? = null)

Identifies the log position a snapshot covers: everything with index <= lastIncludedIndex.

StepDownReason

enum StepDownReason : Enum<StepDownReason>

Why a node stepped down from RaftRole.Leader or RaftRole.Candidate to RaftRole.Follower.

StoredSnapshot

class StoredSnapshot(val meta: SnapshotMeta, val state: ByteArray)

A persisted snapshot: its meta plus the opaque application state bytes.

Functions

asCommitted

fun LogEntry.asCommitted(): Committed

The Committed instruction a committed LogEntry surfaces as: an application entry becomes Committed.Entry; raft's own bookkeeping — the §5.4.2 election no-op (LogEntry.isNoOp) and §6 membership-change entries (LogEntry.config) — becomes a payload-free Committed.Internal.

awaitRead

suspend fun RaftNode.awaitRead(applied: StateFlow<Long>): Long

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.

changeMembershipWithRetry

suspend fun RaftNode.changeMembershipWithRetry(newConfig: ClusterConfig, maxAttempts: Int = 20, retryDelay: Duration = 200.milliseconds)

Applies a membership change to this node, retrying while a prior change is still settling.

raftNode

fun CoroutineScope.raftNode(clusterConfig: ClusterConfig, transport: RaftTransport, storage: RaftStorage, raftConfig: RaftConfig = RaftConfig(), identity: ClientIdentity = ClientIdentity.Auto, onMetric: (RaftMetric) -> Unit? = null): RaftNode

Creates and starts a RaftNode whose lifetime is tied to this CoroutineScope.