npmpackage.info

Gathering detailed insights and metrics for @godaddy/terminus

@godaddy/terminus

Graceful shutdown and Kubernetes readiness / liveness checks for any Node.js HTTP applications

4.12.1

1,848

MIT

JavaScript

32,801,529 4.8

Installations

npm install @godaddy/terminus

Score

57.1

Supply Chain

99.6

Quality

83.2

Maintenance

100

Vulnerability

100

License

Pull Requests

Open

12

Total

263

Closed

108

Merged

143

Issues

Open

4

Total

67

Closed

63

Releases

v4.12.1

Published on 23 Jun 2023

v4.12.0

Published on 16 Apr 2023

v4.11.2

Published on 29 Aug 2022

v4.11.1

Published on 10 Jul 2022

v4.11.0

Published on 22 Jun 2022

v4.10.2

Published on 19 Jan 2022

View all 40 releases

Developer

godaddy

Developer Guide

BETA

Module System

CommonJS

Min. Node Version

Typescript Support

Yes

Node Version

18.16.0

NPM Version

8.19.1 Statistics

1,848 Stars

172 Commits

96 Forks

28 Watching

13 Branches

59 Contributors

Updated on 15 Nov 2024

Languages

JavaScript (96.89%)

TypeScript (2.71%)

Dockerfile (0.4%)

Total Downloads

Cumulative downloads

Total Downloads

32,801,529

Last day

-8%

31,441

Compared to previous day

Last week

4.6%

180,949

Compared to previous week

Last month

1.1%

775,432

Compared to previous month

Last year

14.9%

8,561,364

Compared to previous year

Daily Downloads

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

stoppable

Dev Dependencies

@types/express @types/koa @types/node chai express mocha node-fetch nyc pre-commit semantic-release standard typescript

Versions

terminus

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

Installation

Install via npm:

1npm i @godaddy/terminus --save

Usage

1const http = require('http');
2const { createTerminus } = require('@godaddy/terminus');
3
4function onSignal () {
5  console.log('server is starting cleanup');
6  return Promise.all([
7    // your clean logic, like closing database connections
8  ]);
9}
10
11function onShutdown () {
12  console.log('cleanup finished, server is shutting down');
13}
14
15function healthCheck ({ state }) {
16  // `state.isShuttingDown` (boolean) shows whether the server is shutting down or not
17  return Promise.resolve(
18    // optionally include a resolve value to be included as
19    // info in the health check response
20  )
21}
22
23const server = http.createServer((request, response) => {
24  response.end(
25    `<html>
26      <body>
27        <h1>Hello, World!</h1>
28       </body>
29     </html>`
30   );
31})
32
33const options = {
34  // health check options
35  healthChecks: {
36    '/healthcheck': healthCheck,    // a function accepting a state and returning a promise indicating service health,
37    verbatim: true,                 // [optional = false] use object returned from /healthcheck verbatim in response,
38    __unsafeExposeStackTraces: true // [optional = false] return stack traces in error response if healthchecks throw errors
39  },
40  caseInsensitive,                  // [optional] whether given health checks routes are case insensitive (defaults to false)
41
42  statusOk,                         // [optional = 200] status to be returned for successful healthchecks
43  statusOkResponse,                 // [optional = { status: 'ok' }] status response to be returned for successful healthchecks
44  statusError,                      // [optional = 503] status to be returned for unsuccessful healthchecks
45  statusErrorResponse,              // [optional = { status: 'error' }] status response to be returned for unsuccessful healthchecks
46
47  // cleanup options
48  timeout: 1000,                    // [optional = 1000] number of milliseconds before forceful exiting
49  signal,                           // [optional = 'SIGTERM'] what signal to listen for relative to shutdown
50  signals,                          // [optional = []] array of signals to listen for relative to shutdown
51  useExit0,                         // [optional = false] instead of sending the received signal again without beeing catched, the process will exit(0)
52  sendFailuresDuringShutdown,       // [optional = true] whether or not to send failure (503) during shutdown
53  beforeShutdown,                   // [optional] called before the HTTP server starts its shutdown
54  onSignal,                         // [optional] cleanup function, returning a promise (used to be onSigterm)
55  onShutdown,                       // [optional] called right before exiting
56  onSendFailureDuringShutdown,      // [optional] called before sending each 503 during shutdowns
57
58  // both
59  logger                            // [optional] logger function to be called with errors. Example logger call: ('error happened during shutdown', error). See terminus.js for more details.
60};
61
62createTerminus(server, options);
63
64server.listen(PORT || 3000);

With custom error messages

1const http = require('http');
2const { createTerminus, HealthCheckError } = require('@godaddy/terminus');
3
4createTerminus(server, {
5  healthChecks: {
6    '/healthcheck': async function () {
7      const errors = []
8      return Promise.all([
9        // all your health checks goes here
10      ].map(p => p.catch((error) => {
11        // silently collecting all the errors
12        errors.push(error)
13        return undefined
14      }))).then(() => {
15        if (errors.length) {
16          throw new HealthCheckError('healthcheck failed', errors)
17        }
18      })
19    }
20  }
21});

With custom headers

