# eBay/NuRaft: a C++ Raft core that adds the protocols a real cluster needs

> NuRaft is an Apache-2.0 licensed C++ implementation of the Raft consensus core, derived from the lightweight cornerstone library and extended with features eBay needed in production, including pre-vote, leadership expiration, read-only members, asynchronous replication, TLS and a custom commit policy. It gives you the consensus algorithm and expects you to supply the log store and the state machine.

**eBay/NuRaft** — C++ implementation of Raft core logic as a replication library

- Repository: https://github.com/eBay/NuRaft
- Stars: 1,208 · Forks: 297
- Language: C++
- License: Apache-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/ebay-nuraft

## cornerstone, then the features eBay needed

NuRaft is a C++ implementation of the core Raft logic, presented as a replication library. Its lineage is worth stating plainly, because it explains the shape of the code. It is derived from the cornerstone project, a very lightweight C++ implementation with minimum dependencies originally written by Andy Chen, and it was developed by Jung-Sang Ahn, who is named as the author and developer alongside the eBay copyright.

The distinction the project draws is between the original Raft paper and what production demanded. The features that came from cornerstone are the core algorithm itself, log replication and compaction, leader election, snapshots, and dynamic membership and configuration change, plus group commit and pipelined write, and support for user-defined log store and state machine.

The features added in this project are the interesting part, and the project states plainly that they are not described in the original paper but were required for real world use cases in eBay, and that the authors believe they are useful outside eBay as well.

The additions are things a cluster operator runs into quickly. A pre-vote protocol, so a node that has been partitioned does not disrupt the cluster when it rejoins. Leadership expiration, so a leader that cannot reach a quorum stops serving. Priority-based semi-deterministic leader election. A read-only member, the learner role, so a joining node can catch up without voting. Object-based logical snapshot. Custom or separate quorum size for commit and for leader election. Asynchronous replication. SSL and TLS support. Parallel log appending. A custom commit policy. And a streaming mode.

Each of these has its own document in the `docs/` directory, linked from the feature list, which is the right place to start for anyone evaluating whether the library covers their failure modes.

## The build is cmake, openssl and asio

The build instructions are explicit about the platform differences, and the prerequisites are installed first. On Ubuntu:

```sh
$ sudo apt-get install cmake openssl libssl-dev libz-dev
```

On macOS the equivalent is `brew install cmake` and `brew install openssl`, and on Windows the instruction is to download and install CMake, with an important caveat attached: SSL is currently not supported for Windows.

The network layer comes from Asio, which is fetched as a git submodule:

```sh
$ git submodule update --init
```

There are alternatives for that step, which is a good sign for a project that expects different environments. On Linux and macOS there is a `prepare.sh` script, and on Windows the instruction is to clone Asio manually, pinned to a specific tag:

```sh
C:\NuRaft> git clone https://github.com/chriskohlhoff/asio -b asio-1-24-0
```

On Linux and macOS the library, the tests and the examples are then built with a standard CMake sequence:

```sh
$ mkdir build
$ cd build
build$ cmake ../
build$ make
```

and the unit tests are run with `./runtests.sh` from the same directory. The Windows path uses NMake with MSVC 2019, and the instructions note that you may need to run the `vcvars` script first, which is the usual friction point for building a C++ project with Microsoft toolchains.

## A Conan recipe for projects that already use Conan

There is a second build method aimed at a specific situation, and it is the one to look at if your project already builds with Conan.

The project has a `conanfile.py` that can be used to build locally and export the package to the Conan cache or repository, or to use it in editable mode locally. The commands are short:

```sh
conan build .
conan build . -s build_type=Debug
```

The first builds the Release configuration, the second an alternative configuration supported by CMake, and build options can be controlled from the command line, with the example given being `conan build . -o build_tests=True`.

The distinction here is worth making explicitly, because it is a decision rather than a detail. The CMake path produces a static library you link into your own build system, which is what most integrations do. The Conan path produces a package that can be versioned, exported and consumed by other projects in the same Conan graph, which is what a large organisation with many services sharing a build cache wants. A library like this one is exactly the kind of component that a shared cache handles well, since the version and the flags become part of the dependency graph rather than something each service re-derives.

## The examples directory is the real usage documentation

The README defers usage to a document and a directory, and both are worth an engineer's time.

`docs/how_to_use.md` is the usage document, and the `examples/` directory holds the runnable code. The listing gives a good sense of the shape: `quick_start.cxx` for the smallest possible case, `echo/` and `calculator/` as worked applications, `in_memory_log_store.cxx` and `in_memory_state_mgr.hxx` as the pluggable pieces, plus a `logger.cc`, a `logger_wrapper.hxx` and a `backtrace.h`.

The in-memory log store and state manager are the two files that explain the architecture. Raft itself is the algorithm that decides which entries are committed, and everything around it is an interface: where the log lives, and what to do with an entry once it is committed. NuRaft gives you the algorithm, and expects you to write both.

That is the fundamental trade of the library, and it is a good one for the intended user. A team that wants consensus to be a solved problem plugs in its own durable log, usually backed by a real database or a write ahead log, and its own state machine, and inherits the hard part of the algorithm, including the failure modes that the extra features exist to handle.

