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
express-graceful-exit
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
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.
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([
]);
}
function onShutdown () {
console.log('cleanup finished, server is shutting down');
}
const server = http.createServer((request, response) => {
response.end(
`<html>
<body>
<h1>Hello, World!</h1>
</body>
</html>`
);
})
const options = {
healthChecks: {
'/healthcheck': check
},
timeout: 1000,
signal,
beforeShutdown,
onSignal,
onShutdown,
logger
};
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 = {
};
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 = {
};
terminus(server, options);
server.listen(PORT || 3000);
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.