🗳️ Raft Consensus Protocol

RaftKV

A distributed key-value store built from scratch in Python with the Raft consensus algorithm for strong consistency across a cluster of nodes.

⭐ View on GitHub 📝 Read the Article
89+
Tests Passing
3,400
Lines of Code
10
API Endpoints
3
Node Cluster

Architecture

Leader-based replication with Raft consensus

Client ──PUT /kv/name──▶ LEADER (Node 1) │ ┌────┴────┐ Log Entry Log Entry Replicate Replicate │ │ ▼ ▼ FOLLOWER FOLLOWER (Node 2) (Node 3) │ │ ACK ─┘ ACK ─┘ │ Majority ✓ │ COMMITTED → Apply to KV Store │ ◀──{"status":"committed"}──

Raft State Machine

Automatic leader election with term-based consistency

🔸 Follower

Receives heartbeats
Replicates log entries

→

🔮 Candidate

Requests votes
Runs for leader

→

👑 Leader

Handles all writes
Sends heartbeats

Features

Everything you need for a distributed KV store

🗳️

Leader Election

Term-based elections with randomized timeouts. Automatic failover when the leader goes down.

📋

Log Replication

Append-only log with conflict detection and resolution. Entries committed when replicated to majority.

🔒

Strong Consistency

Linearizable reads and writes. All operations go through the elected leader.

💾

Write-Ahead Log

Durable persistence with crash recovery. JSONL WAL with atomic state saves.

📸

State Snapshots

Log compaction via periodic snapshots. Prevents unbounded log growth.

🐳

Docker Support

One-command 3-node cluster with docker-compose. Health checks included.

API Endpoints

RESTful HTTP API for clients + internal Raft RPC

Method Endpoint Description
GET /kv/{key} Read a value
PUT /kv/{key} Set a key-value pair
DELETE /kv/{key} Delete a key
GET /kv List all keys and values
GET /cluster/status Full cluster status
GET /cluster/leader Current leader info
GET /health Health check
POST /raft/vote RequestVote RPC (internal)
POST /raft/append AppendEntries RPC (internal)

Quick Start

Get a cluster running in seconds

# Clone and install $ git clone https://github.com/hajirufai/raftkv.git $ cd raftkv && pip install -e . # Start a 3-node cluster with Docker $ docker-compose up --build # Or start nodes manually $ raftkv start --node-id node-1 --port 8001 \ --peers "localhost:8002,localhost:8003" # Use the CLI $ raftkv put name "RaftKV" $ raftkv get name name = RaftKV # Or use the HTTP API $ curl -X PUT http://localhost:8001/kv/name \ -d '{"value": "RaftKV"}'