liferaft
is an JavaScript implementation of the Raft consensus algorithm.
The liferaft
module is distributed through npm and is compatible with
browserify
as well as node.js
. You can install this module using:
npm install --save liferaft
In all examples we assume that you've imported the liferaft
module as
following:
'use strict';
var LifeRaft = require('liferaft')
, raft = new Raft('address', { /* optional options */});
Please note that the instructions for Node.js and browser are exactly the same as we assume that your code will be compiled using a Browserify based system. The only major difference is that you probably don't need to configure a commit and append log (but this of course, fully optional).
The LifeRaft library is quite dumb by default. We try to be as lean and
extendible as possible so you, as a developer, have complete freedom on how you
want to implement Raft in your architecture. This also means that we ship this
library without any build in transport. This allows you to use it with your
existing technology stack and environment. If you want to use SharedWorkers
as
transport in the browser? Awesome, you can do that. Want to use it on node?
There are literally thousands of different transport libraries that you can use.
There are a couple of default options that you can configure in the constructor of your Raft:
address
A unique address of the node that we just created. If none is supplied we will generate a random UUID.heartbeat
The heartbeat timeout. Make sure that this value is lower then your minimum election timeout and take message latency in consideration when specifying this and the minimum election value.election min
Minimum election timeout.election max
Maximum election timeout.threshold
Threshold for when the heartbeat and latency is to close to the minimum election timeout.Log
: An Log compatible constructor we which use for state and data replication.
The timeout values can be configured with either a number which represents the
time milliseconds or a human readable time string such as 10 ms
. The heartbeat
timeouts are used to detect a disconnection from the LEADER
process if no
message has been received within the given timeout we assume its dead that we
should be promoted to master. The election timeout is the time it may take to
reach a consensus about the master election process. If this times out, we will
start another re-election.
var raft = new Raft({
'address': 'tcp:https://localhost:8089',
'election min': '200 millisecond',
'election max': '1 second'
});
As you might have noticed we're using two different styles of passing in the address to the raft instance, as address property in the options and as first argument in the constructor.
The liferaft
module is an EventEmitter
at it's core and is quite chatty
about the events it emits.
Event | Description |
---|---|
term change |
The term has changed. |
leader change |
We're now following a newly elected leader. |
state change |
Our state/role changed. |
heartbeat timeout |
Heartbeat timeout, we're going to change to candidate. |
data |
Emitted by you, so we can work with the data. |
vote |
We've received a vote request. |
leave |
Node has been removed from the cluster. |
join |
Node has been added to the cluster. |
end |
This Raft instance has ended. |
initialize |
The node has been fully initialized. |
error |
An error happened while doing.. Things! |
threshold |
The heartbeat timeout is getting close to election timeout. |
leader |
Our state changed to leader. |
follower |
Our state changed to follower. |
candidate |
Our state changed to candidate. |
stopped |
Our state changed to stopped. |
heartbeat |
The leader is about to send a heartbeat message. |
commit |
A command has been saved to the majority of node's logs |
Please note that the following properties are exposed on the constructor
not
on the prototype
.
This is an array that contains the names of the states. It can be used to create a human readable string from your current state.
console.log(LifeRaft.states[raft.state]); // FOLLOWER
These are the values that we set as state. If you instance is a leader it's
state will be set to LifeRaft.LEADER
.
The rest of these properties are exposed on the LifeRaft prototype
Check the type of the given thing. This returns the correct type for arrays,
objects, regexps and all the things. It's used internally in the library but
might be useful for you as user as well. The function requires one argument
which would be the thing
who's type you need figure out.
raft.type([]); // array
raft.type({}); // object
Check if we've reached our quorum (a.k.a. minimum amount of votes requires for a voting round to be considered valid) for the given amount of votes. This depends on the amount of joined nodes. It requires one argument which is the amount of responses that have been received.
raft.join('tcp:https://127.0.0.1');
raft.join('tcp:https://127.0.0.2');
raft.join('tcp:https://127.0.0.3');
raft.join('tcp:https://127.0.0.4');
raft.join('tcp:https://127.0.0.4');
raft.quorum(5); // true
raft.quorum(2); // false
Returns the majority that needs to be reached for our quorum.
raft.majority(); // 4
According to section 5.3 of the Raft paper it's required that we retry sending
the RPC messages until they succeed. This function will run the given attempt
function until the received callback has been called successfully and within our
given timeout. If this is not the case we will call the attempt function again
and again until it succeeds. The function requires 3 arguments:
attempt
, The function that needs to be called over and over again until he calls the receiving callback successfully and without errors as we assume an error first callback pattern.fn
, Completion callback, we've successfully executed the attempt.timeout
, Time the attempt is allowed to take.
raft.indefinitely(function attemp(next) {
dosomething(function (err, data) {
//
// if there is no error then we wil also pass the data to the completion
// callback.
//
return next(err, data);
});
}, function done(data) {
// Successful execution.
}, 1000);
Generate a new packet object that can be transfered to a client. The method accepts 2 arguments:
type
, Type of packet that we want to transfer.data
, Data that should be transfered.
var packet = raft.packet('vote', { foo: 'bar' });
These packages will contain the following information:
state
If we are aLEADER
,FOLLOWER
orCANDIDATE
term
Our current term.address
The address of this node.leader
The address of our leader.last
If logs are enabled we also include the last committed term and index.
And of course also the type
which is the type you passed this function in and
the data
that you want to send.
The message method is somewhat private but it might also be useful for you as developer. It's a message interface between every connected node in your cluster. It allows you to send messages the current leader, or only the followers or everybody. This allows you easily build other scale and high availability patterns on top of this module and take advantage of all the features that this library is offering. This method accepts 2 arguments:
who
, The messaging pattern/mode you want it use. It can either be:
LifeRaft.LEADER
: Send message to the current leader.LifeRaft.FOLLOWER
: Send to everybody who is not a leader.LifeRaft.CHILD
: Send to every child in the cluster (everybody).<node address>
: Find the node based on the provided address.
what
, The message body you want to use. We high suggest using the.packet
method for constructing cluster messages so additional state can be send.when
, Optional completion callback for when all messages are send.
This message does have a side affect it also calculates the latency for sending the messages so we know if we are dangerously close to our threshold.
Add a new raft node to your cluster. All parameters are optional but normally
you would pass in the name or address with the location of the server you want
to add. The write method is only optional if you are using a custom instance
that already has the write
method defined.
var node = raft.join('127.0.0.1:8080', function write(packet) {
// Write the message to the actual server that you just added.
});
As seen in the example above it returns the node
that we created. This Node
is also a Raft instance. When the node is added to the cluster it will emit the
join
event. The event will also receive a reference to the node that was added
as argument:
raft.on('join', function join(node) {
console.log(node.address); // 127.0.0.1:8080
});
Now that you've added a new node to your raft cluster it's also good to know
that you remove them again. This method either accepts the address of the node that
you want to remove from the cluster or the returned node
that was returned
from the LifeRaft.join
method.
raft.leave('127.0.0.1:8080');
Once the node has been removed from the cluster it will emit the leave
event.
The event will also receive a reference to the node that was removed as
argument:
raft.on('leave', function leave(node) {
console.log(node.address); // 127.0.0.1:8080
});
Private method, use with caution
This promotes the Node from FOLLOWER
to CANDIDATE
and starts requesting
votes from other connected nodes. When the majority has voted in favour of this
node, it will become LEADER
.
raft.promote();
This method is also aliased as .destroy
.
This signals that the node wants to be removed from the cluster. Once it has
successfully removed it self, it will emit the end
event.
raft.on('end', function () {
console.log('Node has shut down.');
});
raft.end();
Save a json command to the log. The command will be added to the log and then
replicated to all the follower nodes. Once the majority of nodes have received
and stored the command. A commit
event will be triggered so that the
command can be used.
raft.command({name: 'Jimi', surname: 'Hendrix'});
raft.on('commit', function (command) {
console.log(command.name, command.surname);
});
LifeRaft uses the same pattern as Backbone.js to extend it's prototypes. It
exposes an .extend
method on the constructor. When you call this method it
will return a fresh LifeRaft constructor with the newly applied prototypes and
properties. So these extends will not affect the default instance. This extend
method accepts 2 arguments.
- Object with properties that should be merged with the
prototype
. - Object with properties that should be merged with the constructor.
var LifeBoat = LifeRaft.extend({
foo: function foo() {
return 'bar';
}
});
LifeRaft uses Levelup for storing the log that is replicated to each node. Log replication is optional and so the log constructor needs to be included in the options when creating a raft instance. You can use any leveldown compatible database to store the log. LifeRaft will default to using leveldown. A unique path is required for each node's log.
const Log = require('liferaft/log');
const raft = new Raft({
adapter: require('leveldown'),
path: './db/log1'
});
The library ships without transports by default. If we we're to implement this
it would have made this library way to opinionated. You might want to leverage
and existing infrastructure or library for messaging instead of going with our
solution. There are only two methods you need to implement an initialize
method and an write
method. Both methods serve different use cases so we're
going to take a closer look at both of them.
var LifeBoat = LifeRaft.extend({
socket: null,
write: function write(packet, callback) {
if (!this.socket) this.socket = require('net').connect(this.address);
this.socket.write(JSON.stringify(packet));
// More code here ;-)
}
});
There are a couple of things that we assume you implement in the write method:
- Message encoding The packet that you receive is an JSON object but you have to decide how you're going transfer that over the write in the most efficient way for you.
- message resending The Raft protocol states the messages that you write should be retried until indefinitely (Raft 5.3). There are already transports which do this automatically for you but if your's is missing this, the LifeRaft#indefinitely() is specifically written for this.
When you extend the LifeRaft
instance you can assign a special initialize
method. This method will be called when our LifeRaft
code has been fully
initialized and we're ready to initialize your code. The invocation type depends
on the amount of arguments you specify in the function.
- synchronous: Your function specifies less then 2 arguments, it will receive one argument which is the options object that was provided in the constructor. If no options were provided it will be an empty object.
- asynchronous: Your function specifies 2 arguments, just like the
synchronous execution it will receive the passed options as first argument but
it will also receive a callback function as second argument. This callback
should be executed once you're done with setting up your transport and you are
ready to receive messages. The function follows an error first pattern so it
receives an error as first argument it will emit the
error
event on the constructed instance.
var LifeBoat = LifeRaft.extend({
socket: null,
initialize: function initialize(options) {
this.socket = new CustomTransport(this.address);
}
});
//
// Or in async mode:
//
var LifeBoat = LifeRaft.extend({
server: null,
initialize: function initialize(options, fn) {
this.server = require('net').createServer(function () {
// Do stuff here to handle incoming connections etc.
}.bind(this));
var next = require('one-time')(fn);
this.server.once('listening', next);
this.server.once('error', next);
this.server.listen(this.address);
}
})
After your initialize
method is called we will emit the initialize
event. If
your initialize
method is asynchronous we will emit the event after the
callback has been executed. Once the event is emitted we will start our timeout
timers and hope that we will receive message in time.
MIT