A benchmark directory sits alongside, at `tests/bench`, with quick benchmark results documented in `docs/bench_results.md`. The repository also carries a `.codecov.yml`, a `.clang-format` and a `NuRaftConfig.cmake.in`, which is the usual set of files for a C++ library that is consumed through CMake.

## Where NuRaft is the wrong choice

The first wrong case is a team expecting a database. NuRaft is the consensus layer. It gives you an ordered, replicated log and agreement on which entries are committed, and it does not shard, it does not provide transactions across keys, and it does not give you a query language. Every one of those is still your problem, and the architecture work of deciding how your data is partitioned and how queries cross partitions happens on top of the library rather than inside it.

The second wrong case is a language mismatch. This is a C++ library, and the integration surface is a C++ API with headers, a log store implementation and a state machine implementation. A team whose services are written in Go, Rust or Java is looking at a native component with a network or process boundary in front of it, which may well be a better architecture, but it is not a library you drop in.

The third is a platform outside the supported set. Linux and macOS are described as extensively tested and widely used, while Windows is built with MSVC 2019 and has limited testing, and SSL is not supported for Windows at all. Running a consensus implementation on a platform the project does not test properly is a decision you should make deliberately, if at all.

The fourth is a system where the extra protocols are not wanted. Pre-vote, leadership expiration and a separate quorum size are all deviations from the paper, and they are the right defaults for a production cluster but the wrong ones if you are implementing the paper to study it, or if your membership changes in a way those designs do not anticipate.

## Third party code, licences and the release line

The library embeds a handful of third party components, and the README credits each one with its licence, which is a detail that matters for a component whose source you may be shipping.

The base is cornerstone from datatechnology, originally Apache 2.0. The CRC32 implementation comes from stbrumme, under the original ZLib licence, and is the kind of dependency that gets vendored rather than linked. The logging and test tooling comes from greensky00, with simple_logger, testsuite and latency-collector, all originally MIT licensed, and the coverage conversion script from eriwen under Apache 2.0. The CMake modules are from bilke under the BSD licence. The project itself is Apache 2.0, copyright 2017-present eBay Inc.

On releases, the line is active but not fast. v2.0.0 was published on 2022-11-10, v2.1.0 on 2023-01-18 and v3.0.0 on 2025-03-31, and the last push to the repository was on 2026-10-12. A major version jump in 2025 is worth a careful read of the change notes before you upgrade, since a consensus library's behaviour around elections, quorum and commit policy is the kind of thing that should be reviewed rather than absorbed.

The support contact is named directly, Jung-Sang Ahn, and contributions are invited through issues and pull requests, with the project's own framing that bugs, edge cases and new feature suggestions are all welcome.

## Conclusion

Adopt NuRaft when you need a replicated log and want Raft's semantics without writing the algorithm, and when your C++ codebase can host it, since the design deliberately keeps the log store and the state machine pluggable. Do not adopt it expecting a distributed database, since NuRaft is the consensus layer only, and it neither shards data nor provides transactions across keys, so you still have to decide how state is partitioned. Verify first that the platform you target is one of the supported ones, since Linux and OSX are described as extensively tested while Windows is built with MSVC 2019 and only limited testing, and that SSL is not supported on Windows at all, then read the protocol documents for pre-vote and leadership expiration before you run it in production.

## FAQ

### What is NuRaft and what is its relationship to cornerstone?

NuRaft is a C++ implementation of the Raft core logic as a replication library, derived from the lightweight cornerstone project originally written by Andy Chen. The core algorithm, log replication and compaction, leader election, snapshots and dynamic membership came from cornerstone, and the features added in this project were required for eBay's real world use cases.

### Which Raft features does NuRaft add beyond the original paper?

The added features include the pre-vote protocol, leadership expiration, priority-based semi-deterministic leader election, a read-only member for learners, object-based logical snapshot, custom or separate quorum size for commit and leader election, asynchronous replication, SSL and TLS support, parallel log appending, a custom commit policy and a streaming mode. Each has its own document in the `docs/` directory.

### How do I build NuRaft on Linux or macOS?

Install cmake and openssl, fetch Asio with `git submodule update --init` or by running `./prepare.sh`, then create a build directory, run `cmake ../` and `make`. The unit tests are run with `./runtests.sh` from the build directory.

### Does NuRaft support Windows and TLS?

Windows is supported through MSVC 2019 with NMake, but the project describes it as having limited testing, and states that SSL is currently not supported for Windows. Linux and macOS are described as extensively tested and widely used.

### What do I have to implement to use NuRaft?

The consensus core is provided, but the log store and the state machine are pluggable and yours to write. The examples directory shows this with `in_memory_log_store.cxx` and `in_memory_state_mgr.hxx` as reference implementations, alongside `quick_start.cxx` and the `echo/` and `calculator/` examples.

## Sources

- [eBay/NuRaft on GitHub](https://github.com/eBay/NuRaft)
- [Issues](https://github.com/eBay/NuRaft/issues)
- [License: Apache-2.0](https://github.com/eBay/NuRaft/blob/master/LICENSE)
- [README](https://github.com/eBay/NuRaft/blob/master/README.md)
- [Releases](https://github.com/eBay/NuRaft/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ebay-nuraft