README

ib-http-graceful-shutdown

Fork of "http-graceful-shutdown"

Version 1.0

can be used with [express][express-url], [koa][koa-url], [fastify][fastify-url], native node [http][http-url], [http2][http2-url] ... see examples
simple to use
configurable to your needs
add your own cleanup function

Features

ib-http-graceful-shutdown manages a secure and save shutdown of your http server application:

tracks all connections
stops the server from accepting new connections on shutdown
graceful communication to all connected clients of server intention to shutdown
immediately destroys all sockets without an attached HTTP request
properly handles all HTTP and HTTPS connections
possibility to define cleanup functions (e.g. closing DB connections)
preShutdown function if you need to have all HTTP sockets available and untouched
choose between shutting down by function call or triggered by SIGINT, SIGTERM, ...
choose between final forcefull process termination node.js (process.exit) or clearing event loop (options).

Quick Start

Installation

$ npm install ib-http-graceful-shutdown

Basic Usage

const gracefulShutdown = require('ib-http-graceful-shutdown');
...
// app: can be http, https, express, koa, fastity, ...
server = app.listen(...);
...

// this enables the graceful shutdown
gracefulShutdown(server);

Explanation

Functionality

                                                                    PARENT Process (e.g. nodemon, shell, kubernetes, ...)
─────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────
                         │ Signal (SIGINT, SIGTERM, ...)
                         │
                         │
           (1)       (2) v                                                 NODE SERVER (HTTP, Express, koa, fastity, ...)
    ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇
           │             │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │ <─ shutdown procedure
           │             │ shutdown initiated           │ │                                            │
           │             │                              │ │                                            │
           │             │                              │ │    (8) shutdown function    (9) finally fn │
           │             │ ▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄             │ │ ▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄▄▄▄▄▄ │
           │             └ (3)          (4) close       │ └ (7) destroy                                │
           │               preShutdown  idle sockets    │   remaining sockets                          │
           │                                            │                                              │ (10)
     serve │      serving req. (open connection)        │          (5)                                 └ SERVER terminated
        ▄▄▄│      ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄┤           ^ blocked
        ^  │      ^  last request before                │           │
        │  │      │  receiving shutdown signal          │           │
        │  │      │                                     │           │
        │  │      │                                     │           │
        │  │      │                                     │           │
        │  │      │ Long request                        │           │
Request │  V Resp │                                     V Resp.     │
        │         │                                                 │                                                   CLIENT
────────┴─────────┴─────────────────────────────────────────────────┴─────────────────────────────────────────────────────────

usually your NODE http server (the black bar in the middle) replies to client requests and sends responses
if your server receives a termination signal (e.g. SIGINT - Ctrl-C) from its parent, ib-http-graceful-shutdown starts the shutdown procedure
first ib-http-graceful-shutdown will run the "preShutdown" (async) function. Place your own function here (passed to the options object), if you need to have all HTTP sockets available and untouched.
then alle empty connections are closed and destroyed and
ib-http-graceful-shutdown will block any new requests
If possible, ib-http-graceful-shutdown communicates to the clients that the server is about to close (connection close header)
ib-http-graceful-shutdown now tries to wait till all sockets are finished, then destroys the all remaining sockets
now it is time to run the "onShutdown" (async) function (if such a function is passed to the options object)
as soon as this onShutdown function has ended, the "finally" (sync) function is executed (if passed to the options)
now the event loop cleared up OR process.exit() is triggered (can be defined in the options) and the server process ends.

Options

option	default	Comments
timeout	30000	timeout till forced shutdown (in milli seconds)
signals	'SIGINT SIGTERM'	define the signals, that should be handled (separated by SPACE)
development	false	if set to true, no graceful shutdown is proceeded to speed up dev-process
preShutdown	-	not time consuming callback function. Needs to return a promise. Here all HTTP sockets are still available and untouched
onShutdown	-	not time consuming callback function. Needs to return a promise.
forceExit	true	force process.exit - otherwise just let event loop clear
finally	-	small, not time consuming function, that will be handled at the end of the shutdown (not in dev-mode)

