ruvector/crates/ruvector-raft

Ruvector Raft

Raft consensus implementation for Ruvector distributed metadata coordination.

ruvector-raft provides a production-ready Raft consensus implementation for coordinating distributed Ruvector deployments. Ensures strong consistency for cluster metadata, configuration, and leader election. Part of the Ruvector ecosystem.

Why Ruvector Raft?

• Strong Consistency: Linearizable reads and writes
• Leader Election: Automatic failover on leader failure
• Log Replication: Durable, replicated transaction log
• Membership Changes: Dynamic cluster reconfiguration
• Snapshot Support: Log compaction via snapshots

Features

Core Capabilities

• Raft Consensus: Full Raft protocol implementation
• Leader Election: Randomized timeouts, pre-vote protocol
• Log Replication: Pipelined append entries
• Commit Management: Majority-based commit tracking
• State Machine: Generic state machine interface

Advanced Features

• Pre-Vote Protocol: Prevents disruption during network partitions
• Leadership Transfer: Graceful leader handoff
• Read Index: Linearizable reads without log entry
• Learner Nodes: Non-voting members for scaling reads
• Batch Commits: Coalesce multiple entries per commit

Installation

Add ruvector-raft to your Cargo.toml:

[dependencies]
ruvector-raft = "0.1.1"

Quick Start

Create Raft Node

use ruvector_raft::{RaftNode, RaftConfig, StateMachine};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure Raft node
    let config = RaftConfig {
        node_id: 1,
        peers: vec![2, 3],  // Other node IDs
        election_timeout_min: Duration::from_millis(150),
        election_timeout_max: Duration::from_millis(300),
        heartbeat_interval: Duration::from_millis(50),
        ..Default::default()
    };

    // Create state machine
    let state_machine = MyStateMachine::new();

    // Create and start Raft node
    let node = RaftNode::new(config, state_machine).await?;
    node.start().await?;

    // Wait for leader election
    node.wait_for_leader().await?;

    Ok(())
}

Implement State Machine

use ruvector_raft::{StateMachine, Entry, Snapshot};

struct MyStateMachine {
    data: HashMap<String, String>,
}

impl StateMachine for MyStateMachine {
    type Command = MyCommand;
    type Response = MyResponse;

    fn apply(&mut self, entry: &Entry<Self::Command>) -> Self::Response {
        match &entry.command {
            MyCommand::Set { key, value } => {
                self.data.insert(key.clone(), value.clone());
                MyResponse::Ok
            }
            MyCommand::Get { key } => {
                MyResponse::Value(self.data.get(key).cloned())
            }
            MyCommand::Delete { key } => {
                self.data.remove(key);
                MyResponse::Ok
            }
        }
    }

    fn snapshot(&self) -> Snapshot {
        Snapshot {
            data: bincode::serialize(&self.data).unwrap(),
            last_index: self.last_applied,
            last_term: self.last_term,
        }
    }

    fn restore(&mut self, snapshot: &Snapshot) {
        self.data = bincode::deserialize(&snapshot.data).unwrap();
    }
}

Propose Commands

// Propose a command (only succeeds on leader)
let response = node.propose(MyCommand::Set {
    key: "foo".to_string(),
    value: "bar".to_string(),
}).await?;

// Read with linearizable consistency
let response = node.read_index(MyCommand::Get {
    key: "foo".to_string(),
}).await?;

// Check leadership
if node.is_leader().await {
    println!("This node is the leader");
}

API Overview

Core Types

// Raft configuration
pub struct RaftConfig {
    pub node_id: NodeId,
    pub peers: Vec<NodeId>,
    pub election_timeout_min: Duration,
    pub election_timeout_max: Duration,
    pub heartbeat_interval: Duration,
    pub max_entries_per_append: usize,
    pub snapshot_threshold: u64,
}

// Log entry
pub struct Entry<C> {
    pub index: u64,
    pub term: u64,
    pub command: C,
}

// Snapshot
pub struct Snapshot {
    pub data: Vec<u8>,
    pub last_index: u64,
    pub last_term: u64,
}

// Node state
pub enum NodeState {
    Follower,
    Candidate,
    Leader,
    Learner,
}

Node Operations

impl<S: StateMachine> RaftNode<S> {
    pub async fn new(config: RaftConfig, state_machine: S) -> Result<Self>;
    pub async fn start(&self) -> Result<()>;
    pub async fn stop(&self) -> Result<()>;

    // Leadership
    pub async fn is_leader(&self) -> bool;
    pub async fn leader_id(&self) -> Option<NodeId>;
    pub async fn wait_for_leader(&self) -> Result<NodeId>;

    // Commands
    pub async fn propose(&self, command: S::Command) -> Result<S::Response>;
    pub async fn read_index(&self, command: S::Command) -> Result<S::Response>;

    // Cluster management
    pub async fn add_node(&self, node_id: NodeId) -> Result<()>;
    pub async fn remove_node(&self, node_id: NodeId) -> Result<()>;
    pub async fn transfer_leadership(&self, target: NodeId) -> Result<()>;
}

Architecture

┌────────────────────────────────────────────────────────┐
│                     Raft Cluster                        │
│                                                        │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐        │
│   │  Node 1  │    │  Node 2  │    │  Node 3  │        │
│   │ (Leader) │───▶│(Follower)│    │(Follower)│        │
│   │          │    │          │    │          │        │
│   │ Log:     │    │ Log:     │    │ Log:     │        │
│   │ [1,2,3]  │───▶│ [1,2,3]  │    │ [1,2,3]  │        │
│   └──────────┘    └──────────┘    └──────────┘        │
│         │                               ▲              │
│         └───────────────────────────────┘              │
│                  AppendEntries RPC                     │
└────────────────────────────────────────────────────────┘

Related Crates

• ruvector-core - Core vector database engine
• ruvector-cluster - Clustering and sharding
• ruvector-replication - Data replication

Documentation

• Main README - Complete project overview
• API Documentation - Full API reference
• GitHub Repository - Source code

License

MIT License - see LICENSE for details.

---

Part of Ruvector - Built by rUv

Documentation | Crates.io | GitHub