mathrawkaexpress-graceful-exit
Gracefully decline new requests while shutting down your application. A component that helps support zero downtime deploys for Node.js with Express.
The project was originally developed for Express v3.X, but is used in production with Express v4.X. Please write up an issue or submit a PR if you find bugs using express-graceful-exit with Express v4.X and higher.
Installation
$ cd /path/to/your/project
$ npm install express-graceful-exitCompatibility
v0.X.X versions are backwards API compatible, with these minor behavior changes:
- Process exit is called in a
setTimeoutblock from v0.2.0 forward, so the timing is slightly different between v0.1.0 to v0.2.x+. - After exit was triggered, incoming requests were mismanaged prior to v0.5.0.
As of v0.5.0 incoming requests are dropped cleanly by default, with new options such as responding with a custom error and/or performing one last request per connection.
Usage
The following two components must both be used to enable clean server shutdown, where incoming requests are gracefully declined.
There are multiple exit options for how in-flight requests are handled, ranging from forced exist after a specified deadline to waiting indefinitely for processing to complete.
middleware
This middleware should be the very first middleware that gets setup with your Express app.
var express = require('express');
var app = express();
var gracefulExit = require('express-graceful-exit');
var server = app.listen(port)
gracefulExit.init(server) // use init() if configured to exit the process after timeout
app.use(gracefulExit.middleware(app));gracefulExitHandler
This function tells express to accept no new requests and gracefully closes the http server. It can be attached to a signal, or used as a normal function call if another tool is used (such as naught).
// Example for naught
process.on('message', function(message) {
if (message === 'shutdown') {
gracefulExit.gracefulExitHandler(app, server, {
<see options below>
});
}
});Options
Middleware
There are no options available currently.
Exit Handler
The following options are available:
| Option | Description | Default |
|---|---|---|
| log | Print status messages and errors to the logger | false |
| logger | Function that accepts a string to output a log message | console.log |
| callback | Optional function that is called with the exit status code once express has shutdown, gracefully or not Use in conjunction with exitProcess: false when the caller handles process shutdown |
no-op |
| performLastRequest | Process the first request received per connection after exit starts, and include a connection close header in the response for the caller and/or load balancer. The current default is false, but will default to true in the next major release, false is deprecated as of v0.5.0 |
false, true is recommended |
| errorDuringExit | When requests are refused during graceful exit, respond with an error instead of silently dropping them. The current default is false, but will default to true in the next major release, false is deprecated as of v0.5.0 |
false, true is recommended |
| getRejectionError | Function returning rejection error for incoming requests during graceful exit | function () { return new Error('Server unavailable, no new requests accepted during shutdown') } |
| exitProcess | If true, the module calls process.exit() when express has shutdown, gracefully or not |
true |
| exitDelay | Wait timer duration in the final internal callback (triggered either by gracefulExitHandler or the hard exit handler) if exitProcess: true |
10ms |
| suicideTimeout | How long to wait before giving up on graceful shutdown, then returns exit code of 1 | 2m 10s (130s) |
| socketio | An instance of socket.io, used to close all open connections after timeout |
none |
| force | Instructs the module to forcibly close sockets once the suicide timeout elapses. For this option to work you must call gracefulExit.init(server) when initializing the HTTP server |
false |
Details
To gracefully exit this module does the following things:
- Closes the http server so no new connections are accepted
- Sets connection close header for Keep-Alive connections, if configured for responses
IferrorDuringExitis true, HTTP status code 502 is returned by default, so nginx, ELB, etc will resend to an active server
IferrorDuringExitand/orperformLastRequestare set to true, a response is sent with aConnection: closeheader - If a socket.io instance is passed in the options, all connected clients are immediately disconnected (socket.io v0.X through v1.4.x support)
The client should have code to reconnect on disconnect - Once the server fully disconnects or the hard exit timer runs
- If all in-flight requests have resolved and/or disconnected, the exit handler returns
0 - OR if any connections remain after
suicideTimeoutms, the handler returns1
- If all in-flight requests have resolved and/or disconnected, the exit handler returns
- In either case, if exitProcess is set to true the hard exit handler waits exitDelay ms and calls
process.exit(x), this allows the logger time to flush and the app's callback to complete, if any
Zero Downtime Deploys
This module does not give you zero downtime deploys on its own. It enables the http server to exit gracefully, which when used with a module like naught can provide zero downtime deploys.
Author: Jon Keating
This module was originally developed for Frafty (formerly www.frafty.com), a Daily Fantasy Sports site.