forkie

Forkie

Forkie is a graceful process manager which allows you to:

• register workers:
  • nodejs modules
  • node.js cluster workers
• register start/stop hooks on master and workers
• get workers events: ready/started/stopped
• get master events: worker ready, worker started, worker stopped, worker killed
• handle graceful stops (think long running jobs)
• automatically restart process
• provide a REPL with start/stop/restart for each process

Forkie solves the "how do we deal with graceful start an stops in our node.js application?".

See the examples.

master API

A forkie master will forks all the workers you give to him. Workers must implement the [worker API](#worker API).

var workers = [
  'job-worker.js',
  'job-worker2.js',
  'job-worker2.js',
  require('cluster'),
  require('cluster')
];

// default options
var opts = {
  start: process.nextTick,  // executes before starting processes
  stop: process.nextTick,   // executes before stopping processes
  killTimeout: 5000         // how much `ms` to wait before killing a process that does not exits by itself
  restarts: false           // how many times should we restart a failed process, put `Infinity` or -1 for infinite restarts
  repl: false               // should we start a repl? See repl documentation
};

var master = require('forkie').master(workers, opts);

master.on('worker stopped', function(metas) {
  console.log(metas.title); // worker title, see worker API
  console.log(metas.code)   // exit code
  console.log(metas.signal) // exit signal, should be SIGKILL when killTimeout occurs
});

// on ready and started events, you get the `{ title: 'worker title' }`
master.on('worker ready', console.log);
master.on('worker started', console.log);

// this will be called before
// starting workers
function startMaster(cb) {
  setTimeout(cb, 3000);
}

// this will be called before
// stopping workers
function stopMaster(cb) {
  setTimeout(cb, 1500);
}

REPL

Forkie can provide you a handy REPL to start/stop/restart workers individually.

You can use all the options from dshaw/replify.

See the many usable clients on to connect to the REPL.

Here's an example from examples/master-repl.js using dshaw/repl-client:

worker API

The worker API can be used in conjunction with a master process (master-worker) or as a standalone worker.

var title = 'I am a worker';

var opts = {
  start: startWorker,
  stop: stopWorker
};

var worker = require('forkie').worker(title, opts);

worker.on('stopped', console.log);
worker.on('started', console.log);
worker.on('ready', console.log);

function startWorker(cb) {
  setTimeout(cb, 3000);
}

function stopWorker(cb) {
  setTimeout(cb, 1500);
}

By default, as soon as master receives a SIGTERM or SIGINT, all workers are asked to stop.

.working(true/false)

To inform forkie that you are dealing with long asynchronous tasks and that you don't want to be interrupted, use worker.working(true).

For example, when using a work queue, before starting to work on a job, use worker.working(true), after dealing with a job, use worker.working(false).

See examples/job-worker.js for a more concrete example.

Graceful exit

Forkie will not call process.exit() for you. All you workers must terminate their respective connections and async loops in the stop method.

So that your process exits by itself.

When in a master-worker setup, your worker will be killed after killTimeout ms if it doesn't exits.

When in a standalone worker setup, your worker will not exits if you don't terminate your connections.