node-clusterfork v0.4.0

clusterfork

An abstraction over the Node.js cluster API allowing you to run programs clustered with little or no configuration (why?).

It's as simple as running clusterfork server.js instead of node server.js!

• Installation
• Usage
  • Via the command-line interface
  • As an npm script
  • Programmatically
• Features
  • Debug information
  • Number of workers
  • Automatic restart
• Interactive example
• Why

Installation

Install node-clusterfork to your project, saving it in package.json:

npm install -S node-clusterfork

If you just want to try node-clusterfork out, you may also install it globally:

npm install -g node-clusterfork

Usage

Via the command-line interface

If you have node-clusterfork installed globally, you can run a Node.js program (usually a web server) like this:

clusterfork server.js

You might want to pass the -v / --verbose flag as well, to get a better idea of what's going on behind the scenes.

As an npm script

Node.js programs are often run via the npm start command. For that to work, you will have to edit your package.json in this fashion:

"scripts": {
- "start": "node server.js"
+ "start": "clusterfork server.js"
}

Note that node-clusterfork should be installed normally, not globally, for the above example.

Programmatically

If you'd rather not do any of the above, and prefer the explicitness of code, you might want to use node-clusterfork programmatically:

'use strict';
const clusterfork = require('node-clusterfork');
const createServer = require('http').createServer;

const server = createServer((req, res) => {
  res.end(`Hello from process ${process.pid}`);
});

clusterfork(() => server.listen(3000), { verbose: true });

The above example starts a clustered server listening on port 3000. The only thing done differently from normal is that instead of calling server.listen directly, the call is passed along as an anonymous function to node-clusterfork.

Features

For a full list of options, run clusterfork -h.

Debug information

You may get debug information on the state of the master process and the workers by using the -v / --verbose flag.

Number of workers

The default behaviour of node-clusterfork is to create a one-to-one mapping to your CPU cores, thus creating 8 workers if you have 8 cores. You may override this behaviour with the -c / --concurrency option, e.g.:

clusterfork server.js --concurrency $WEB_CONCURRENCY

Automatic restart

If you do not wish node-clusterfork to restart workers automatically if they die, use the -n / --no-refork flag. Note that this option is called refork (not noRefork) when passing options as an object to the clusterfork function.

Interactive example

Copy the following code to a file named server.js:

'use strict';
const createServer = require('http').createServer;

createServer((req, res) => {
  res.end(`Hello from process ${process.pid}`);
}).listen(3000);

You can now run the server normally with node server.js. Opening http://localhost:3000 you should see something like this:

Hello from process 12345

In this example, 12345 is the PID of the server. You can kill it by running kill -9 12345. If you refresh the page, you'll see that you'll get no response.

Now, assuming you have installed node-clusterfork globally, you can run the server like this:

clusterfork server.js -v

You will see the PIDs of the workers in the console (due to -v) and if you open http://localhost:3000 in the browser, you will get a hello message as before.

You can see how node-clusterfork restarts processes as they die by killing the process specified in the browser. If you refresh the page, you'll get a new PID, from one of the other workers or the newly created one.

Why

Node.js is single-threaded and cannot take advantage of multiple cores by default. It also has a low hard memory limit. To take full advantage of all resources, you must fork processes, also called clustering. This can be done via Node.js cluster API or by using a library such as clusterfork.

In many cases there is no need for custom logic to implement clustering. By using clusterfork you can avoid modifying your app's entry point with clustering boilerplate and try out different configurations with ease. The optimal clustering configuration is highly dependent on the server's resources. Heroku has some examples of sane numbers of workers for clustering on their various server types.