Gathering detailed insights and metrics for @godaddy/terminus
Gathering detailed insights and metrics for @godaddy/terminus
Graceful shutdown and Kubernetes readiness / liveness checks for any Node.js HTTP applications
Installations
npm install @godaddy/terminusDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS
Node Version
18.16.0
NPM Version
8.19.1
Releases
40
Languages
3
JavaScript
TypeScript
Dockerfile
JavaScript (96.89%)
TypeScript (2.71%)
Dockerfile (0.4%)
Developer
godaddy
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
MIT License
1,878 Stars
172 Commits
96 Forks
26 Watchers
13 Branches
59 Contributors
Updated on Jun 25, 2025
Bundle Size
4.26 kB
Minified
1.68 kB
Minified + Gzipped
Maintainers
11
Package Meta Information
Latest Version
4.12.1
Package Id
@godaddy/terminus@4.12.1
Unpacked Size
60.88 kB
Size
10.64 kB
File Count
29
NPM Version
8.19.1
Node Version
18.16.0
Published on
Jun 23, 2023
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
1
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 app = express(); 4 5app.get('/', (req, res) => { 6 res.send('ok'); 7}); 8 9const server = http.createServer(app); 10 11const options = { 12 // opts 13}; 14 15createTerminus(server, options); 16 17server.listen(PORT || 3000);
With koa
1const http = require('http'); 2const Koa = require('koa'); 3const app = new Koa(); 4 5const server = http.createServer(app.callback()); 6 7const options = { 8 // opts 9}; 10 11createTerminus(server, options); 12 13server.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})
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.
Reason
no binaries found in the repo
Reason
no dangerous workflow patterns detected
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: MIT License: LICENSE:0
Reason
security policy file detected
Details
- Info: security policy file detected: github.com/godaddy/.github/SECURITY.md:1
- Info: Found linked content: github.com/godaddy/.github/SECURITY.md:1
- Warn: One or no descriptive hints of disclosure, vulnerability, and/or timelines in security policy
- Info: Found text in security policy: github.com/godaddy/.github/SECURITY.md:1
Reason
SAST tool detected but not run on all commits
Details
- Info: SAST configuration detected: CodeQL
- Warn: 0 commits out of 25 are checked with a SAST tool
Reason
Found 10/17 approved changesets -- score normalized to 5
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:71687bdd98228f3ce273fc8484435f327940ce186aadc99bf63390094d0da568
- Warn: containerImage not pinned by hash: example/mongo/Dockerfile:1: pin your Docker image by updating mongo to mongo@sha256:5941949d3887e40be5175787aade07dc052f2cddb8ce21b740c3948eba6a3ed0
- Warn: containerImage not pinned by hash: example/mongoose/Dockerfile:1: pin your Docker image by updating mongo to mongo@sha256:5941949d3887e40be5175787aade07dc052f2cddb8ce21b740c3948eba6a3ed0
- Warn: containerImage not pinned by hash: example/mysql/Dockerfile:1: pin your Docker image by updating mysql to mysql@sha256:f1049ce35b3986b84c08184de43a0b2109ae037a4a10a23ecf373a893daeadf7
- Warn: containerImage not pinned by hash: example/postgres/Dockerfile:1: pin your Docker image by updating postgres to postgres@sha256:3962158596daaef3682838cc8eb0e719ad1ce520f88e34596ce8d5de1b6330a1
- Warn: containerImage not pinned by hash: example/redis/Dockerfile:1: pin your Docker image by updating redis:latest to redis:latest@sha256:b43d2dcbbdb1f9e1582e3a0f37e53bf79038522ccffb56a25858969d7a9b6c11
- 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
Reason
0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/cicd.yml:1
- Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1
- Info: no jobLevel write permissions found
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
27 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-p6mc-m468-83gw
- Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8
- Warn: Project is vulnerable to: GHSA-67hx-6x53-jw92
- Warn: Project is vulnerable to: GHSA-h5c3-5r3r-rr8q
- Warn: Project is vulnerable to: GHSA-rmvr-2pp2-xj38
- Warn: Project is vulnerable to: GHSA-xx4v-prfh-6cgc
- Warn: Project is vulnerable to: GHSA-qwcr-r2fm-qrc7
- Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
- Warn: Project is vulnerable to: GHSA-grv7-fg5c-xmjg
- Warn: Project is vulnerable to: GHSA-pxg6-pf52-xh8x
- Warn: Project is vulnerable to: GHSA-3xgq-45jj-v275
- Warn: Project is vulnerable to: GHSA-rv95-896h-c2vc
- Warn: Project is vulnerable to: GHSA-qw6h-vgh9-j6wx
- Warn: Project is vulnerable to: GHSA-4q6p-r6v2-jvc5
- Warn: Project is vulnerable to: GHSA-rc47-6667-2j5j
- Warn: Project is vulnerable to: GHSA-78xj-cgh5-2h22
- Warn: Project is vulnerable to: GHSA-2p57-rm9w-gvfp
- Warn: Project is vulnerable to: GHSA-952p-6rrq-rcjv
- Warn: Project is vulnerable to: GHSA-mwcw-c2x4-8c55
- Warn: Project is vulnerable to: GHSA-9wv6-86v2-598j
- Warn: Project is vulnerable to: GHSA-rhx6-c78j-4q9w
- Warn: Project is vulnerable to: GHSA-c2qf-rxjj-qqgw
- Warn: Project is vulnerable to: GHSA-m6fv-jmcg-4jfg
- Warn: Project is vulnerable to: GHSA-76p7-773f-r4q5
- Warn: Project is vulnerable to: GHSA-cm22-4g7w-348p
- Warn: Project is vulnerable to: GHSA-f5x3-32g6-xq36
- Warn: Project is vulnerable to: GHSA-j8xg-fqg3-53r7
Score
4.4
/10
Last Scanned on 2025-06-30
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