gossipmonger

Gossipmonger is an implementation of the Scuttlebutt gossip protocol endpoint for real-time peer-to-peer state distribution with pluggable storage and transport mechanisms.

Contributors

@tristanls, @KenanSulayman

Usage

var Gossipmonger = require('gossipmonger');

var gossipmonger = new Gossipmonger(
    { // peerInfo
        id: "localId",
        transport: { // default gossipmonger-tcp-transport data
            host: "localhost",
            port: 9742
        }
    },
    { // options
        seeds: [
            {id: "seed1", transport {/*...*/}},
            {id: "seed2", transport {/*...*/}},
            {id: "seed3", transport {/*...*/}}
        ]
    });

gossipmonger.on('error', function (error) {
    console.dir(error); 
});

gossipmonger.on('new peer', function (newPeer) {
    console.log("found new peer " + newPeer.id + " at " + newPeer.transport);
});

gossipmonger.on('peer dead', function (deadPeer) {
    console.log("peer " + deadPeer.id + " is now assumed unreachable");
});

gossipmonger.on('peer live', function (livePeer) {
    console.log("peer " + livePeer.id + " is live again");
});

gossipmonger.on('update', function (peerId, key, value) {
    console.log("peer " + peerId + " updated key " + key + " with " + value);
});

/* **IMPORTANT**
 * Typically, one would create a `transport`, start it (call listen())
 * and then pass it in as `options.transport` in Gossipmonger constructor. This
 * makes the implementation of Gossipmonger less complex and simpler.
 * For development purposes, Gossipmonger comes with a default transport, so
 * it's easier to get a feel for it, but because of that, if you don't provide
 * a `transport`, the default one will be used but **you need to start it**.
 * The call illustrated below will start the default transport. If this isn't done,
 * you will not receive communications from other gossipmongers. */
gossipmonger.transport.listen(function () {
    console.log('default transport is listening');
});

gossipmonger.gossip(); // start gossiping

gossipmonger.update('foo', 'bar');
// this node's foo/bar key value pair will now be gossiped 
//  to the rest of the cluster

Tests

npm test

Visual Test

To watch a cluster of 5 nodes communicate via gossip run scripts/locatest.js via:

npm run localtest

Overview

Gossipmonger is an implementation of the Scuttlebutt gossip protocol endpoint for real-time peer-to-peer peer-state distribution. Gossip protocols are used in a decentralized peer-to-peer manner in order to make every peer that is connected aware of the state of every other peer. The objective is to give every peer global awareness without a centralized server. This is accomplished by heuristically guided message passing between peers.

Peers

Gossipmonger manages information about peers via maintaining peer information in a structure called a peer. A peer stores the details of a particular peer on the network, including the data necessary to estimate whether the peer is "alive" or "dead".

Peers are implemented internally as JavaScript objects, and most details are not necessary to be exposed, however when creating a new Gossipmonger, the following are required to be provided as peerInfo object:

data: Object (Default: {}) A map of key, [value, version] pairs to store for this peer.
id: String Id of this peer.
maxVersionSeen: Integer (Default: 0) Vector clock value indicating the last version of the version of the last change of this peer.
transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.

All peer attributes are as implemented in gossipmonger-peer:

data: Object (Default: {}) Peer data.
id: String Id of the peer.
intervals: Array (Default: [750]) An array of the last (up to MAX_INTERVALS) intervals between times when the peer has been seen.
intervalsMean: Integer (Default: undefined) Memoized intervals mean.
lastTime: Integer (Default: undefined) The last time the peer has been seen (in milliseconds since midnight Jan 1, 1970).
live: Boolean (Default: true) Indicator whether or not the peer is thought to be live.
maxVersionSeen: Integer (Default: 0) Vector clock value indicating the last version of the peer that has been observed.
MAX_INTERVALS: Integer (Default: 100) The maximum number of intervals to keep in intervals.
sum: Integer (Default: undefined) Memoized sum of intervals to make intervals mean calculation more efficient.
transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.

Digests

Digests are passed around between peers to communicate what they know about all other peers and the latest version they have seen of those peers.

A digest is an array of peer objects, for example:

[ 
    {
        id: "peer1", 
        maxVersionSeen: 1732, 
        transport: {
            host: "peer1.host", 
            port: 9742
        }
    },
    {
        id: "peer2", 
        maxVersionSeen: 1432, 
        transport: {
            host: "peer2.host", 
            port: 9742
        }
    }    
]

Deltas

Deltas are passed around between peers in response to receiving a digest to update any information that (from the senders perspective) is out of date.

Deltas are an array of delta objects, for example:

[
    ["peer1", "foo", "bar", 1732],
    ["peer1", "bas", "baz", 4322],
    ["peer2", "far", "blh", 422]
]

Documentation

Gossipmonger

Public API

new Gossipmonger(peerInfo, [options])
gossipmonger.gossip()
gossipmonger.update(key, value)
Event 'error'
Event 'new peer'
Event 'peer dead'
Event 'peer live'
Event 'update'

new Gossipmonger(peerInfo, [options])

