recluster
Clustering library with support for zero-downtime reloading
usage
If server.js is your regular http server (e.g. express), create
cluster.js and add:
var recluster = require('recluster'),
path = require('path');
var cluster = recluster(path.join(__dirname, 'server.js'));
cluster.run();
process.on('SIGUSR2', function() {
console.log('Got SIGUSR2, reloading cluster...');
cluster.reload();
});
console.log("spawned cluster, kill -s SIGUSR2", process.pid, "to reload");
then run it
node cluster.js
To hot-reload the server, simply run
kill -s SIGUSR2 <cluster_pid>
To find out which of the N (= number of cores by default) worker
instances you're running from inside server.js, you can use
process.env.WORKER_ID
which is zero-based i.e. 0 <= WORKER_ID < N
options
var cluster = recluster(file, opt)
where
file
Absolute path to the module that defines the server
opt.workers
Number of active workers (default = cores)
opt.timeout
Timeout to kill old workers after reload (seconds).
Defaults to 1 second in development, 1 hour in production.
opt.respawn
Minimum time between worker respawns when workers die (seconds)
opt.backoff
Maximum respawn time (reached via exponential backoff). Set to
0 or undefined to disable exponential backoff.
opt.readyWhen
Use 'listening' for servers (e.g. for express/connect http servers)
and 'started' for workers that are immediately ready.
If you want to manually tell recluster when the worker is ready to replace
older workers you can use {readyWhen: 'ready'}. Then, to signal readiness
from the worker use process.send({cmd: 'ready'})
opt.args
Array of arguments to pass to the worker
opt.log
Log various events to stdout. Currently only 'respawns' is supported.
Default: {respawns: true}
opt.logger
Which logger to use. Requires a console-compatible log method
Default: console
cluster
The returned object has the following methods:
cluster.run
Starts the cluster by running child processes
cluster.reload(cb)
Hot-reloads new code. some of the children will remain active
for opt.timeout seconds after reload
cluster.terminate(cb)
Terminates the entire cluster and removes all listeners.
cluster.activeWorkers()
Returns a hash of all worker slots (0 <= WORKER_ID < N). If a worker isn't
available at that slot, the value in the hash is null or undefined. Otherwise,
the value will be a worker object that is ready to serve requests.
cluster.workers()
Returns an array of all the workers, including those that are not
yet ready or those that will be replaced.
worker cleanup
A server worker can gracefully exit by cleaning up in the 'close' event
of its server:
server.on('close', function() {
// cleanup
});
Non-server workers can listen for the disconnect command and shut down
gracefully before the kill timeout:
process.on('message', function(m) {
if (m.cmd == 'disconnect') {
// cleanup
}
})
sticky sessions support
If you need sticky sessions e.g. for socket.io you can use the experimental
companion module sticky-listen, which implements an alternate
balancer that distributes the sockets based on the client IP (instead of the
regular round-robin one)
