atsuya / qilin

Unicorn-like monitoring for node.js

Qilin

NOTE: THIS PROJECT IS HEAVILY IN DEVELOPMENT, EXPERIMENTAL AND UNSTABLE

Unicorn-like monitoring for node.js.

What is it?

Unicorn is a great HTTP server that allows you to do no downtime deployment. It also allows you to run multiple rack applications on the same IP/port combination with child processes it spawns, and it automatically resurrects the process it dies. That is awesome and Qilin is that for node.js.

How does it work?

The basics are the same as unicorn and you can find articles that talks about its architectures here and there. The main difference is that most of good stuff is coming from cluster module.

Cluster module is like your boss and it monitors what happens in its workers. For example, when http server listens on some port on one of worker processes, then the boss (master process) looks at what port it is about to listen. If it already has a handler that matches with the port, then it gives the worker the handler that is already being open. This means that if multiple workers listen on the same port, they all share the handler. This way, we can let OS do load balancing. If you want to know more about it, you can just read the cluster documentation. It also provides you with a way for master process and workers to communicate. It will be notified when certain worker died and things in that sort.

So basically, all qilin does is leveraging cluster module to manage workers.

How to gracefully restart?

Just like unicorn, just send SIGUSR2 signal to the master process. All connections that are currently processed will stay connected until they go through, and new workers will be spawned and handling new requests. If the file specified to start qilin has been modified, the workers will load the modified one.

Install

$ npm install -g qilin

examples

$ qilin -w 3 /path/to/your/node/file.js

The example above will start /path/to/your/node/file.js with 3 workers.

If you want to use qilin programmatically, then you can do this:

var Qilin = require('qilin');
var qilin = new Qilin(
    {
        exec: '/path/to/your/nodejs/file.js'
      , args: []
      , silent: false
    }
  , {
        workers: 3
    }
);
qilin.start(function() {
  console.log('Qilin is started!');
});

This example will start /path/to/your/nodejs/file.js with 3 workers.

Methods

Will do later...

License

MIT

qilin's Issues

write documentations

do it

Set a process name to master process

possible issue with USR2

qilin is great thank you for creating this.

In order for graceful restarts to work for me with qilin, I had to add the following to my worker.js file:

const cluster = require('cluster');

if (cluster.isWorker) {
cluster.worker.on('disconnect', function(code, signal) {
setTimeout(process.exit.bind(process), 1000);
});
}
}

It could be my workers have additional connections open and so, I need to listen for the disconnect signal from the parent process otherwise the worker.js process will be a zoombie processes.

Not sure if there is an interface that qilin could provide to make this easier without having to use the cluster interface directly, but seems to work for my purpose..

Allow graceful shutdown

Not just graceful restart (or reload), but graceful shutdown should be supported.

Rename to kirin

Because it has to be badass.

"the Qilin is ranked as the third most powerful creature (after the dragon and phoenix), but in Japan, the Kirin occupies the top spot"

https://en.wikipedia.org/wiki/Qilin