chord

Chord - Distributed Hash Table
==============================

Chord
is a self-organizing distributed hash table. This is an implementation of the Chord
algorithm in Node.js. It provides the ability to construct a Chord cluster and to
route application layer messages to a process responsible for a range of keys.

It supports virtual nodes and uses UDP as its out-of-process transport layer.

API
---

$3

Occasionally, you may wish to hash a value the same way that Chord does. It currently
uses Murmurhash3-128, but hash will always expose the current hash algorithm.

$3

$3

The primary entry point for starting a Chord server. The available arguments are:

* listen_port: The UDP port on which to listen.
* virtual_node_count: The number of virtual nodes to start.
* node_to_join: The address of a node to join (optional).
* on_message: A callback function that is notified when a message addressed to a
local virtual node is received.

The returned value is a send_message function. The send_message function also has a
close property, which is a function to shut down the local virtual nodes.

var server = chord.Chord(...); // start the server
server(...) // send a message (see below)
server.close() // stop the server

$3

This is the function for sending a new application level message to another node in the
Chord ring. It takes the following parameters:

* to: Optional (must be null if not used). The address of the node to which to send.
* id: The key of the DHT to which to address the message. The node which is currently
responsible for that point in the hash ring will receive the message.
* message: A JSON-able object, which will be send to the recipient.
* reply_to: Optional. The address of the node for the recipient to reply to. This may be
used as a way to share the identity of a node with another node. If the recipient replies,
their message will be sent to the reply_to node. If no reply_to is specified, replies
return to the original sender.

$3

The client is intended to provide an easy way to have non-members of the Chord ring
communicate with members of the Chord ring. This is useful if, for example, members of the
Chord ring provide a data storage service, and clients of this data storage service need
to make requests of it without themselves storing data.

A client is really just a completely local Chord ring that never joins any other node. As such,
it has all of the machinery necessary to speak the Chord wire protocol to another Chord ring.

* on_message: The callback that is notified when a message is received.
* listen_port: The port on which to listen for reply messages.

$3

Whenever a client or server receives a message, its on_message callback is triggered. The callback
receives a few parameters:

* from: The address of the sender. There is a from.id property, which is the point in the hash
ring of the sender's identity.
* id: The key to which the message was sent.
* message: The application layer message that was received.
* reply: A callback for sending a reply message (see below).

$3

Send a message to source (or reply_to) of a received message.

* message: The message to send back.
* to: Optional. The address of the node to which to send the reply.
* reply_to: Optional. The address to which the recipient will reply. If not specified,
any reply will return to the originator of the message. One useful pattern is to
pass from as the reply_to, which will cause the next reply to also go to the originator
of the request. This can permit multi-stage operations without having to route the final reply
through intermediate nodes.

Setting up a cluster
--------------------
When you set up a cluster, you will first create an initial node. The only thing that
distinguishes your initial node from any other node is that it does not join any other
node. Subsequent nodes join any existing node. The Chord protocol will distribute the
existence of new nodes around the ring automatically.

To create a new node:

var chord = require('chord');
chord.Chord(1234, // Listen on port 1234
10, // Start 10 virtual nodes
on_message); // Call the function 'on_message' when we receive something

To connect a subsequent node:

chord.Chord(1235,
10,
{address:'127.0.0.1', port:1234}, // Connect to the existing server on port 1234
on_message_2); // Provide a callback for receiving.

All 20 virtual nodes will talk amongst themselves to arrange themselves in a ring. Subsequent
messages will be delivered the node that owns a particular key at that time. Note that due to
nodes leaving an joining, the node that owns a particular key may change over time. Your application
should be designed to expect this.

[1] "Chord: A Scalable Peer-to-peer Lookup Service for Internet Applications"