@ladjs/graceful

@ladjs/graceful

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:

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).

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)
  // <https://github.com/expressjs/express>
  // <https://github.com/koajs/koa>
  // <https://github.com/fastify/fastify>
  //
  servers: [],

  // bree clients
  // <https://github.com/breejs/bree>
  brees: [],

  // redis clients
  // <https://github.com/luin/ioredis>
  // <https://github.com/redis/node-redis>
  redisClients: [],

  // mongoose clients
  // <https://github.com/Automattic/mongoose>
  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.

Express

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

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

Koa

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();

Fastify

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();

Other

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 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). 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). If you pass a false value then this property will not get populated.

Examples

You can refer Forward Email for more complex usage:

• API - https://github.com/forwardemail/forwardemail.net/blob/master/api.js
• Web - https://github.com/forwardemail/forwardemail.net/blob/master/web.js
• Bree - https://github.com/forwardemail/forwardemail.net/blob/master/bree.js
• Proxy - https://github.com/forwardemail/forwardemail.net/blob/master/proxy.js

Additionally you can also refer to Lad usage:

• API - https://github.com/ladjs/lad/blob/master/template/api.js
• Web - https://github.com/ladjs/lad/blob/master/template/web.js
• Bree - https://github.com/ladjs/lad/blob/master/template/bree.js
• Proxy - https://github.com/ladjs/lad/blob/master/template/proxy.js

You can also read more about Bree at https://github.com/breejs/bree.

Contributors

Name	Website
Nick Baugh	http://niftylettuce.com/
Felix Mosheev	https://github.com/felixmosh
Nicholai Nissen	https://nicholai.dev
Spencer Snyder	https://spencersnyder.io

License

MIT © Nick Baugh