Gracious is a library that faciliates the graceful shutdown of Node.js applications.
When you deploy a Node.js application, the previous version is usually terminated by sending a SIGINT or SIGTERM signal to the main process. Unless handled, the application will stop abruptly, interrupting any inflight work. Even in well designed systems, failing to complete a unit of work, or attempting to perform it twice, is likely to create problems such has confusing logs, but in poorly designed systems this could result in data loss or inconsistency. By deferring shutdown until inflight work is complete, you minimise these undersireable side effects. This is where Gracious comes in.
Gracious provides a TaskRegistry for tracking inflight units of work. Whenever your application starts a new unit of work you must record it in the registry, then clear the entry when the task completes. In addition, when sent a SIGINT and SIGTERM events, you must prevent the application starting new units of work, and wait for the registry to close. The registry will only close when all inflight units of work are complete, or after a configurable timeout. The default timeout is 3 seconds.
const { globalTaskRegistry: registry } = require('gracious');
const intervalId = setInterval(async () => {
// Record the start of a unit of work
const token = registry.register('Example');
try {
// Perform the unit of work
for (let i = 0; i < 10; i++) {
await performStep(i);
}
} finally {
// Record that the unit of work has completed
registry.clear(token);
}
}, 2000);
['SIGTERM', 'SIGINT'].forEach((signal) => {
process.once(signal, async () => {
try {
console.log(`Received ${signal}`);
// Stop accepting new work
clearInterval(intervalId);
console.log(`Waiting for ${registry.count} task(s) to complete`);
// Wait for the registry to close
await registry.close();
console.log('Done');
process.exit(0);
} catch (err) {
console.error(err);
process.exit(1);
}
});
});
function performStep(i) {
return new Promise((resolve) => {
setTimeout(() => {
console.log(`Performing step ${i + 1}`);
resolve();
}, 100);
}Top and tailing tasks between register and clear calls can get onerous, and if the clear call is bypassed, will cause a memory leak. As an alternative consider using the perform function, i.e.
await registry.perform('Example', async () => {
for (let i = 0; i < 10; i++) {
await performStep(i);
}
});The default timeout of three seconds can be overriden as follows
// Timeout after five seconds
await registry.close({ timeout: 5000 });
// Disable the timeout completely
await registry.close({ timeout: 0 });Gracious ships with a shared global registry, but you do not have to use it. You can instantiate your own registries as follows
const { TaskRegistry } = require('gracious');
const registry = new TaskRegistry();