peerInfo: Object
- data: Object (Default: {}) A map of key, [value, version] pairs to store for this peer.
- id: String Id of this peer.
- maxVersionSeen: Integer (Default: 0) Vector clock value indicating the last version of the version of the last change of this peer.
- transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.
options: Object
- DEAD_PEER_PHI: Integer (Default: 8) Phi accrual failure detector value that when exceeded assumes the corresponding peer is dead.
- GOSSIP_INTERVAL: Integer (Default: 1000) Number of milliseconds between gossip attempts.
- MAX_DELTAS_PER_GOSSIP: Integer (Default: 5) The maximum number of deltas to include in a gossip.
- MINIMUM_LIVE_PEERS: Integer (Default: 1) If the number of live peers visible to this peer drops below MINIMUM_LIVE_PEERS, this peer will make sure to gossip with one of the seeds even if it thinks it's dead.
- seeds: Array (Default: []) An array of seed peers that the transport understands.
- storage: Object (Default: gossipmonger-memory-storage) An initialized and ready to use storage module for storing local and peer data that conforms to the Gossipmonger Storage Protocol. If storage is not provided, a new instance of gossipmonger-memory-storage will be created and used with default settings.
- transport: Object (Default: gossipmonger-tcp-transport) An initialized and ready to use (i.e. listening) transport module for sending communications that conforms to the Gossipmonger Transport Protocol. If transport is not provided, a new instance of gossipmonger-tcp-transport will be initialized with peerInfo.transport settings, but it will not be started. In this case, gossipmonger.transport.listen() must be called explicitly to start listening.

Creates a new Gossipmonger instance.

The seeds are necessary in order to bootstrap the gossip cluster. Gossipmonger will use these seeds to find out about other nodes and also as peers of last resort if all the peers appear to be dead.

IMPORTANT: If no transport is provided in options, then the default gossipmonger-tcp-transport will be used. However, it needs to be started by explicitily calling gossipmonger.transport.listen() (see Usage). If this does not happen, no communications can be received from other Gossipmongers and they will think this instance is dead.

NOTE: "Why do I have to excplicitly start the transport?". This way, you can create a Gossipmonger instance without worrying about servers being started on the network. It makes things much easier for testing. It also gives you the power of sequencing actions and when you want to start interacting with the outside world.

gossipmonger.digest(livePeers)

CAUTION: reserved for internal use

livePeers: Array (Default: []) An array of live peers.
Return: Array An array of peers with maxVersionSeen fields included.

Creates a digest of peers that are thought to be "live" to send to another peer.

gossipmonger.gossip()

Initiates gossip and will continue to gossip according to GOSSIP_INTERVAL.

The implemented algorithm does the following in order:

Select a random live peer (if any) and send my digest to the peer.
Maybe send my digest to a random dead peer (or do so for sure if all peers appear to be dead).
If number of live peers is below MINIMUM_LIVE_PEERS send my digest to a random seed.
Update my estimate of the liveness of all live peers.
Update my estimate of the deadness of all dead peers.
Set timeout to gossip again GOSSIP_INTERVAL from now.

gossipmonger.update(key, value)

key: String Key to update.
value: Any The value to update with.

Updates the local peer's key with specified value.

Event `deltas receive`

CAUTION: reserved for internal use

function (remotePeer, deltas) {}
- remotePeer: Object
  - id: String Id of the peer.
  - transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.
- deltas: Array An array of deltas to update local knowledge with. Each delta is of the form: [peerId, key, value, version].

Emitted when Gossipmonger receives deltas from a remote peer.

Event `deltas send`

CAUTION: reserved for internal use

function (remotePeer, deltas) {}
- remotePeer: Object
  - id: String Id of the peer.
  - transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.
- deltas: Array An array of deltas to update local knowledge with. Each delta is of the form: [peerId, key, value, version].

Emitted when Gossipmonger sends deltas to a remote peer.

Event `digest receive`

CAUTION: reserved for internal use

function (remotePeer, digest) {}
- remotePeer: Object
  - id: String Id of the peer.
  - transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.
- digest: Array An array of peer objects with id, maxVersionSeen, and transport fields.

Emitted when Gossipmonger receives a digest from a remote peer.

Event `digest send`

CAUTION: reserved for internal use

function (remotePeer, digest) {}
- remotePeer: Object
  - id: String Id of the peer.
  - transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.
- digest: Array An array of peer objects with id, maxVersionSeen, and transport fields.

Emitted when Gossipmonger sends a digest to a remote peer.

Event `error`

function (error) {}
- error: Object An error.

Emitted when Gossipmonger or one of its dependencies emits an error. If no handler is registered, an exception will be thrown.

Event `new peer`

function (newPeer) {}
- remotePeer: Object
  - id: String Id of the peer.
  - transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.

Emitted when Gosspimonger becomes aware of a new peer.

Event `peer dead`

function (deadPeer) {}
- deadPeer: Object
  - id: String Id of the peer.
  - transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.

Emitted when Gossipmonger assumes that a live peer is now dead.

Event `peer live`

function (livePeer) {}
- livePeer: Object
  - id: String Id of the peer.
  - transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.

