Distributed Key-Value Store

A working implementation of the Raft consensus algorithm, built from scratch in Rust. The core Raft protocol — leader election, log replication, and safety — runs inside a single-threaded async event loop and sits underneath a replicated key–value store accessible over gRPC.

What Raft does

Raft is a protocol for getting a group of machines to agree on a sequence of commands, even when some of them crash or lose connectivity. All three subproblems are tackled separately:

• Leader election — the cluster picks one node to coordinate writes. If the leader goes quiet, a follower steps up and runs an election. Only one leader wins per term, and only nodes whose logs are at least as up-to-date as a majority of the cluster can win.
• Log replication — every write goes through the leader, which appends it to a replicated log and waits for a majority of followers to confirm before committing. Once committed, the entry is guaranteed to survive leadership changes.
• Safety — the election restriction prevents committed entries from being overwritten when a new leader takes over. A candidate must have a log at least as current as a majority of the cluster to be elected.

KV store

On top of Raft sits a concurrent key–value store backed by a DashMap. Clients call Put, Get, and Delete via gRPC. Reads are served locally from whichever replica you hit; writes go through the leader and are replicated before being acknowledged.

Persistence

Every log entry is written to a JSON-line file (the write-ahead log) before a client gets a response. On restart the log is replayed to restore state. When the log grows large, the node takes a snapshot of the state machine and discards older entries.

Transport

The same Raft core can run in two modes:

• gRPC — each node listens on an HTTP/2 socket. RPCs between nodes and client requests share a single .proto definition.
• Simulated (in-memory) — nodes talk through tokio channels with zero network overhead. The integration tests use this to exercise the full consensus protocol deterministically, without races or real latency.

Try it

# In-memory demo — no networking needed
cargo run --bin demo

The demo starts a 3-node cluster, runs a leader election, replicates three key–value pairs, and shows that every replica ends up with the same data.

For a real gRPC cluster, see the README.

See the Raft Consensus notes for the theory behind the algorithm.