@godaddy/terminus
Advanced tools
[](https://godaddy-oss.slack.com/) [](https://github.com/godaddy/terminus/actions/workflows
@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.
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);express-graceful-exit is a middleware for Express.js applications that allows for graceful shutdowns. It provides similar functionality to @godaddy/terminus by enabling the application to handle termination signals and complete ongoing requests before shutting down. However, it is specifically designed for Express.js applications, whereas @godaddy/terminus can be used with any Node.js HTTP server.
lightship is a library for managing graceful shutdowns and health checks in Node.js applications. It offers similar features to @godaddy/terminus, including handling termination signals and providing health check endpoints. One key difference is that lightship includes built-in support for Kubernetes readiness and liveness probes, making it a good choice for applications running in Kubernetes environments.
Adds graceful shutdown and Kubernetes readiness / liveness checks for any HTTP applications.
Install via npm:
npm i @godaddy/terminus --save
const http = require('http');
const { createTerminus } = 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 ({ state }) {
// `state.isShuttingDown` (boolean) shows whether the server is shutting down or not
return Promise.resolve(
// optionally include a resolve value to be included as
// info in the health check response
)
}
const server = http.createServer((request, response) => {
response.end(
`<html>
<body>
<h1>Hello, World!</h1>
</body>
</html>`
);
})
const options = {
// health check options
healthChecks: {
'/healthcheck': healthCheck, // a function accepting a state and returning a promise indicating service health,
verbatim: true, // [optional = false] use object returned from /healthcheck verbatim in response,
__unsafeExposeStackTraces: true // [optional = false] return stack traces in error response if healthchecks throw errors
},
caseInsensitive, // [optional] whether given health checks routes are case insensitive (defaults to false)
statusOk, // [optional = 200] status to be returned for successful healthchecks
statusOkResponse, // [optional = { status: 'ok' }] status response to be returned for successful healthchecks
statusError, // [optional = 503] status to be returned for unsuccessful healthchecks
statusErrorResponse, // [optional = { status: 'error' }] status response to be returned for unsuccessful healthchecks
// cleanup options
timeout: 1000, // [optional = 1000] number of milliseconds before forceful exiting
signal, // [optional = 'SIGTERM'] what signal to listen for relative to shutdown
signals, // [optional = []] array of signals to listen for relative to shutdown
useExit0, // [optional = false] instead of sending the received signal again without beeing catched, the process will exit(0)
sendFailuresDuringShutdown, // [optional = true] whether or not to send failure (503) during 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
onSendFailureDuringShutdown, // [optional] called before sending each 503 during shutdowns
// both
logger // [optional] logger function to be called with errors. Example logger call: ('error happened during shutdown', error). See terminus.js for more details.
};
createTerminus(server, options);
server.listen(PORT || 3000);
const http = require('http');
const { createTerminus, HealthCheckError } = require('@godaddy/terminus');
createTerminus(server, {
healthChecks: {
'/healthcheck': async function () {
const errors = []
return Promise.all([
// all your health checks goes here
].map(p => p.catch((error) => {
// silently collecting all the errors
errors.push(error)
return undefined
}))).then(() => {
if (errors.length) {
throw new HealthCheckError('healthcheck failed', errors)
}
})
}
}
});
const http = require("http");
const express = require("express");
const { createTerminus, HealthCheckError } = require('@godaddy/terminus');
const app = express();
app.get("/", (req, res) => {
res.send("ok");
});
const server = http.createServer(app);
function healthCheck({ state }) {
return Promise.resolve();
}
const options = {
healthChecks: {
"/healthcheck": healthCheck,
verbatim: true,
__unsafeExposeStackTraces: true,
},
headers: {
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Methods": "OPTIONS, POST, GET",
},
};
terminus.createTerminus(server, options);
server.listen(3000);
const http = require('http');
const express = require('express');
const app = express();
app.get('/', (req, res) => {
res.send('ok');
});
const server = http.createServer(app);
const options = {
// opts
};
createTerminus(server, options);
server.listen(PORT || 3000);
const http = require('http');
const Koa = require('koa');
const app = new Koa();
const server = http.createServer(app.callback());
const options = {
// opts
};
createTerminus(server, options);
server.listen(PORT || 3000);
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.
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.
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)
})
}
createTerminus(server, {
beforeShutdown,
useExit0: true
})
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
[](https://godaddy-oss.slack.com/) [](https://github.com/godaddy/terminus/actions/workflows
The npm package @godaddy/terminus receives a total of 143,391 weekly downloads. As such, @godaddy/terminus popularity was classified as popular.
We found that @godaddy/terminus demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 11 open source maintainers collaborating on the project.
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.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.