Various-cluster NPM

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.