search

hitchyjs / scull

Raft Consensus for Node.js, backed by LevelDB
MIT License
3 stars 4 forks source link

readme

Scull

Raft Consensus Algorithm implementation for Node.js.

About

This package was started as a fork of package skiff by Pedro Teixeira.

While reading, revising and refactoring original code, trying to understand the project and fixing some encountered issues we've planned to keep this fork tightly bound to the original package by using similar name, sharing version numbers and probably providing revisions back upstream. But on starting to introduce changes breaking existing API as well as trying to replace some downsides of existing code with more efficient features we considered our fork significantly moving away from its origin. That's why we chose to switch its name to express this stronger separation.

Motivation

The original skiff has been forked to adopt it's abilities for implementing an application-cluster backend for our hitchy framework. Even though this sounds like the now called project scull being tightly bound to hitchy we guarantee it's not. The fork has been started to refactor parts of code, modernizing its API and adding some commands to cluster missing in original project. We basically intend to keep this project mostly API compatible to skiff, too.

Features

Installation

$ npm install scull --save

Usage

const Scull = require( 'scull' );

const options = {
  db: require( 'memdown' ), // in memory database
  peers: [ // peer addresses
    '/ip4/127.0.0.1/tcp/9491',
    '/ip4/127.0.0.1/tcp/9492'
  ]
};

const shell = Scull( '/ip4/127.0.0.1/tcp/9490', options );

// expose the cluster as a LevelUP-compatible database
const db = shell.levelUp();

shell.start( err => {
  if ( err ) {
    console.error( 'Error starting scull node: ', err.message );
  } else {
    console.log( 'Scull node started' );

    db.put( 'key', 'value', ( err ) => {
      // ...
    } );
  }
} );

API

Scull( address, options ) : Shell

Creates a new Shell for controlling local node in cluster.

Arguments:

Advanced options

shell.start() : Promise

This method is starting current node by establishing network connectivity, loading its persistent state from database and entering follower state while waiting for first heartbeat request from current leader node of cluster. The returned promise is resolved on having loaded persistent state and on having started to listen for incoming requests.

shell.stop() : Promise

This method is stopping current node by disconnecting it from all its peers which implies shutting down any listener for incoming requests or replies as well as ceasing to send any requests.

shell.levelUp()

Returns a new LevelUP-compatible object for interacting with the cluster.

shell.levelDown()

Returns a new LevelDOWN-compatible object for interacting with the cluster.

shell.join( peerAddress ) : Promise

Adds node at given address as another peer to current cluster unless it has been added before.

shell.leave( peerAddress ) : Promise

Adds node at given address as another peer to current cluster unless it has been added before.

shell.stats ()

Returns some interesting stats for this node.

shell.peers() : Promise<[]>

Fetches list of current nodes in cluster including statistical information collected by current leader. This method might forward the request to current leader node and thus has to be used asynchronously.

shell.term

This read-only property provides current term of controlled node. The term is identifying the continuous reign of a leader node. Whenever a current leader is failing another one is elected starting another term. The same applies in case of one election failing to properly choose one of the available nodes in cluster to become leader.

shell.weaken( durationMS )

Weakens the node for the duration. During this period, the node transitions to a special weakened state, in which the node does not react to election timeouts. This period ends once it learns a new leader or the period runs out.

shell.readConsensus() : Promise

Requests special read command on cluster to be confirmed by a majority of nodes in cluster considered consensus from the cluster on its current state as managed by current leader node.

shell.waitFor( peers ) : Promise

Performs equivalent request as shell.readConsensus() but requiring explicit confirmation from all given peers in addition to required confirmation by majority.

This method is available to make sure one or more nodes of cluster have been catching up.

shell.peers().then( peers => shell.waitFor( peers ).then( () => {
    // do something
} ) );

This code template can be used to explicitly wait for consensus confirmed by all peer nodes of cluster.

Events

A Shell instance emits the following events:

Scull.createNetwork( options )

This static method - it's no method of shell created before - creates a network you can share amongst several Scull nodes in the same process.

Options:

License

MIT

Copyright