1const http = require("http");
2const express = require("express");
3const { createTerminus, HealthCheckError } = require('@godaddy/terminus');
4const app = express();
5
6app.get("/", (req, res) => {
7  res.send("ok");
8});
9
10const server = http.createServer(app);
11
12function healthCheck({ state }) {
13  return Promise.resolve();
14}
15
16const options = {
17  healthChecks: {
18    "/healthcheck": healthCheck,
19    verbatim: true,
20    __unsafeExposeStackTraces: true,
21  },
22  headers: {
23    "Access-Control-Allow-Origin": "*",
24    "Access-Control-Allow-Methods": "OPTIONS, POST, GET",
25  },
26};
27
28terminus.createTerminus(server, options);
29
30server.listen(3000);

With express

1const http = require('http');
2const express = require('express');
3const { createTerminus } = require('@godaddy/terminus');
4const app = express();
5
6app.get('/', (req, res) => {
7  res.send('ok');
8});
9
10const server = http.createServer(app);
11
12const options = {
13  // opts
14};
15
16createTerminus(server, options);
17
18server.listen(PORT || 3000);

With koa

1const http = require('http');
2const Koa = require('koa');
3const { createTerminus } = require('@godaddy/terminus');
4const app = new Koa();
5
6const server = http.createServer(app.callback());
7
8const options = {
9  // opts
10};
11
12createTerminus(server, options);
13
14server.listen(PORT || 3000);

With cluster (and eg. express)

If you want to use (cluster)[https://nodejs.org/api/cluster.html] to use more than one CPU, you need to use terminus per worker. This is heavily inspired by https://medium.com/@gaurav.lahoti/graceful-shutdown-of-node-js-workers-dd58bbff9e30.

See example/express.cluster.js.

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.

Also it makes sense to use the useExit0 = true option to signal Kubernetes that the container exited gracefully. Otherwise APM's will send you alerts, in some cases.

1function beforeShutdown () {
2  // given your readiness probes run every 5 second
3  // may be worth using a bigger number so you won't
4  // run into any race conditions
5  return new Promise(resolve => {
6    setTimeout(resolve, 5000)
7  })
8}
9createTerminus(server, {
10  beforeShutdown,
11  useExit0: true
12})

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.

No vulnerabilities found.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

10

Packaging

Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.

9

Security-Policy

Determines if the project has published a security policy.

7

SAST

Determines if the project uses static code analysis.

5

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

1

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

Reason

dependency not pinned by hash detected -- score normalized to 1

Details

Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/cicd.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/godaddy/terminus/cicd.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/cicd.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/godaddy/terminus/cicd.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/cicd.yml:33: update your workflow using https://app.stepsecurity.io/secureworkflow/godaddy/terminus/cicd.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/cicd.yml:37: update your workflow using https://app.stepsecurity.io/secureworkflow/godaddy/terminus/cicd.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:38: update your workflow using https://app.stepsecurity.io/secureworkflow/godaddy/terminus/codeql-analysis.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/godaddy/terminus/codeql-analysis.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:53: update your workflow using https://app.stepsecurity.io/secureworkflow/godaddy/terminus/codeql-analysis.yml/main?enable=pin
Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codeql-analysis.yml:67: update your workflow using https://app.stepsecurity.io/secureworkflow/godaddy/terminus/codeql-analysis.yml/main?enable=pin
Warn: containerImage not pinned by hash: example/cassandra/Dockerfile:1: pin your Docker image by updating cassandra to cassandra@sha256:5d4795c41491654e2bda432179e020c7c2cd702bbb22b7d1314747658efd71b4
Warn: containerImage not pinned by hash: example/mongo/Dockerfile:1: pin your Docker image by updating mongo to mongo@sha256:c165af1a407eefce644877bf5a59ba3d9ca762e62b4f1723c919dc08dc32f4d0
Warn: containerImage not pinned by hash: example/mongoose/Dockerfile:1: pin your Docker image by updating mongo to mongo@sha256:c165af1a407eefce644877bf5a59ba3d9ca762e62b4f1723c919dc08dc32f4d0
Warn: containerImage not pinned by hash: example/mysql/Dockerfile:1: pin your Docker image by updating mysql to mysql@sha256:0255b469f0135a0236d672d60e3154ae2f4538b146744966d96440318cc822c6
Warn: containerImage not pinned by hash: example/postgres/Dockerfile:1: pin your Docker image by updating postgres to postgres@sha256:994cc3113ce004ae73df11f0dbc5088cbe6bb0da1691dd7e6f55474202a4f211
Warn: containerImage not pinned by hash: example/redis/Dockerfile:1: pin your Docker image by updating redis:latest to redis:latest@sha256:af0be38eb8e43191bae9b03fe5c928803930b6f93e2dde3a7ad1165c04b1ce22
Info: 0 out of 8 GitHub-owned GitHubAction dependencies pinned
Info: 0 out of 6 containerImage dependencies pinned
Info: 2 out of 2 npmCommand dependencies pinned

0

Maintained

Determines if the project is "actively maintained".

0

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Fuzzing

Determines if the project uses fuzzing.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Score

4.8

/10

Last Scanned on 2024-11-25

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.

Learn More