cinderalla / hraftd

A reference use of Hashicorp's Raft implemenation

For some background on this project check out this blog post.

hraftd

hraftd is a reference use of the Hashicorp Raft implementation, inspired by raftd. Raft is a distributed consensus protocol, meaning its purpose is to ensure that a set of nodes -- a cluster -- agree on the state of some arbitrary system, even when nodes are vulnerable to failure and network partitions. Distributed consensus is a fundamental concept when it comes to building fault-tolerant systems.

A simple system like hraftd makes it easy to study Raft in general, and Hashicorp's implementation in particular.

Reading and Writing Keys

Like raftd, the implementation is a very simple key-value store. You can set a key like so:

curl -XPOST localhost:11000/key -d '{"foo": "bar"}'

You can read the value for a key like so:

curl -XGET localhost:11002/key/foo

Running hraftd

Starting and running a hraftd cluster is easy. Download hraftd like so:

mkdir hraftd
cd hraftd/
export GOPATH=$PWD
go get github.com/otoolep/hraftd

Run your first hraftd node like so:

$GOPATH/bin/hraftd ~/node0

You can now set a key and read its value back:

curl -XPOST localhost:11000/key -d '{"user1": "batman"}'
curl -XGET localhost:11000/key/user1

Bring up a cluster

Let's bring up 2 more nodes, so we have a 3-node cluster. That way we can tolerate the failure of 1 node:

$GOPATH/bin/hraftd -haddr :11001 -raddr :12001 -join :11000 ~/node1
$GOPATH/bin/hraftd -haddr :11002 -raddr :12002 -join :11000 ~/node2

This tells each new node to join the existing node. Once joined, each node now knows about the key:

curl -XGET localhost:11000/key/user1
curl -XGET localhost:11001/key/user1
curl -XGET localhost:11002/key/user1

Furthermore you can add a second key:

curl -XPOST localhost:11000/key -d '{"user2": "robin"}'

Confirm that the new key has been set like so:

curl -XGET localhost:11000/key/user2
curl -XGET localhost:11001/key/user2
curl -XGET localhost:11002/key/user2

Tolerating failure

Kill the leader process and watch one of the other nodes be elected leader. The keys are still available for query on the other nodes, and you can set keys on the new leader. Furthermore when the first node is restarted, it will rejoin the cluster and learn about any updates that occurred while it was down.

Leader-forwarding

Automatically forwarding requests to set keys to the current leader is not implemented. The client must always send requests to change a key to the leader or an error will be returned.