Crate raftbare

raftbare is a minimal but feature-complete, I/O-free implementation of the Raft distributed consensus algorithm.

Node is the main struct that represents a Raft node. It offers methods for creating a cluster, proposing commands, updating cluster configurations, handling incoming messages, snapshotting, and more.

Node itself does not execute I/O operations. Instead, it generates Actions that represent pending I/O operations. How to execute these actions is up to the crate user.

Except for a few optimizations, raftbare is a very straightforward (yet efficient) implementation of the Raft algorithm. This crate focuses on the core part of the algorithm. So, offering various convenience features (which are not described in the Raft paper) is left to the crate user.

The following example outlines a basic usage flow of this crate:

use raftbare::{Action, Node, NodeId};

// Start a node.
let mut node = Node::start(NodeId::new(0));

// Create a three nodes cluster.
let commit_position = node.create_cluster(&[NodeId::new(0), NodeId::new(1), NodeId::new(2)]);

// Execute actions requested by the node until the cluster creation is complete.
while node.get_commit_status(commit_position).is_in_progress() {
    for action in node.actions_mut() {
        // How to execute actions is up to the crate user.
        match action {
           Action::SetElectionTimeout => { /* ... */ },
           Action::SaveCurrentTerm => { /* ... */ },
           Action::SaveVotedFor => { /* ... */ },
           Action::BroadcastMessage(_) => { /* ... */ },
           Action::AppendLogEntries(_) => { /* ... */ },
           Action::SendMessage(_, _) => { /* ... */ },
           Action::InstallSnapshot(_) => { /* ... */ },
        }
    }

    // If the election timeout is expired, handle it.
    if is_election_timeout_expired() {
        node.handle_election_timeout();
    }

    // If a message is received, handle it.
    while let Some(message) = try_receive_message() {
        node.handle_message(message);
    }
}

// Propose a user-defined command.
let commit_position = node.propose_command();

// Execute actions as before.

Structs

Actions

Actions represents a prioritized set of Actions that are issued by a Node but have not yet been executed.

ClusterConfig

Cluster configuration (membership).

Log

In-memory representation of a Node local log.

LogEntries

Log entries.

LogIndex

Log index.

LogPosition

Log position (Term and LogIndex).

MessageHeader

Common header for all messages.

MessageSeqNo

Message sequence number.

Node

Raft node.

NodeId

Node identifier (u64).

Term

Term.

Enums

Action

Action represents the I/O operations for Node that crate users need to execute.

CommitStatus

Commit status of a log entry.

LogEntry

Log entry.

Message

Message for RPC.

Role

Role of a Raft node (follower, candidate, or leader).