Emitted when Gossipmonger assumes that a dead peer is now live.

Event `unknown peer`

CAUTION: reserved for internal use

function (peerId) {}
- id: String Id of the unknown peer.

Emitted when Gossipmonger receives deltas for an unknown peer. (It shouldn't happen).

Event `update`

function (peerId, key, value) {}
- id: String Id of the peer.
- key: String Key that was updated at the peer.
- value: Any The new updated value.

Emitted when Gossipmonger is aware of a key update on a remote peer.

Gossipmonger Storage

Modules implementing the storage mechanism for Gossipmonger shall conform to the following interface. A storage is a JavaScript object.

Storage modules shall rely on peer.live property to keep track of peer liveness for the purposes of deadPeers() and livePeers() results.

Storage modules shall treat all peer properties as immutable.

Storage implementations shall allow registering and interacting with event listeners as provided by events.EventEmitter interface.

For reference implementation, see gossipmonger-memory-storage.

storage.deadPeers()

Return: Array An array of peers that are dead (peer.live != true).

storage.get(id)

id: String Id of peer to get.
Return: Object Peer with given id or undefined.

storage.livePeers()

Return: Array An array of peers that are live (peer.live == true).

storage.put(id, peer)

id: String Id of peer to put.
peer: Object Peer to put into storage.

Event `error`

function (error) {}
- error: Object An error that occurred.

Emitted when Storage encounters an error. If no handler is registered, an exception will be thrown.

Gossipmonger Transport

Modules implementing the transport mechanism for Gossipmonger shall conform to the following interface. A transport is a JavaScript object.

Transport implementations shall ensure that deltasToSend and digestToSend will be unaltered.

Transport implementations shall ensure that localPeer.id and localPeer.transport are sent to the remote node unaltered.

Transport implementations shall allow registering and interacting with event listeners as provided by events.EventEmitter interface.

For reference implementation, see gossipmonger-tcp-transport.

Gossipmonger Transport API

transport.deltas(remotePeer, localPeer, deltasToSend)
transport.digest(remotePeer, localPeer, digestToSend)
Event 'deltas'
Event 'digest'
Event 'error'

transport.deltas(remotePeer, localPeer, deltasToSend)

remotePeer: Object Peer to send rpc to.
- transport: Any Any data that the transport mechanism requires for operation.
localPeer: Object Sender peer.
- id: String Sender peer id.
- transport: Any Any data that the transport mechanism requires for operation.
deltasToSend: Any Deltas to send.

Sends deltasToSend to the remotePeer.

transport.digest(remotePeer, localPeer, digestToSend)

remotePeer: Object Peer to send rpc to.
- transport: Any Any data that the transport mechanism requires for operation.
localPeer: Object Sender peer.
- id: String Sender peer id.
- transport: Any Any data that the transport mechanism requires for operation.
digestToSend: Any Digest to send.

Sends digestToSend to the remotePeer.

Event `deltas`

function (remotePeer, deltas) {}
- remotePeer: Object
  - id: String Id of the peer.
  - transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.
- deltas: Any Received deltas.

Emitted when Transport receives deltas from a peer.

Event `digest`

function (remotePeer, digest) {}
- remotePeer: Object
  - id: String Id of the peer.
  - transport: Any Any data identifying this peer to the transport mechanism that is required for correct transport operation.
- digest: Any Received digest.

Emitted when Transport receives digest from a peer.

Event `error`

function (error) {}
- error: Object An error that occurred.

Emitted when Transport encounters an error. If no handler is registered, an exception will be thrown.

Available Modules

Storage

gossipmonger-memory-storage: In-memory storage engine for Gossipmonger.

Transports

gossipmonger-tcp-transport: TCP Transport for Gossipmonger.

Sources

Efficient Reconciliation and Flow Control for Anti-Entropy Protocols

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
scripts		scripts
test		test
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
index.js		index.js
package.json		package.json

License

tristanls/gossipmonger

Folders and files

Latest commit

History

Repository files navigation

gossipmonger

Contributors

Usage

Tests

Visual Test

Overview

Peers

Digests

Deltas

Documentation

Gossipmonger

new Gossipmonger(peerInfo, [options])

gossipmonger.digest(livePeers)

gossipmonger.gossip()

gossipmonger.update(key, value)

Event deltas receive

Event deltas send

Event digest receive

Event digest send

Event error

Event new peer

Event peer dead

Event peer live

Event unknown peer

Event update

Gossipmonger Storage

Gossipmonger Storage API

storage.deadPeers()

storage.get(id)

storage.livePeers()

storage.put(id, peer)

Event error

Gossipmonger Transport

Gossipmonger Transport API

transport.deltas(remotePeer, localPeer, deltasToSend)

transport.digest(remotePeer, localPeer, digestToSend)

Event deltas

Event digest

Event error

Available Modules

Storage

Transports

Sources

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Event `deltas receive`

Event `deltas send`

Event `digest receive`

Event `digest send`

Event `error`

Event `new peer`

Event `peer dead`

Event `peer live`

Event `unknown peer`

Event `update`

Event `error`

Event `deltas`

Event `digest`

Event `error`

Packages