Add initial commit.

MIT licensed.
Documentation.
Some tests.
Chord distributed hash table implementation.

Author: bollenberger

LICENSE.md

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+=====================
+
+Copyright (c) 2013 Optimizely, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,113 @@
+Chord - Distributed Hash Table
+==============================
+
+[Chord] [1] 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
+
+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.
+
+[1] http://pdos.csail.mit.edu/papers/chord:sigcomm01/chord_sigcomm.pdf "Chord: A Scalable Peer-to-peer Lookup Service for Internet Applications"