http-shutdown

What is http-shutdown?

The http-shutdown npm package extends the standard Node.js HTTP server with a shutdown method. This allows you to gracefully shut down the server, ensuring that all existing connections are served before the server is closed.

What are http-shutdown's main functionalities?

Graceful Shutdown

This feature allows you to add a shutdown method to your HTTP server instance. When called, it will not accept new connections and will wait for all existing connections to end before shutting down the server.

const http = require('http');
const enableShutdown = require('http-shutdown');

const server = enableShutdown(http.createServer((req, res) => {
  res.writeHead(200);
  res.end('Hello World!');
}));

server.listen(3000);

// Shutdown the server after 10 seconds
setTimeout(() => {
  server.shutdown(() => {
    console.log('Server is gracefully shut down.');
  });
}, 10000);

Other packages similar to http-shutdown

stoppable

Stoppable is an npm package that also provides a way to gracefully stop an HTTP server. It tracks active connections and allows you to set a timeout for how long the server should wait for active connections to finish before forcibly shutting down. It is similar to http-shutdown but offers a timeout feature.

terminus

Terminus is an npm package designed to add graceful shutdown and Kubernetes readiness / liveness checks for any HTTP applications. It extends the server with more advanced features compared to http-shutdown, such as signal handling for shutdown, health checks, and on-shutdown hooks.

README

Http-Shutdown

Shutdown a Nodejs HTTP server gracefully by doing the following:

1. Close the listening socket to prevent new connections
2. Close all idle keep-alive sockets to prevent new requests during shutdown
3. Wait for all in-flight requests to finish before closing their sockets.
4. Profit!

Other solutions might just use server.close which only terminates the listening socket and waits for other sockets to close - which is incomplete since keep-alive sockets can still make requests. Or, they may use ref()/unref() to simply cause Nodejs to terminate if the sockets are idle - which doesn't help if you have other things to shutdown after the server shutsdown.

http-shutdown is a complete solution. It uses idle indicators combined with an active socket list to safely, and gracefully, close all sockets. It does not use ref()/unref() but, instead, actively closes connections as they finish meaning that socket 'close' events still work correctly since the sockets are actually closing - you're not just unrefing and forgetting about them.

Installation

$ npm install http-shutdown

Usage

There are currently two ways to use this library. The first is explicit wrapping of the Server object:

// Create the http server
var server = require('http').createServer(function(req, res) {
  res.end('Good job!');
});

// Wrap the server object with additional functionality.
// This should be done immediately after server construction, or before you start listening.
// Additional functionailiy needs to be added for http server events to properly shutdown.
server = require('http-shutdown')(server);

// Listen on a port and start taking requests.
server.listen(3000);

// Sometime later... shutdown the server.
server.shutdown(function(err) {
	if (err) {
		return console.log('shutdown failed', err.message);
	}
	console.log('Everything is cleanly shutdown.');
});

The second is implicitly adding prototype functionality to the Server object:

// .extend adds a .withShutdown prototype method to the Server object
require('http-shutdown').extend();

var server = require('http').createServer(function(req, res) {
  res.end('God job!');
}).withShutdown(); // <-- Easy to chain. Returns the Server object

// Sometime later, shutdown the server.
server.shutdown(function(err) {
	if (err) {
		return console.log('shutdown failed', err.message);
	}
  console.log('Everything is cleanly shutdown.');
});

Test

$ npm test