Microraft

MicroRaft is a feature-complete and stable open-source implementation of the Raft consensus algorithm in Java. It is a single lightweight JAR file of a few hundred KBs of size. It can be used for building fault tolerant and strongly-consistent (CP) data, metadata and coordination services. A few examples of possible use-cases are building distributed file systems, key-value stores, distributed lock services, etc.

MicroRaft works on top of a minimalistic and modular design. It is a single lightweight JAR with a few hundred KBs of size and only logging dependency. It contains an isolated implementation of the Raft consensus algorithm, and a set of accompanying abstractions to run the algorithm in a multi-threaded and distributed environment. These abstractions are defined to isolate the core algorithm from the concerns of persistence, thread-safety, serialization, networking, and actual state machine logic. Users are required to provide their own implementations of these abstractions to build their custom CP distributed systems with MicroRaft.

Please note that MicroRaft is not a high-level solution like a distributed key-value store or a distributed lock service. It is a core library that offers a set of abstractions and functionalities to help you build such high-level systems.

Features

MicroRaft implements the leader election, log replication, log compaction (snapshotting), and cluster membership changes components of the Raft consensus algorithm. Additionally, it offers a rich set of optimizations and enhancements:

• Adaptive batching during log replication,
• Back pressure to prevent OOMEs on Raft leader and followers,
• Parallel snapshot transfer from Raft leader and followers,
• Pre-voting and leader stickiness (Section 4.2.3 of the Raft dissertation and Four modifications of the Raft consensus algorithm),
• Auto-demotion of Raft leader on loss of quorum heartbeats (Section 6.2 of the Raft dissertation),
• Linearizable quorum reads without appending log entries (Section 6.4 of the Raft dissertation),
• Lease-based local queries on Raft leader (Section 6.4.1 of the Raft dissertation),
• Monotonic local queries on Raft followers (Section 6.4.1 of the Raft dissertation),
• Parallel disk writes on Raft leader and followers (Section 10.2.1 of the Raft dissertation),
• Leadership transfer (Section 3.10 of the Raft dissertation).
• Improved majority quorums

Get started

Run a single tutorial test that starts a local 3-node Raft group, elects a leader, and commits operations to an atomic register:

./gradlew :microraft-tutorial:test \
  --tests io.microraft.tutorial.OperationCommitTest \
  -Pmicroraft.javaVersion=21

microraft.javaVersion defaults to 11. If Java 11 is already installed on your machine, you can omit that property. If you only have a newer local JDK, set -Pmicroraft.javaVersion=<your-installed-version> to match it. If you want a quick smoke test for leader election only, run:

./gradlew :microraft-tutorial:test \
  --tests io.microraft.tutorial.LeaderElectionTest \
  -Pmicroraft.javaVersion=21

What you will see:

• a 3-node local Raft group bootstrapping in-process,
• a leader elected for the group,
• replicated operations committed with increasing commit indexes,
• the final atomic register value observed from the leader.

Next steps:

• Read the runnable tutorial entry point in microraft-tutorial/README.md.
• Continue with the setup guide.
• Build an atomic register by following the tutorial.

Why MicroRaft?

Use MicroRaft when you want to embed consensus into your own Java service without adopting an entire distributed data platform.

MicroRaft is a good fit when you need:

• a lightweight embeddable Raft library,
• explicit control over persistence, transport, serialization, and threading,
• production-oriented Raft features such as membership changes, snapshotting, quorum-aware reads, and leadership transfer.

MicroRaft is not the right fit when you need:

• a turnkey distributed database,
• a managed coordination service,
• a system that hides Raft integration details completely.

For a fuller positioning guide, see Why MicroRaft?.

Use MicroRaft in your project

Add MicroRaft to your dependency list:

Gradle (version catalog)

[versions]
microraft = "0.9"

[libraries]
microraft = { module = "io.microraft:microraft", version.ref = "microraft" }

Gradle (kotlinscript)

implementation("io.microraft:microraft:0.9")

Maven

<dependency>
    <groupId>io.microraft</groupId>
    <artifactId>microraft</artifactId>
    <version>0.9</version>
</dependency>

Build from source

Pull the latest code with gh repo clone MicroRaft/MicroRaft and build with cd MicroRaft && ./gradlew build.

Source code layout

microraft module contains the source code of MicroRaft along with its unit and integration test suite.

microraft-hocon and microraft-yaml modules are utility libraries for parsing HOCON and YAML files to start Raft nodes.

microraft-metrics module contains the integration with the Micrometer library for publishing MicroRaft metrics to external systems.

afloatdb contains a simple in-memory distributed KV store project built with MicroRaft and gRPC.

site-src contains the source files of microraft.io.

Contribute to MicroRaft

You can see this guide for contributing to MicroRaft.

License

MicroRaft is available under the Apache 2 License.

MicroRaft originates from the Raft implementation that powers Hazelcast IMDG's CP Subsystem module. You can see the announcement for details.