Jaft

Overview

Jaft is a minimal, embeddable implementation of the Raft consensus algorithm in Java. It implements the core algorithm and nothing else. Network transport, serialization, and persistent storage are left to the application. That separation keeps the library deterministic, testable, and adaptable to any runtime.

The protocol core is modeled as a pure state machine: feed a Message in, collect the resulting output. Same state, same input, same output. No threads, no I/O, no side effects.

Inspired by etcd/raft, the most widely deployed Raft implementation in production. The protocol logic follows the same proven design, but Jaft is built from the ground up in idiomatic Java.

Features

Core protocol

• Leader election and log replication
• Log compaction via snapshots
• Membership changes via joint consensus. Safely add, remove, or replace nodes in a running cluster
• Leadership transfer. Gracefully hand off leadership to a specific node

Linearizable reads

• Heartbeat-based. The leader confirms it still holds authority by contacting a majority before serving a read
• Lease-based. The leader serves reads locally without a network round-trip, relying on bounded clock drift
• Reads can be served by both the leader and followers

Election modes

• Direct election. A node that times out immediately requests votes from the cluster
• Dual election. A pre-election round checks if the node can win before starting a real election, preventing unnecessary leader disruptions from partitioned nodes

Execution models

• Sequential. Entries are persisted to stable storage before being applied to the state machine
• Pipelined. Persistence and application happen concurrently, so the leader writes to disk in parallel with its followers for higher throughput

Architecture

The system is three layers deep. Each layer adds one concern on top of the one below it.

Raft. The core state machine. Processes messages and buffers output. Elections, replication, membership changes, and reads all happen here.

RaftEngine. Wraps Raft in a process(input) / advance() loop. Tracks state diffs so advance() only returns what has changed.

Node. The application-facing API. A single-threaded event loop that accepts proposals, ticks, and messages from external threads, and publishes work items for the application to consume.

Origin

Jaft was originally built as the consensus layer for Axis, a strongly consistent distributed key-value store. It has since been extracted into a standalone library for independent development and use.

This project is part of a broader effort to learn and engineer production-grade distributed systems from first principles.

References

1. In Search of an Understandable Consensus Algorithmraft.github.io
2. Raft Thesis, Diego Ongarogithub.com
3. etcd/raft: Go reference implementationgithub.com