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

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.