workforce

A simple wrapper around native cluster in spirit of the original cluster, LearnBoost/cluster.

Installation

  $ npm install workforce

Example

var workforce = require('workforce');
 
var manager = workforce('./path/to/server')
  .set('workers', 4)
  .set('title', 'awesome app')
  .set('restart threshold', '10s')
  .set('exit timeout', '5s');
 
manager.configure('development', function(){
  manager.use(workforce.watch(['./lib']));
});
 
manager.configure('production', function(){
  manager.set('working directory', '/var/run/awesome-app');
});
 
manager.listen(3000);

Configuration Options

workers

How many workers to fork. Defaults to the number of cpus.

manager.set('workers', 4);

title

The title prefix for the process titles. The master process will be appended "-master" and the workers will be appended "-worker". Defaults to "workforce".

manager.set('title', 'my-app');

exit timeout

How long to wait after a shutdown request has been made until the worker(s) are forcefully killed. You may use "ms" style arguments, via: '15s' or just milliseconds as normal. Defaults to 15000.

manager.set('exit timeout', '30s');

restart threshold

How long a worker must be up prior to an exit in order for it to be eligible for a worker replacement. You may use "ms" style arguments here too. Defaults to 5000.

manager.set('restart threshold', '5s');

working directory

The directory to change into prior to spawning the workers. Defaults to the current directory from where the process is started.

manager.set('working directory', '/home/foo/apps/awesome');

signals

The signals to listen for shutdown, restart and exit. By default SIGTERM will shutdown gracefully, SIGUSR2 will restart gracefully and SIGKILL will exit the workers and process immediately.

manager.set('signals', {
  'shutdown': 'SIGQUIT',
  'restart': 'SIGHUP',
  'exit': 'SIGINT'
});

Plugins

The plugin API is just your typical .use(fn) style interface. The bundled plugins are currently:

• watch Watches for file changes to reloads workers.
• NEEEED MORE PLUGINS!!!

Custom plugins are easy and are encouraged, if you think it would be handy for everyone, please submit a pull request so we can talk about having it in the core set of plugins. To write a plugin, the plugin should return a function that accepts the workforce instance, which it can use to hook into the "manager" process:

my-plugin.js

module.exports = function(options){
  options = options || {};
  return function(manager){
    // hook into manager process!
  };
}
};

my-server.js

var workforce = require('workforce');
var myplugin = require('./my-plugin');
 
workforce('./app')
  .use(myplugin({ foo: 'bar' }))
  .listen(3000);

Events

• listening All workers are ready and the application is ready for requests.
• worker A new worker was spawned.
• worker exit An existing worker exited.
• shutdown Master is shutting down.
• restart Master restarted the workers.
• exit Master is exiting imediatley along with the workers.

API

• workerforce(path)
• .use(fn)
• .set(key, value)
• .configure(env, fn)
• .listen(port, fn)
• .shutdown(fn)
• .restart(fn)
• .exit(fn)
• .fork(number)

Attribution

• learnboost/cluster (everything)
• learnboost/up (gracefull reloading)
• issacs/cluster-master (worker uptime)

License

Copyright 2012 Red Ventures

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with the License. You may obtain a copy of the License in the LICENSE file, or at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.