willemt/raft
FreeC implementation of the Raft Consensus protocol, BSD licensed
FreeFree tier
About willemt/raft
An open-source C implementation of the Raft consensus protocol, BSD licensed. The library provides the core Raft logic with no external dependencies, leaving networking and I/O to the implementer. It supports cluster simulation (virtraft2) for testing invariants like log matching, election safety, and state machine safety, along with fuzz testing via Hypothesis. The source is available as a single amalgamated header (raft.h) for easy integration. Designed for use in distributed systems requiring fault-tolerant replicated state machines, such as in the ticketd ticketing system.
Key Features
Pure C implementation with no external dependencies
Single-file header amalgamation (raft.h) for easy integration
Virtraft2 cluster simulator to test Raft invariants under unreliable networks
Fuzzing/property-based testing via Hypothesis
Supports UDP-like network assumptions (no ordering or duplicate detection)
BSD licensed for permissive use
Comprehensive regression tests for bugs
Pros & Cons
Pros
- No dependencies, minimal footprint
- Permissive BSD license
- Thoroughly tested with simulations and fuzzing
- Single header file simplifies integration
- Flexible networking layer – implementer chooses transport (e.g., UDP)
Cons
- Not thread-safe; requires exclusive access to library functions
- Networking and I/O not provided; implementer must handle all plumbing
- Limited documentation beyond header comments and examples; learning curve for beginners
- No built-in serialization or RPC mechanism
Best For
Building fault-tolerant replicated state machinesDistributed consensus in custom network layersEmbedded systems requiring lightweight consensusEducational projects to study Raft protocol internalsPrototyping distributed databases or key-value stores
FAQ
What is Raft?
Raft is a consensus protocol for managing a replicated log across a cluster of servers. This library provides the core Raft logic in C.
Is this library thread-safe?
No, the library is not thread-safe. You must ensure that its functions are called exclusively, typically by using separate threads for handling Raft peer traffic and client traffic.
Does it include networking?
No, networking is out of scope. The library does not assume a network layer with ordering or duplicate detection, so you can use any transport (e.g., UDP). The implementer must handle all networking plumbing.
How do I integrate the library?
You can use the single-file amalgamation (raft.h) via clib or directly include it. For an example, see the ticketd project. Initialize with raft_new, add cluster nodes with raft_add_node, and call raft_periodic periodically.
What testing has been done?
The library uses a simulator (virtraft2) that checks invariants like log matching, election safety, and state machine safety under chaotic conditions, including partitions, message drops, and duplication. It also uses hypothesis-based fuzzing and has regression tests for all known bugs.