Option Explanation

timeout: You can define the maximum time that the shutdown process may take (timeout option). If after this time, connections are still open or the shutdown process is still running, then the remaining connections will be forcibly closed and the server process is terminated.
signals Here you can define which signals can trigger the shutdown process (SIGINT, SIGTERM, SIGKILL, SIGHUP, SIGUSR2, ...)
development If true, the shutdown process is much shorter, because it just terminates the server, ignoring open connections, shutdown function, finally function ...
preShutdown Place your own (not time consuming) callback function here, if you need to have all HTTP sockets available and untouched during cleanup. Needs to return a promise. (async). If you add an input parameter to your cleanup function (optional), the SIGNAL type that caused the shutdown is passed to your cleanup function. See example.
onShutdown place your (not time consuming) callback function, that will handle your additional cleanup things (e.g. close DB connections). Needs to return a promise. (async). If you add an input parameter to your cleanup function (optional), the SIGNAL type that caused the shutdown is passed to your cleanup function. See example.
finally here you can place a small (not time consuming) function, that will be handled at the end of the shutdown e.g. for logging of shutdown. (sync)
forceExit force process.exit() at the end oof the shutdown process - otherwise just let event loop clear

Advanced Options Example

You can pass an options-object to specify your specific options for the graceful shutdown

The following example uses all possible options:

const gracefulShutdown = require('ib-http-graceful-shutdown');
...
// app: can be http, https, express, koa, fastity, ...
server = app.listen(...);
...

// your personal cleanup function
// - must return a promise
// - the input parameter is optional (only needed if you want to
//   access the signal type inside this function)
// - this function here in this example takes one second to complete
function shutdownFunction(signal) {
  return new Promise((resolve) => {
    console.log('... called signal: ' + signal);
    console.log('... in cleanup')
    setTimeout(function() {
      console.log('... cleanup finished');
      resolve();
    }, 1000)
  });
}

// finally function
// -- sync function
// -- should be very short (not time consuming)
function finalFunction() {
  console.log('Server gracefulls shutted down.....')
}

// this enables the graceful shutdown with advanced options
gracefulShutdown(server,
  {
    signals: 'SIGINT SIGTERM',
    timeout: 10000,                   // timeout: 10 secs
    development: false,               // not in dev mode
    forceExit: true,                  // triggers process.exit() at the end of shutdown process
    preShutdown: preShutdownFunction, // needed operation before httpConnections are shutted down
    onShutdown: shutdownFunction,     // shutdown function (async) - e.g. for cleanup DB, ...
    finally: finalFunction            // finally function (sync) - e.g. for logging
  }
);

Trigger shutdown manually

You can now trigger gracefulShutdown programatically (e.g. for tests) like so:

let shutdown
beforeAll(() => {
  shutdown = gracefulShutdown(...)
})

afterAll(async () => {
  await shutdown()
})

Do not force process.exit()

With the forceExit option, you can define how your node server process ends: when setting forceExit to false, you just let the event loop clear and then the proccess ends automatically:

const gracefulShutdown = require('ib-http-graceful-shutdown');
...
// app: can be http, https, express, koa, fastity, ...
server = app.listen(...);
...

// enable graceful shutdown with options:
// this option lets the event loop clear to end your node server
// no explicit process.exit() will be triggered.

gracefulShutdown(server, {
  forceExit: false
});

If you want an explicit process.exit() at the end, set forceExit to true (which is the default).

Debug

If you want to get debug notes ([debug][debug-url] is a dependency of this module), just set the DEBUG environment variable to enable debugging:

export DEBUG=ib-http-graceful-shutdown

OR on Windows:

set DEBUG=ib-http-graceful-shutdown

Examples

You can find examples how to use ib-http-graceful-shutdown with Express, Koa, http, http2, fastify in the examples directory. To run the examples, be sure to install debug and express, koa or fastify.

npm install debug express koa fastify

Usage no npm install needed!