# http-terminator
> Gracefully terminates HTTP(S) server.
Latest version **3.2.0** (published 2022-03-10) · BSD-3-Clause license · 0 weekly downloads
## Install
```sh
npm install http-terminator
pnpm add http-terminator
yarn add http-terminator
bun add http-terminator
```
## Health
**Score 25/100 (F)** — status: abandoned.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 3.2.0 |
| Published | 2022-03-10 |
| First published | 2020-01-19 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=14 |
| Dependencies | 4 |
| Unpacked size | 22.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 335 |
| Author | Gajus Kuizinas |
| Maintainers | gajus |
| Keywords | kubernetes, prometheus |
## Links
- npm: https://www.npmjs.com/package/http-terminator
- Repository: https://github.com/gajus/http-terminator
- Homepage: https://github.com/gajus/http-terminator#readme
- Issues: https://github.com/gajus/http-terminator/issues
- npm.io page: https://npm.io/package/http-terminator
## Dependencies (4)
- [delay](https://npm.io/package/delay.md) ^5.0.0
- [roarr](https://npm.io/package/roarr.md) ^7.0.4
- [type-fest](https://npm.io/package/type-fest.md) ^2.3.3
- [p-wait-for](https://npm.io/package/p-wait-for.md) ^3.2.0
## Recent versions
- 3.2.0 (latest) — 2022-03-10
- 3.1.0 — 2022-02-28
- 3.0.4 — 2021-11-30
- 3.0.3 — 2021-09-18
- 3.0.2 — 2021-09-17
- 3.0.1 — 2021-09-17
- 3.0.0 — 2021-02-09
- 2.0.3 — 2020-04-19
- 2.0.2 — 2020-02-03
- 2.0.1 — 2020-01-29
- 2.0.0 — 2020-01-21
- 1.2.3 — 2020-01-21
- 1.2.2 — 2020-01-20
- 1.2.1 — 2020-01-20
- 1.2.0 — 2020-01-20
- … 2 more at https://npm.io/package/http-terminator/versions
## README
# http-terminator 🦾
[](https://travis-ci.com/gajus/http-terminator)
[](https://coveralls.io/github/gajus/http-terminator)
[](https://www.npmjs.org/package/http-terminator)
[](https://github.com/gajus/canonical)
[](https://twitter.com/kuizinas)
Gracefully terminates HTTP(S) server.
* [http-terminator 🦾](#http-terminator)
* [Behaviour](#http-terminator-behaviour)
* [API](#http-terminator-api)
* [Usage](#http-terminator-usage)
* [Usage with Express](#http-terminator-usage-usage-with-express)
* [Usage with Fastify](#http-terminator-usage-usage-with-fastify)
* [Usage with Koa](#http-terminator-usage-usage-with-koa)
* [Usage with other HTTP frameworks](#http-terminator-usage-usage-with-other-http-frameworks)
* [Alternative libraries](#http-terminator-alternative-libraries)
* [FAQ](#http-terminator-faq)
* [What is the use case for http-terminator?](#http-terminator-faq-what-is-the-use-case-for-http-terminator)
## Behaviour
When you call [`server.close()`](https://nodejs.org/api/http.html#http_server_close_callback), 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.
http-terminator implements the logic for tracking all connections and their termination upon a timeout. http-terminator also ensures graceful communication of the server intention to shutdown to any clients that are currently receiving response from this server.
## API
```js
import {
createHttpTerminator,
} from 'http-terminator';
/**
* @property gracefulTerminationTimeout Number of milliseconds to allow for the active sockets to complete serving the response (default: 5000).
* @property server Instance of http.Server.
*/
type HttpTerminatorConfigurationInputType = {|
+gracefulTerminationTimeout?: number,
+server: Server,
|};
/**
* @property terminate Terminates HTTP server.
*/
type HttpTerminatorType = {|
+terminate: () => Promise,
|};
const httpTerminator: HttpTerminatorType = createHttpTerminator(
configuration: HttpTerminatorConfigurationInputType
);
```
## Usage
Use `createHttpTerminator` to create an instance of http-terminator and instead of using `server.close()`, use `httpTerminator.terminate()`, e.g.
```js
import http from 'http';
import {
createHttpTerminator,
} from 'http-terminator';
const server = http.createServer();
const httpTerminator = createHttpTerminator({
server,
});
await httpTerminator.terminate();
```
### Usage with Express
Usage with [Express](https://www.npmjs.com/package/express) example:
```js
import express from 'express';
import {
createHttpTerminator,
} from 'http-terminator';
const app = express();
const server = app.listen();
const httpTerminator = createHttpTerminator({
server,
});
await httpTerminator.terminate();
```
### Usage with Fastify
Usage with [Fastify](https://www.npmjs.com/package/fastify) example:
```js
import fastify from 'fastify';
import {
createHttpTerminator,
} from 'http-terminator';
const app = fastify();
void app.listen(0);
const httpTerminator = createHttpTerminator({
server: app.server,
});
await httpTerminator.terminate();
```
### Usage with Koa
Usage with [Koa](https://www.npmjs.com/package/koa) example:
```js
import Koa from 'koa';
import {
createHttpTerminator,
} from 'http-terminator';
const app = new Koa();
const server = app.listen();
const httpTerminator = createHttpTerminator({
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, http-terminator works by accessing an instance of a Node.js [`http.Server`](https://nodejs.org/api/http.html#http_class_http_server). To understand how to use http-terminator with your framework, identify how to access an instance of `http.Server` and use it to create a http-terminator instance.
## Alternative libraries
There are several alternative libraries that implement comparable functionality, e.g.
* 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 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
## FAQ
### What is the use case for 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).
* 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).
---
_Source: https://npm.io/package/http-terminator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._