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.

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.

forkie start workflow

All messages are sent with IPC

• master calls user provided start(cb) function
• master forks every asked module (either filename or cluster.fork())
• workers sends a { graceful: { status: 'ready' } } message, received by master
• master sends every fork a { graceful: { action: 'start' } }, received by workers
• workers calls user provided start(cb) function
• workers sends a { graceful: { status: 'started' } }, received by master
• master emits a { graceful: { status: 'started' } } event

forkie stop workflow

• master receives SIGTERM
• master calls user provided stop(cb) function
• master sends a { graceful: { action: 'stop' } }, received by workers
• workers calls user provided stop(cb) function
• workers sends a { graceful: { status: 'stopped' } }, received by master
• master emits a { graceful: { status: 'stopped' } } event

If worker was working (i.e. .working(true) was called last), it will wait for .working(false) to be called.

If worker did not gracefully exits before killTimeout, it will be .kill('SIGKILL')ed.

If master does not exits by itself, it will stay online.

Master and worker exits are up to you, you must close all connections and timers for process to exits gracefully.

master failures

When master fails, all forked workers will automatically exit because they listen to disconnect event.

key differences with isaacs/cluster-master

• no resize()
• provide a graceful stop API through [.working(true/false)](#.working(true/false)
• fully tested

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.