Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mascrypt0/chordhelper

Chord Distributed Hash Table
https://github.com/mascrypt0/chordhelper

Last synced: 14 days ago
JSON representation

Chord Distributed Hash Table

Awesome Lists containing this project

README 

        
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.