npm package: @mascrypt0/chordhelper
Description: Chord Hash Table
Author: mascrypt0
Latest version: 0.1.2

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

[Chord](http://pdos.csail.mit.edu/papers/chord:sigcomm01/chord_sigcomm.pdf)
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
---

### chord.hash(string)

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.

### chord.Chord(listen_port, virtual_node_count, node_to_join, on_message)
### chord.Chord(listen_port, virtual_node_count, on_message)

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

### send_message(to, id, message, reply_to)

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.

### chord.Client(on_message, listen_port)

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.

### on_message(from, id, message, reply)

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).

### reply(message, to, reply_to)

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.