class Raft::Node

Overview

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

Included Modules

Defined in:

raft/node.cr
raft/node/role.cr

Constructors

Instance Method Summary

Constructor Detail

def self.new(id : String, peers : Array(String), state_machine : StateMachine, transport : Transport, log : Raft::Log, config : Config = Config.new) #

[View source]

Instance Method Detail

def add_peer(peer_id : String) : Nil #

Adds a new 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.


[View source]
def id : String #

This node's unique identifier within the cluster.


[View source]
def leader : String | Nil #

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


[View source]
def leader_id : String | Nil #

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


[View source]
def metrics : Metrics #

Observable counters and state. See Metrics.


[View source]
def 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.


[View source]
def 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.


[View source]
def remove_peer(peer_id : String) : Nil #

Removes a peer 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.


[View source]
def role : Role #

The current role of this node.


[View source]
def snapshot : Nil #

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.


[View source]
def start : Nil #

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

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


[View source]
def stop : Nil #

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


[View source]