Raft-rs

Note: This project is of alpha quality. APIs are still in some flux, but they are ready for you to play with them. A stable version will be released when we feel it is ready.

Development Updates

Problem and Importance

When building a distributed system one principal goal is often to build in fault-tolerance. That is, if one particular node in a network goes down, or if there is a network partition, the entire cluster does not fall over. The cluster of nodes taking part in a distributed consensus protocol must come to agreement regarding values, and once that decision is reached, that choice is final.

Distributed Consensus Algorithms often take the form of a replicated state machine and log. Each state machine accepts inputs from its log, and represents the value(s) to be replicated, for example, a hash table. They allow a collection of machines to work as a coherent group that can survive the failures of some of its members.

Two well known Distributed Consensus Algorithms are Paxos and Raft. Paxos is used in systems like Chubby by Google, and Raft is used in things like etcd. Raft is generally seen as a more understandable and simpler to implement than Paxos, and was chosen for this project for this reason.

Documentation

• Raft Crate Documentation
• The Raft site
• The Secret Lives of Data - Raft
• Raft Paper
• Raft Dissertation
• Raft Refloated

Compiling

For Linux, BSD, or Mac. Windows is not supported at this time. We are willing and interested in including support, however none of our contributors work on Windows. Your PRs are welcome!

You will need the Rust compiler:

curl -L https://static.rust-lang.org/rustup.sh > rustup
chmod +x rustup
./rustup --channel=nightly

We require the nightly channel for now.

This should install cargo and rustc. Next, you'll need capnp to build the messages.canpnp file . It is suggested to use the git method

git clone https://github.com/sandstorm-io/capnproto.git
cd capnproto/c++
./setup-autotools.sh
autoreconf -i
./configure
make -j6 check
sudo make install

Finally, clone the repository and build it:

git clone git@github.com:Hoverbear/raft-rs.git && \
cd raft-rs && \
cargo build

Note this is a library, so building won't necessarily produce anything useful for you unless you're developing.

Examples

You can run a single-node register example like this:

RUST_LOG=raft=debug cargo run --example register server 1 1 127.0.0.1:8080

There are currently examples showing:

• Register: A single shared, replicated buffer for storing some data. Uses bincode.
• Hashmap: A replicated hash table that stores json::Value with Strings as keys. Uses serde.

For a multi-node example (hashmap shown for variety), make sure to include all the peers on all instances:

# Node 1
RUST_LOG=raft=debug cargo run --example hashmap server 1 1 127.0.0.1:8080 2 127.0.0.1:8081
# Node 2
RUST_LOG=raft=debug cargo run --example hashmap server 2 1 127.0.0.1:8080 2 127.0.0.1:8081

We'd love it if you contributed your own or expanded on ours!

Testing

You can run the raft crate's full bank of tests with all debug output like so:

RUST_BACKTRACE=1 RUST_LOG=raft=debug cargo test -- --nocapture

For something more terse use cargo test.

Contributing

First timer with Git? Check this out for some help!!

We use Homu for merging requests. This means we cannot merge your code unless it passes tests!