@ladjs/graceful

![license]()

> Gracefully exit HTTP servers (Express/Koa/Fastify/etc), databases (Mongo/Mongoose), Redis clients, [Bree][] job schedulers, and custom handlers.

Table of Contents

* Install
* Usage
* Express
* Koa
* Fastify
* Other
* Instance Options
* Examples
* Contributors
* License

Install

[npm][]:

``sh
npm install @ladjs/graceful
`

Usage

See the Express, Koa, Fastify, or Other code snippet examples and Instance Options below.

You can pass Instance Options to customize your graceful handler (e.g. if you have more than one server, or wish to close both a Redis connection and a server at the same time).

`js
const Graceful = require('@ladjs/graceful');

//
// ...
//

//
// see Instance Options in the README below and examples for different projects (e.g. Koa or Express)
//
const graceful = new Graceful({
//
// http or net servers
// (this supports Express/Koa/Fastify/etc)
// (basically anything created with http.createServer or net.createServer)
//
//
//
//
servers: [],

// bree clients
//
brees: [],

// redis clients
//
//
redisClients: [],

// mongoose clients
//
mongooses: [],

// custom handlers to invoke upon shutdown
customHandlers: [],

// logger
logger: console,

// how long to wait in ms for exit to finish
timeoutMs: 5000,

// options to pass to lil-http-terminator to override defaults
lilHttpTerminator: {},

//
// appends a true boolean value to a property of this name in the logger meta object
// (this is useful for Cabin/Axe as it will prevent a log from being created in MongoDB)
// (and instead of having a DB log created upon graceful exit, it will simply log to console)
// (defer to the Forward Email codebase, specifically the logger helper)
//
// NOTE: if you set this to false then this will be ignored and no meta property will be populated
//
ignoreHook: 'ignore_hook',

//
// appends a true boolean value to a property of this name in the logger meta object
// (this is useful for Cabin/Axe as it will prevent the meta object from being outputted to the logger)
//
hideMeta: 'hide_meta'
});

//
// NOTE: YOU MUST INVOKE graceful.listen() IN ORDER FOR THIS TO WORK!
//
graceful.listen();
`

Using this package will bind process event listeners when graceful.listen() is called:

* process.on('warning') - will output via config.logger.warn
process.on('unhandledRejection') - bubbles up to uncaughtException (will output via config.logger.error and process.exit(1) (does not exit gracefully*)
process.once('uncaughtException') - will output via config.logger.error and process.exit(1) (does not exit gracefully*)
* process.on('message') - support Windows (e.g. signals not available) and listen for message of shutdown and then exit gracefully
* process.once('SIGTERM') - will exit gracefully
* process.once('SIGHUP') - will exit gracefully
* process.once('SIGINT') - will exit gracefully

This package also prevents multiple process/SIG events from triggering multiple graceful exits. Only one graceful exit can occur at a time.

For servers passed, we use [lil-http-terminator][] under the hood. Default configuration options can be overridden by passing a lilHttpTerminator configuration object. See index.js for more insight.

$3

`js
const express = require('express');
const Graceful = require('@ladjs/graceful');

const app = express();
const server = app.listen();
const graceful = new Graceful({ servers: [server] });
graceful.listen();
`

$3

`js
const Koa = require('koa');
const Graceful = require('@ladjs/graceful');

const app = new Koa();
const server = app.listen();
const graceful = new Graceful({ servers: [server] });
graceful.listen();
`

$3

`js
const fastify = require('fastify');
const Graceful = require('@ladjs/graceful');

const app = fastify();
app.listen();

//
// NOTE: @ladjs/graceful is smart and detects app.server automatically
//
const graceful = new Graceful({ servers: [app] });
graceful.listen();
`

$3

This package works with any server created with http.createServer or net.createServer (Node's internal HTTP and Net packages).

Please defer to the test folder files for example usage.

Instance Options

Here is the full list of options and their defaults. See index.js for more insight if necessary.

| Property | Type | Default Value | Description |
| ------------------- | ------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| servers | Array | [] | An array of HTTP or NET servers to gracefully close on exit |
| brees | Array | [] | An array of [Bree][] instances to gracefully exit |
| redisClients | Array | [] | An array of Redis client instances to gracefully exit |
| mongooses | Array | [] | An array of Mongoose connections to gracefully exit |
| customHandlers | Array | [] | An array of functions (custom handlers) to invoke upon graceful exit |
| logger | Object | console | This is the default logger. We recommend using [Cabin][cabin] instead of using console as your default logger. Set this value to false to disable logging entirely (uses noop function) |
| timeoutMs | Number | 5000 | A number in milliseconds for how long to wait to gracefully exit |
| lilHttpTerminator | Object | {} | An object of options to pass to lil-http-terminator to override default options provided |
| ignoreHook | String or false Boolean | "ignore_hook" | Appends a true boolean property to a property with this value in logs, e.g. console.log('graceful exiting', { ignore_hook: true }); which is useful for preventing logs from being written to a database in hooks (this is meant for usage with [Cabin][] and [Axe][] and made for [Forward Email][forward-email]). If you pass a false value then this property will not get populated. |
| hideMeta | String or false Boolean | "hide_meta" | Appends a true boolean property to a property with this value in logs, e.g. console.log('graceful exiting', { hide_meta: true }); which is useful for preventing metadata object from being invoked as the second argument (this is meant for usage with [Cabin][] and [Axe][] and made for [Forward Email][forward-email]). If you pass a false` value then this property will not get populated. |

Examples

You can refer Forward Email for more complex usage:

* API -
* Web -
* Bree -
* Proxy -

Additionally you can also refer to [Lad][] usage:

* API -
* Web -
* Bree -
* Proxy -

You can also read more about Bree at .

Contributors

| Name | Website |
| ------------------- | ------------------------------ |
| Nick Baugh | |
| Felix Mosheev | |
| Nicholai Nissen | |
| Spencer Snyder | |

License

MIT © Nick Baugh

##

[npm]: https://www.npmjs.com/

[lad]: https://lad.js.org

[lil-http-terminator]: https://github.com/flash-oss/lil-http-terminator

[cabin]: https://cabinjs.com

[bree]: https://jobscheduler.net

[axe]: https://github.com/cabinjs/axe

[forward-email]: https://github.com/forwardemail