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

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

• hapi tutorial series with 100+ tutorials

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 @futurestudio  ·  Twitter @futurestud_io