various-cluster

easily create a mulit-cluster environment with different worker-types.

if you need some messaging inside your worker-types, take a look at msghub

Why another Cluster-Module?

This is a thin wrapper around the node native cluster module. There are currently no cluster-module-wrappers out there, which will spawn different Worker-Types which are not necessarly some http-servers. also this module enables you to take full control of all shutdown-mechanisms.

Getting Started

$ npm install various-cluster

require it in your code, and use it:

var variouscluster = require('various-cluster');

variouscluster.init({
  title: 'title of your master process',
  count: 2, // fallback for workers with no count defined
  shutdownTimout: 10000, // fallback for workers with no shutdownTimout defined
  workers: [
    {
      title: 'some-worker',  // title of this worker process
      exec: 'lib/some-worker.js', // location of your worker to be executed
      count: 1, // number of process to be spawned
      shutdownTimeout: 1000, // how long thisw workertype has time to shutdown
      config: {} // add some worker-config right here
    },
    {
      title: 'another-worker',
      exec: 'lib/another-worker.js',
      count: 1,
      shutdownTimeout: 1000,
      config: {}
    }
  ]
});

Documentation

api-docs: (open doc/index.html in your browser)

Creation

create your environment with including various-cluster in your code and call the init-method with your cluster-config (see more about config below!)

var yourConfig = {...};
var variouscluster = require('various-cluster');
variouscluster.init(yourConfig);

Workerspecific Config and Initialization

you can also pass a workerspecific config to your workers, so you dont need to read the config manually in every process.

just follow this pattern:

// in your master pass the workerconfig
variouscluster.init({
  ...
  workers: [
    {
      config: {
        "someKey": "someValue"
      }
    }
  ]
});

// and in your worker create a constructor function receiving this config
function SomeWorker(config) {
  this.config = config;
}

// and add an init-method to your Worker. This will instantly be called from various-cluster if present!
SomeWorker.prototype.init = function () {
  console.log(this.config.someKey); // will print 'someValue'
}

Logging

various cluster will try to use a logger-instance which is appended to the current process. this logger instance needs a 'crit' and a 'notice' method. if no process.logger is present, it just uses node.js native util.log()

// in your master create a logger:
process.logger = {
  crit: function (msg) {
    console.error(msg);
  },
  notice: function (msg) {
    console.log(msg);
  }
};

Shutdown

in every worker-process you can append a shutdown-Listener if you want to cleanup something in your application before shutting down:

process.on('shutdown', function (done) {
  // clean up here and call the done-callback when finished
  done();
});

if the cleanup takes longer than in your config defined, the process will be forced to exit!

uncaughtExceptions

per default if in the master an uncaught-exception happens, the whole application will gracefully shutdown.

if a worker has an uncaughtException, it depends on your configuration. per default this worker is gracefully shutdown and is reforked. if you configure a workertype with the config-parameter 'shutdownAll: true', the whole application will gracefully shutdown.

CONFIG which you provide in the init-method

config.title

process.title of the master process, DEFAULT: 'various-cluster-master'

config.count

workercount which should be used (if no count is given for a single worker this one is used), DEFAULT: os.cpus().length

config.shutdownTimeout

shutdownTimeout in ms (if no shutdownTimeout is given for a single worker this one is used), DEFAULT: 10000 ...

config.workers

an array with all workers (see more below)

config.workers[x].title

process.title of the worker process, DEFAULT: 'various-cluster-worker'

config.workers[x].exec

the local module-file which should be executed, DEFAULT: undefined

config.workers[x].count

workercount which should be used, DEFAULT: config.count

config.workers[x].shutdownTimeout

shutdownTimeout in ms, DEFAULT: config.shutdownTimeout

config.workers[x].shutdownAll

shutdown all workertypes and workers if this worker has an uncaught exception, DEFAULT: false

config.workers[x].config

your workerspecific config DEFAULT: undefined

Examples

see the examples-directory!

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Lint your code using Grunt

Release History

• 0.1.10 final working shutdown mechanism which respects all possibilties

• 0.1.9 fix second restart of workers who will just restart

• 0.1.8 log err.stack on exceptions

• 0.1.7 fix shutdown in workertype

• 0.1.6 rewrite shutdown mechanism

• 0.1.5 allow worker count to be 0

• 0.1.4 force exit when no shutdown-handler

• 0.1.4 force exit when no shutdown-handler

• 0.1.3 fix clean shutdown

• 0.1.2 better exception handling + cleaner shutdown

• 0.1.1 Added some keywords

• 0.1.0 Initial Release

Contributors

• Bastian "hereandnow" Behrens
• Gleb Kotov

License

Copyright (c) 2013 Valiton GmbH Licensed under the MIT license.