workforce/README.md

A cluster manager inspired by Learnboost's cluster.

 [![Build Status](https://secure.travis-ci.org/RedVentures/workforce.png?branch=master)](http://travis-ci.org/RedVentures/workforce)

# workforce

A simple wrapper around native cluster in spirit of the *original cluster*, [LearnBoost/cluster](https://github.com/learnboost/cluster).

## Installation

```shell
  $ npm install workforce
```

## Example

```javascript
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*.

```javascript
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"*.

```javascript
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*.

```javascript
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*.

```javascript
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.

```javascript
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.*

```javascript
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*

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

*my-server.js*

```javascript
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](https://github.com/learnboost/cluster) (everything)
  - [learnboost/up](https://github.com/learnboost/up) (gracefull reloading)
  - [issacs/cluster-master](https://github.com/isaacs/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.