Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →

@godaddy/terminus

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@godaddy/terminus

[![Join Slack](https://img.shields.io/badge/Join%20us%20on-Slack-e01563.svg)](https://godaddy-oss-slack.herokuapp.com/)

2.4.1
Source
npm

Version published: 6 years ago

Weekly downloads: 177K; decreased by-6.53%

Maintainers: 6

Weekly downloads

Created: 7 years ago

What is @godaddy/terminus?

@godaddy/terminus is a Node.js package that helps manage graceful shutdowns and health checks for your applications. It ensures that your application can handle termination signals properly, allowing for clean shutdowns and preventing data corruption or loss. It also provides endpoints for health checks to monitor the application's status.

What are @godaddy/terminus's main functionalities?

Graceful Shutdown

This feature allows the application to handle termination signals gracefully. When a termination signal (e.g., SIGINT) is received, the `onSignal` function is called to perform any necessary cleanup before the server shuts down.

const http = require('http');
const { createTerminus } = require('@godaddy/terminus');

const server = http.createServer((req, res) => {
  res.end('Hello world!');
});

function onSignal() {
  console.log('Server is starting cleanup');
  // start cleanup of resource, like databases or file descriptors
  return Promise.resolve();
}

function onShutdown() {
  console.log('Cleanup finished, server is shutting down');
}

createTerminus(server, {
  signal: 'SIGINT',
  onSignal,
  onShutdown
});

server.listen(3000);

Health Checks

This feature provides a health check endpoint that can be used to monitor the application's status. The `onHealthCheck` function can include logic to determine if the application is healthy and return a promise that resolves if it is.

const http = require('http');
const { createTerminus } = require('@godaddy/terminus');

const server = http.createServer((req, res) => {
  res.end('Hello world!');
});

function onHealthCheck() {
  return Promise.resolve(); // optionally include a health check here
}

createTerminus(server, {
  healthChecks: {
    '/healthcheck': onHealthCheck
  }
});

server.listen(3000);

Other packages similar to @godaddy/terminus

terminus

Adds graceful shutdown and Kubernetes readiness / liveness checks for any HTTP applications.

Installation

Install via npm:

$ npm i @godaddy/terminus --save

Usage

const http = require('http');
const terminus = require('@godaddy/terminus');

function onSignal () {
  console.log('server is starting cleanup');
  return Promise.all([
    // your clean logic, like closing database connections
  ]);
}

function onShutdown () {
  console.log('cleanup finished, server is shutting down');
}

function healthCheck () {
  return Promise.resolve(
    // optionally include a resolve value to be included as
    // info in the healthcheck response
  )
}

const server = http.createServer((request, response) => {
  response.end(
    `<html>
      <body>
        <h1>Hello, World!</h1>
       </body>
     </html>`
   );
})

const options = {
  // healtcheck options
  healthChecks: {
    '/healthcheck': healthCheck    // a promise returning function indicating service health
  },

  // cleanup options
  timeout: 1000,                   // [optional = 1000] number of milliseconds before forcefull exiting
  signal,                          // [optional = 'SIGTERM'] what signal to listen for relative to shutdown
  signals,                          // [optional = []] array of signals to listen for relative to shutdown
  beforeShutdown,                  // [optional] called before the HTTP server starts its shutdown
  onSignal,                        // [optional] cleanup function, returning a promise (used to be onSigterm)
  onShutdown,                      // [optional] called right before exiting

  // both
  logger                           // [optional] logger function to be called with errors
};

terminus(server, options);

server.listen(PORT || 3000);

With express

const http = require('http');
const app = express();

app.get('/', (req, res) => {
  res.send('ok');
});

const server = http.createServer(app);

const options = {
  // opts
};

terminus(server, options);

server.listen(PORT || 3000);

With koa

const http = require('http');
const Koa = require('koa');
const app = new Koa();

const server = http.createServer(app.callback());

const options = {
  // opts
};

terminus(server, options);

server.listen(PORT || 3000);

How to set Terminus up with Kubernetes?

When Kubernetes or a user deletes a Pod, Kubernetes will notify it and wait for gracePeriod seconds before killing it.

During that time window (30 seconds by default), the Pod is in the terminating state and will be removed from any Services by a controller. The Pod itself needs to catch the SIGTERM signal and start failing any readiness probes.

If the ingress controller you use route via the Service, it is not an issue for your case. At the time of this writing, we use the nginx ingress controller which routes traffic directly to the Pods.

During this time, it is possible that load-balancers (like the nginx ingress controller) don't remove the Pods "in time", and when the Pod dies, it kills live connections.

To make sure you don't lose any connections, we recommend delaying the shutdown with the number of milliseconds that's defined by the readiness probe in your deployment configuration. To help with this, terminus exposes an option called beforeShutdown that takes any Promise-returning function.

function beforeShutdown () {
  // given your readiness probes run every 5 second
  // may be worth using a bigger number so you won't
  // run into any race conditions
  return new Promise(resolve => {
    setTimeout(resolve, 5000)
  })
}
terminus(server, {
  beforeShutdown
})

Learn more

Limited Windows support

Due to inherent platform limitations, terminus has limited support for Windows. You can expect SIGINT to work, as well as SIGBREAK and to some extent SIGHUP. However SIGTERM will never work on Windows because killing a process in the task manager is unconditional, i.e., there's no way for an application to detect or prevent it. Here's some relevant documentation from libuv to learn more about what SIGINT, SIGBREAK etc. signify and what's supported on Windows - http://docs.libuv.org/en/v1.x/signal.html. Also, see https://nodejs.org/api/process.html#process_signal_events.

FAQs

What is @godaddy/terminus?

Is @godaddy/terminus popular?

Is @godaddy/terminus well maintained?

Package last updated on 09 Jul 2018

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install