Nocturnal Pajama Mutants
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    clusterflock Build Status

    flocking birds

    clusterflock is a simple clustering HTTP server for Node. It accepts a single request handler and a hash of options. The goal of clusterflock is to eliminate my own repeated need for a simple clustering server that implements graceful worker shutdown and re-forking of dead workers.

    This package is deprecated. I wrote a much more well-tested version without the known bugs of clusterflock called teamster.


    $ npm install clusterflock --save


    By default, clusterflock will fork the number of workers equal to os.cpus().length. When it receives a SIGINT or SIGTERM signal, it will begin attempting to shut down gracefully by ceasing to receive requests and closing all servers after existing requests have been completed.

    The simplest use case of clusterflock is to pass it a single request handler function:

    var clusterflock = require('clusterflock');
    clusterflock(function (req, res) {

    Since clusterflock essentially just calls http.createServer in the worker process, anything that can be normally passed to that function can be passed to the clusterflock main function, including express apps:

    var clusterflock = require('clusterflock'),
        express      = require('express'),
        app          = express();
    app.use(express.bodyParser()); // &c. 

    Worker Re-forking

    When a worker disconnects, the master checks the value of its suicide attribute. If that value is true, master does nothing. If that value is not true (i.e. the worker died/was killed unintentionally), the master forks a new worker.


    The clusterflock function accepts an options object:

    var clusterflock = require('clusterflock'),
        app          = require('./lib/app');
    clusterflock(app, {
      numWorkers: 1,
      port      : 3000,
      timeout   : 5000
    Name Type(s) Default Description
    numWorkers Number os.cpus().length number of worker processes to fork
    port Number, String process.env.PORT || 5000 port the workers will listen on
    timeout Number 1000 amount of time after receiving a graceful shutdown signal that the master will immediately kill workers


    clusterflock responds to signals. heroku, for example, sends SIGTERM to stop and restart dynos, which will cause clusterflock to initiate a graceful shutdown. SIGINT, on the other hand, will force clusterflock to shut down immediately.

    Signal Behavior
    SIGTTIN Fork an additonal worker
    SIGTTOU Disconnect the least-recently forked worker
    SIGINT Kill master process (and therefore workers) immediately.
    SIGTERM Forward myself SIGQUIT.
    SIGQUIT Attempt a graceful shutdown (stop serving requests, serve remaining requests, and shut down).


    To run the tests:

    $ npm test


    1. Fork it.
    2. Create a branch (git checkout -b my-clusterflock)
    3. Commit your changes (git commit -am "add unicorns")
    4. Push to the branch (git push origin my-clusterflock)
    5. Open a Pull Request


    The photo in this readme is by Flickr user Eugene Zemlyanskiy. It has a CC BY 2.0 license.


    npm i clusterflock

    Downloadslast 7 days







    last publish


    • avatar