class

Raft::Node

Inherits Raft::Node::Leader < Raft::Node::Candidate < Raft::Node::Follower < Reference < Object

A single Raft consensus node.

Each node runs a single event-loop fiber that processes RPC messages, client requests, and timer events from a central inbox channel. State transitions (Follower → Candidate → Leader) happen on this fiber, eliminating the need for locks in the consensus core.

node = Raft::Node.new(
  id: "node-1",
  peers: ["node-2", "node-3"],
  state_machine: my_app,
  transport: Raft::Transport::InMemory.new("node-1"),
  log: Raft::Log.new,
)
node.start
result = node.propose("command".to_slice)
node.stop

Constructors

new(id : String, peers : Array(String), state_machine : StateMachine, transport : Transport, log : Raft::Log, config : Config = Config.new, learners : Array(String) = [] of String)

Creates a new Raft node.

id — unique identifier for this node within the cluster (e.g. "node-1")
peers — IDs of the other voting nodes (not including self)
state_machine — application logic; see StateMachine
transport — network layer; use Transport::InMemory for tests, Transport::TCP for production
log — replicated log storage; use Log::InMemory for tests, Log::File for production
config — tuning parameters; sensible defaults are provided (see Config)
learners — IDs of non-voting observer nodes (optional, default empty)

Restores state from a prior snapshot and replays any uncommitted log entries so the node is immediately consistent on restart.

Instance methods

add_learner(peer_id : String) : Nil

Adds a new non-voting learner to the cluster.

The learner receives log replication and snapshots but does not participate in elections or quorum. Use promote_learner to convert to a voting member once caught up.

Raises Error::ConfigChange if the peer already exists. Raises Error::NotLeader if this node is not the leader.

add_peer(peer_id : String) : Nil

Adds a new voting peer to the cluster.

Appends a Config log entry with the updated peer list. The change is applied immediately on the leader and replicated to followers. Must be called on the leader node.

Raises Error::ConfigChange if the peer already exists. Raises Error::NotLeader if this node is not the leader.

id

This node's unique identifier within the cluster.

leader

Returns the ID of the current leader, or nil if unknown. Alias for #leader_id.

leader_id

The ID of the node believed to be the current leader, or nil if unknown.

learners

Returns the list of learner (non-voting) node IDs.

metrics

Observable counters and state. See Metrics.

peers

Returns all peer IDs (voters + learners).

promote_learner(peer_id : String) : Nil

Promotes a learner to a voting member.

Raises Error::ConfigChange if the peer is not a learner. Raises Error::NotLeader if this node is not the leader.

propose(command : Bytes) : Bytes

Proposes a command to the cluster for replication.

Blocks the calling fiber until the command is committed by a majority and applied to the state machine. Returns the state machine's response.

Raises Error::NotLeader if this node is not the current leader. Raises Error::Shutdown if the node has been stopped.

read(command : Bytes) : Bytes

Performs a linearizable read by confirming leadership via a quorum round, then applying the read command directly to the state machine.

Raises Error::NotLeader if this node is not the current leader. Raises Error::Shutdown if the node has been stopped.

remove_peer(peer_id : String) : Nil

Removes a peer (voter or learner) from the cluster.

Appends a Config log entry with the updated peer list. Must be called on the leader node.

Raises Error::ConfigChange if the peer does not exist. Raises Error::NotLeader if this node is not the leader.

role

The current role of this node.

snapshot

Takes a snapshot of the current state machine and compacts the log.

Called automatically when the number of applied entries since the last snapshot exceeds Config#snapshot_threshold. Can also be called manually.

start

Starts the node's event loop, transport, and election timer.

Returns immediately — the consensus logic runs in background fibers. Call #stop to shut down.

stop

Gracefully shuts down the node, stopping replicators and the transport. Takes a final snapshot before stopping for fast recovery on restart.

Nested types