Running many logical nodes in different machines, to build a distributed node cluster. Each logical node can host services, and interchange messages.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Running many logical nodes in different machines, to build a distributed node cluster. Each logical node can host application objects, and interchange messages.


In some of my projects, I need to run object applications that interchange message with other running processes. Instead of having each process open its own TCP/IP port and connecting to the other processes that host the same object application, I want to have an utility to manage such cases. MultiNodes does:

  • Start a logical node in a worker process.
  • Expose the logical node to other nodes in the node set.
  • Connect to other logical nodes.
  • Declare and exposes the local services/applications.
  • Exchange messages (simple JavaScript objects serializable to JSON) between distributed services/applications.

See a logical node as an object running in a machine, using Node.js.

See a service/application as an object that sends and receives messages.

Related projects that need this functionality:

  • SimpleStorm Simple Storm-like distributed application implementation.
  • AjFabriqNode A Distributed Application Framework for NodeJs.

Example: SimpleStorm can run local topologies, like the original Storm Java project. But it can run distributed topologies, too. Each task in those topologies can emit message to the other tasks, that can be local or remote. Instead of managing the connection and discovery of the other remote machines running topologies by itself, SimpleStorm could rely on MultiNode to manage the distributed logical nodes.


Via npm on Node:

npm install multinodes


Reference in your program:

var multinodes = require('multinodes');

Create a node:

var node = multinodes.createNode();

It creates a node with a random name.

var node = multinodes.createNode(name);

It creates a node with the given name.

var node = multinodes.createNode(port[, host]);
// a server starts listen on port
node.start(function(msg) {
    // For each connected client
    // it will receive the description of remote node

Register an application with a description:

node.registerApplication(name, application, description);

application should be an object with a process(msg) function to receive messages. description is an optional object that has application-dependent information.

Get node description:

var description = node.getDescription();

It includes the node name, the registered applications, and the names of the known remote nodes.

Connect a node to a published server node:

node.connect(port, host, function(msg) {
    // It receives the remote node description msg
    // with its name, known nodes and application descriptions

See network test.

Send a message to a node:


Send a message to a remote/connected node:

node.processInNode(nodename, msg);


// Send a message to an application, to be processed as app.process(msg)
node.process({ application: 'webcrawler', message: { link: '' }});
// Send a call to an application, to be processed as app.[action](args...)
node.process({ application: 'webcrawler', action: 'methodname', args: [1, 2] });

Usually, instead of node.process you can use the following methods:

Send a message to app.process(msg)

node.tellToApplication(appname, msg);

Call a method (action) in application as app.action.

node.callApplication(appname, actionname, args);

args is an array.

Stops a node:


Run a function in a node (local or remote)

node.runInNode(function (msg) {
    // this points to node
}, args); // args is an array 
node.runInNode(nodename, function () {
    // this points to selected node
}, args);

Run a function in an application (local or remote)

node.runInApplication(appname, function () {
    // this points to application
}, args);
node.runInApplication(nodename, appname, function () {
    // this points to selected application
}, args);

Using this functions you can run code at remote nodes. See Collatz Sample: the server node code sends code to every new client node, to load and start application.


git clone git://
cd MultiNodes
npm install
npm test



To do

  • Samples
  • Improve


  • 0.0.1: Published.
  • 0.0.2: Published. New sample, runInNode, runInApplication, serializing function.


Feel free to file issues and submit pull requests — contributions are welcome.

If you submit a pull request, please be sure to add or update corresponding test cases, and ensure that npm test continues to pass.