Gossipmonger NPM

gossipmonger

Gossipmonger is an implementation of the Scuttlebutt gossip protocol endpoint for real-time peer-to-peer peer-state distribution.

Installation

npm install gossipmonger

Tests

npm test

NOTE: There are no tests right now.

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 in options.peerInfo:

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 follows:

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.

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.

Documentation

Gossipmonger

Public API

new Gossipmonger(options)

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.
- 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.
- 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 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 created and used with default settings.

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.

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.

Each gossip goes through the following stages:

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

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

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

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

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 `new peer`

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`

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`

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.