DroidSolutions http-terminator

(Based on http-terminator.)

Gracefully terminates HTTP(S) server. Also includes Typescript support.

• DroidSolutions http-terminator
  • Behaviour
  • Usage
    • Usage with Express
    • Usage with Koa
    • Usage with other HTTP frameworks
  • Alternative libraries
  • FAQ
    • What is the use case for http-terminator?

Behaviour

When you call server.close(), it stops the server from accepting new connections, but it keeps the existing connections open indefinitely. This can result in your server hanging indefinitely due to keep-alive connections or because of the ongoing requests that do not produce a response. Therefore, in order to close the server, you must track creation of all connections and terminate them yourself.

DroidSolutions http-terminator implements the logic for tracking all connections and their termination upon a timeout. It also ensures graceful communication of the server intention to shutdown to any clients that are currently receiving response from this server.

Usage

Use new HttpTerminator to create an instance of DroidSolutions http-terminator and instead of using server.close(), use httpTerminator.terminate().

import { HttpTerminator } from "@droidsolutions/http-terminator";
import http from "http";

const server = http.createServer();

const httpTerminator = new HttpTerminator(server);

await httpTerminator.terminate();

Usage with Express

Usage with Express example:

import express from "express";
import { HttpTerminator } from "@droidsolutions/http-terminator";

const app = express();

const server = app.listen();

const httpTerminator = new HttpTerminator(server);

await httpTerminator.terminate();

You can specify an optional timeout in milliseconds to wait, before requests are closed forcefully. If you do not specify a timeout, the default of 1000 ms is used.

const httpTerminator = new HttpTerminator(server);
await httpTerminator.terminate(2000);

Usage with Koa

Usage with Koa example:

import Koa from "koa";
import { HttpTerminator } from "@droidsolutions/http-terminator";

const app = new Koa();

const server = app.listen();

const httpTerminator = new HttpTerminator(server);

await httpTerminator.terminate();

Usage with other HTTP frameworks

As it should be clear from the usage examples for Node.js HTTP server, Express and Koa, DroidSolutions http-terminator works by accessing an instance of a Node.js http.Server. To understand how to use DroidSolutions http-terminator with your framework, identify how to access an instance of http.Server and use it to create a HttpTerminator instance.

Alternative libraries

There are several alternative libraries that implement comparable functionality, e.g.

• https://github.com/gajus/http-terminator
• https://github.com/hunterloftis/stoppable
• https://github.com/thedillonb/http-shutdown
• https://github.com/tellnes/http-close
• https://github.com/sebhildebrandt/http-graceful-shutdown

The main benefit of DroidSolutions http-terminator is that:

• it does not monkey-patch Node.js API
• it immediately destroys all sockets without an attached HTTP request
• it allows graceful timeout to sockets with ongoing HTTP requests
• it properly handles HTTPS connections
• it informs connections using keep-alive that server is shutting down by setting a connection: close header
• it does not terminate the Node.js process
• it comes with full TypeScript support

FAQ

What is the use case for DroidSolutions http-terminator?

To gracefully terminate a HTTP server.

We say that a service is gracefully terminated when service stops accepting new clients, but allows time to complete the existing requests.

There are several reasons to terminate services gracefully:

• Terminating a service gracefully ensures that the client experience is not affected (assuming the service is load-balanced, for example in Kubernetes environments).
• If your application is stateful, then when services are not terminated gracefully, you are risking data corruption.
• Forcing termination of the service with a timeout ensures timely termination of the service (otherwise the service can remain hanging indefinitely).