Hapi-pulse NPM

Introduction

A hapi plugin that gracefully stops the hapi server on SIGINT and SIGTERM and your custom signals.

hapi-pulse works great with PM2 and other Node.js process manager to accomplish zero-downtime deployments!

This serves existing requests before closing the connection and stopping the hapi server process. It uses hapi’s server.stop() method to close connections properly.

Requirements

hapi v19 (or later) and Node.js v12 (or newer)

This plugin requires hapi v19 (or later) and Node.js v12 or newer.

Compatibility

Major Release	hapi.js version	Node.js version
`v3`	`>=17 hapi`	`>=12`
`v2`	`>=17 hapi`	`>=8`

Installation

Add hapi-pulse as a dependency to your project:

npm i hapi-pulse

Usage

The most straight forward way to register the hapi-pulse plugin:

await server.register({
  plugin: require('hapi-pulse'),
  options: {
    // any option that is supported by hapi's "server.stop()"
    timeout: 15000,

    // plugin specific options
    logger: console,
    signals: ['SIGINT'],
    postServerStop: async function () {
      // await Database.close()
    }
  }
})

Plugin Registration Options

hapi-pulse passes the options through to hapi’s server.stop(options). Customize the behavior of server.stop(), like the timeout before forcefully stopping the process.

Additionally, you can pass along the following options:

logger: (Object), default: console — in case of an error, hapi-pulse logs the error with logger.error('message', error)
signals: (Array), default: ['SIGINT', 'SIGTERM'] — use this signals option to customize the events on which hapi-pulse will stop the server
preServerStop: (Function), default: Promise.resolve — an async function that runs before server.stop()
postServerStop: (Function), default: Promise.resolve — an async function that runs after server.stop()
preShutdown: (Function), default: Promise.resolve — an async function that runs after postServerStop() and before process.exit
timeout: (int), default: 5000 (5 seconds) — the timeout existing connections should be closed until they are forcefully interrupted. This option is passed through to hapi’s server.stop()

Example

await server.register({
  plugin: require('hapi-pulse'),
  options: {
    timeout: 25 * 1000,
    logger: console,
    signals: ['SIGINT', 'SIGTERM'],
    preServerStop: async function () {
      // this runs before server.stop()
    },
    postServerStop: async function () {
      // this runs after server.stop()
      // e.g., await Database.close()
    },
    preShutdown: async function () {
      // this runs after postServerStop() and before process.exit
    }
  }
})

// went smooth like chocolate :)