Distributed systems / Personal project
RaftKVKeeping committed data consistent through failure.
A three-node key-value store implementing Raft consensus in Java, with snapshot recovery and a checksummed C11 write-ahead log connected through JNI.
01 / The problem
Why I built it
An apparently healthy leader can be isolated from its peers. A restarted follower can carry a stale suffix. A successful response is only meaningful if the implementation respects the commit and durability boundaries through those failures.
02 / My contribution
What I engineered
I implemented the consensus state machine rather than wrapping a Raft library: persisted elections, replication, majority commits, quorum-checked reads, log repair, and snapshots. I also built the C11/JNI storage boundary and the deterministic fault and history-checking tools.
03 / Interactive demonstration
See the behavior, not just the claim.
Step through an illustrative three-node failure sequence. This is an educational state visualization, not a running Java cluster.
- Term
- 4
- Committed
- 7
- Term
- 4
- Committed
- 7
- Term
- 4
- Committed
- 7
STEP 1 / 5
A healthy majority
Node A is leader in term 4. All nodes have applied committed index 7.
A fixed educational sequence, not the Java consensus engine or a benchmark. For actual execution, use the linked live-cluster test and protocol trace viewer in the repository. No failover time is measured here.
04 / Architecture
Follow the data.
- 01HTTP client
- 02Leader + fresh quorum
- 03Replicated Raft log
- 04Majority commit
- 05Java state + C11/JNI WAL
Quorum-checked reads instead of trusting a cached leader
A leader serves a successful read only after committing an entry in its current term and reaching a fresh majority. An isolated old leader therefore cannot silently serve a successful stale read.
Matched-prefix acknowledgements
A follower acknowledges only the prefix matched by the current request, not an unrelated suffix it already holds. Conflict-term/index hints let the leader repair mismatches without walking backward one entry at a time.
Separate consensus and state-machine persistence
Checksummed Raft state preserves terms, votes, snapshots, and retained logs. Committed commands also cross JNI into a C WAL that fsyncs before updating its in-memory index. Consensus state remains authoritative for recovery.
Inspectability before throughput
One mutex serializes protocol state, with network calls outside it and response role/term rechecks. Synchronous peer replication and full state-image persistence keep the implementation explicit, but limit throughput.
05 / Verification
Results you can inspect.
The deterministic campaign exercises partitions, follower crashes and restarts, isolated old leaders, replacement elections, duplicates, healing, and final convergence. A separate Linux live-process test asserts native storage, checks a concurrent history, kills the leader, and verifies restart/catch-up.
Measurement context
The recorded 186 ms failover is from one WSL2 live-cluster run on September 3, 2026. Its 60/60 operations completed and passed the scoped register-history checker. It is not a median, p95, SLA, or result across all 1,000 scenarios.
The fault harness simulates network faults; the live test terminates real JVM processes. Tests provide evidence for the safety invariants, not a formal proof of Raft correctness or production readiness.
- Recorded results & live-run context
- Safety invariants & storage design
- Fault testing methodology
- Native WAL implementation
- Limitations & roadmap
Evidence pinned to repository revision 54dbc2d18d52. Recorded results are from the linked project evidence, not new benchmark runs for this website.
06 / Engineering boundaries
What I would harden next
Static membership; sequential replication; no client-operation deduplication; no TLS or authorization; no multi-hour soak or disk-fault campaign. This is an educational systems implementation, not a production database.
07 / Next iteration
Where it goes from here
The most valuable next steps are client retry deduplication, segmented/group-committed persistence, concurrent replication, and broader fault testing—not adding unrelated API features.