hapi plugin that gracefully stops the hapi server (for graceful process reloads, e.g. with PM2)
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
media
test
.eslintrc.json
.gitignore
.travis.yml
CHANGELOG.md
LICENSE
README.md
package.json

README.md

hapi-pulse logo

hapi plugin to gracefully stop your hapi server


Installation · Usage · Plugin Options



Build Status Known Vulnerabilities hapi-pulse Version

Follow @marcuspoehls for updates!


The Future Studio University supports development of this hapi plugin 🚀
Join the Future Studio University and Skyrocket in Node.js


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 v17 and Node.js v8 (or newer)

This plugin requires hapi v17 (or later) and uses async/await which requires Node.js v8 or newer.

Installation

Add hapi-pulse as a dependency to your project:

# NPM v5 users, this way is yours
npm i hapi-pulse

# you’re using NPM v4:
npm i -S 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 :)

Feature Requests

Do you miss a feature? Please don’t hesitate to create an issue with a short description of your desired addition to this plugin.

Links & Resources

Contributing

  1. Create a fork
  2. Create your feature branch: git checkout -b my-feature
  3. Commit your changes: git commit -am 'Add some feature'
  4. Push to the branch: git push origin my-new-feature
  5. Submit a pull request 🚀

License

MIT © Future Studio


futurestud.io  ·  GitHub @fs-opensource  ·  Twitter @futurestud_io