handle-quit

Support graceful stop in your app

Respond to shutdown signals, so a process manager can reload your app without dropping any connections.

Why?

• Friendly to your users.
• Easy to use and reason about.
• Helps you do easy zero downtime deployments.

Install

npm install handle-quit --save

Usage

Get it into your program.

const handleQuit = require('handle-quit');

Make sure your program shuts down gracefully or quickly, as necessary.

handleQuit(() => {
    server.close();
});

Note that calling process.exit() is discouraged. Instead, you should close any server and database connections and let Node exit on its own, which it does automatically when it has no more work left to do.

If you are worried about the process hanging and never cleanly exiting, you are encouraged to use your framework's stop timeout.

Use with PM2

To achieve zero downtime deployments, PM2 needs to shutdown your app without dropping any connections. It sends a SIGINT signal to trigger the shutdown process. However, by default, Node reacts to this by exiting immediately, and thus in-progress connections may be dropped.

These problems can be fixed by using handleQuit() in the main entry of your CLI or server, as shown above, to override the default SIGINT behavior and deny new connections on the first SIGINT, while allowing any in-progress connections to finish. This is known as graceful stop.

PM2 waits for apps that gracefully stop to quit before replacing them with a new deployment when using pm2 reload.

$ pm2 start app.js --kill-timeout 6000

Just in case something goes wrong, --kill-timeout tells PM2 how long it should wait for the process to exit before considering the process hung / frozen, in which case it will force kill the process. You should ensure that --kill-timeout is greater than or equal to any stop timeouts used in your app.

To support graceful start, see app-ready.

API

handleQuit(listener)

Listens for POSIX signals (SIGINTand SIGTERM) and calls the listener function on the first signal to perform a graceful shutdown. Calls process.exit() with an appropriate error code on any further signals that are received to perform an ungraceful shutdown. Relevant messages are also printed to the console.

listener

Type: function

A function that will gracefully shutdown your program. A common example is Server#close().

Related

• app-ready - Support graceful start in your app

Contributing

See our contributing guidelines for more details.

1. Fork it.
2. Make a feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request.

License

MPL-2.0 © Seth Holladay

Go make something, dang it.