webrtc-chord

An implementation of Chord, a protocol of Distributed Hash Table, using WebRTC.

Releases

Note that releases of different major versions are not compatible.

The next release v2.0.0 is being developed on master.

Requirements

webrtc-chord requires WebRTC, so check if your browser supports WebRTC.

It also uses PeerJS library, which simplifies the use of WebRTC. PeerJS needs PeerServer (to act) as signaling server, so you must run your own PeerServer or use cloud services such as PeerServer Cloud or SkyWay (Centralization problem caused by PeerServer is discussed in Issue 2). A Chord object receives the information for connecting to the PeerServer via a parameter of the constructor.

WebRTC and PeerJS uses STUN/TURN server and PeerServer, so you may need to adjust some proxy settings to access to them.

Build

cd webrtc-chord
git submodule init && git submodule update
npm install
npm run-script build

Include libraries

webrtc-chord depends on the following libraries.

• Lo-Dash
• sha256.js of crypto-js libraries
• PeerJS (>= 0.3.9)

So you must include them before include webrtc-chord.js as the following.

<script type="text/javascript" src="https://github.com/tsujio/webrtc-chord/raw/master/path/to/lodash.js"></script>
<script type="text/javascript" src="https://github.com/tsujio/webrtc-chord/raw/master/path/to/sha256.js"></script>
<script type="text/javascript" src="https://github.com/tsujio/webrtc-chord/raw/master/path/to/peer.js"></script>
<script type="text/javascript" src="https://github.com/tsujio/webrtc-chord/raw/master/path/to/webrtc-chord.js"></script>

Setup

First, create a new chord instance.

// Create a new chord instance
var chord = new Chord(config);

config is an object containing the following properties.

var config = {
  peer: {                               // The object to pass to the Peer constructor.
    id: 'yourid',                       // See the PeerJS document for details.
    options: {
      host: ...,
      ...
    }
  },

  debug: false,                         // Enable debug log.
                                        // Defaults to false.

  numberOfEntriesInSuccessorList: 3,    // The number of nodes to retain as successor.
                                        // Defaults to 3.

  connectionPoolSize: 10,               // The capacity of connection pool.
                                        // Defaults to 10.

  connectionOpenTimeout: 30000,         // The timeout in milliseconds for waiting
                                        // opening a connection.
                                        // Defaults to 30000.

  requestTimeout: 180000,               // The timeout in milliseconds for waiting
                                        // a response from the other node.
                                        // Defaults to 180000.

  stabilizeTaskInterval: 30000,         // The interval in milliseconds in which the
                                        // stabilize task works.
                                        // Defaults to 30000.

  fixFingerTaskInterval: 30000,         // The interval in milliseconds in which the
                                        // fix finger task works.
                                        // Defaults to 30000.

  checkPredecessorTaskInterval: 30000,  // The interval in milliseconds in which the
                                        // check predecessor task works.
                                        // Defaults to 30000.
};

Chord network

After creating an instance, create a new chord network,

// Create a new chord network
chord.create(function(myPeerId, error) {
  if (error) {
    console.log("Failed to create chord network: " + error);
  } else {
    console.log("My peer ID: " + myPeerId);
  }
});

or join an existing one.

// Join an existing chord network
chord.join(bootstrapId, function(myPeerId, error) {
  if (error) {
    console.log("Failed to join chord network: " + error);
  } else {
    console.log("My peer ID: " + myPeerId);
  }
});

bootstrapId is the peer ID of the node which you initially connect to.

Entries

Then, you can insert/retrieve/remove entries.

// Insert entry
chord.insert(key, value, function(id, error) {
  if (error) {
    console.log("Failed to insert entry: " + error);
  } else {
    console.log("The entry has been inserted (id: " + id + ")");
  }
});

// Retrieve entries
chord.retrieve(key, function(entries, error) {
  if (error) {
    console.log("Failed to retrieve entries: " + error);
  } else {
    console.log("Retrieved " + entries.length + " entries.");
  }
});

// Remove entry
chord.remove(key, value, function(error) {
  if (error) {
    console.log("Failed to remove entry: " + error);
  } else {
    console.log("The entry has been removed.");
  }
});

Expect key to be a string value type and value to be a JSON data type.

You can detect insertion/removal of entries into/from your node as the following.

// Invoked when entries are inserted into your node
chord.onentriesinserted = function(insertedEntries) {
  console.log(insertedEntries.length + " entries were inserted.");
};

// Invoked when entries are removed from your node
chord.onentriesremoved = function(removedEntries) {
  console.log(removedEntries.length + " entries were removed.");
};

APIs of get/set entries from/to your node are also provided.

// Get the entries stored in your node
var entries = chord.getEntries();

// Set entries to your node
chord.setEntries(entries);

Leave network

// Leave chord network
chord.leave();

Chord monitor

Chord monitor visualizes actual behavior of a Chord network.

Open chord-monitor.html by a WebRTC enabled browser to start monitoring.

You can create nodes by clicking "Create node" button and connect them by "Join network" button.

Enjoy.

References

• I. Stoica, et al, Chord: A scalable peer-to-peer lookup service for internet applications, 2001
• Open Chord