{"id":15390291,"url":"https://github.com/gajus/http-terminator","last_synced_at":"2025-05-16T01:06:04.979Z","repository":{"id":45884042,"uuid":"234980401","full_name":"gajus/http-terminator","owner":"gajus","description":"Gracefully terminates HTTP(S) server.","archived":false,"fork":false,"pushed_at":"2023-08-10T07:41:20.000Z","size":75,"stargazers_count":330,"open_issues_count":13,"forks_count":26,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-13T02:18:30.158Z","etag":null,"topics":["http"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gajus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-01-19T22:56:47.000Z","updated_at":"2025-04-28T12:16:24.000Z","dependencies_parsed_at":"2023-11-07T01:06:58.909Z","dependency_job_id":null,"html_url":"https://github.com/gajus/http-terminator","commit_stats":{"total_commits":54,"total_committers":6,"mean_commits":9.0,"dds":"0.14814814814814814","last_synced_commit":"aabca4751552e983f8a59ba896b7fb58ce3b4087"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fhttp-terminator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fhttp-terminator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fhttp-terminator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gajus%2Fhttp-terminator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gajus","download_url":"https://codeload.github.com/gajus/http-terminator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448579,"owners_count":22072764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http"],"created_at":"2024-10-01T15:05:15.324Z","updated_at":"2025-05-16T01:05:59.955Z","avatar_url":"https://github.com/gajus.png","language":"TypeScript","funding_links":[],"categories":["Framework agnostic packages"],"sub_categories":["Node"],"readme":"\u003ca name=\"http-terminator\"\u003e\u003c/a\u003e\n# http-terminator 🦾\n\n[![Travis build status](http://img.shields.io/travis/gajus/http-terminator/master.svg?style=flat-square)](https://travis-ci.com/gajus/http-terminator)\n[![Coveralls](https://img.shields.io/coveralls/gajus/http-terminator.svg?style=flat-square)](https://coveralls.io/github/gajus/http-terminator)\n[![NPM version](http://img.shields.io/npm/v/http-terminator.svg?style=flat-square)](https://www.npmjs.org/package/http-terminator)\n[![Canonical Code Style](https://img.shields.io/badge/code%20style-canonical-blue.svg?style=flat-square)](https://github.com/gajus/canonical)\n[![Twitter Follow](https://img.shields.io/twitter/follow/kuizinas.svg?style=social\u0026label=Follow)](https://twitter.com/kuizinas)\n\nGracefully terminates HTTP(S) server.\n\n* [http-terminator 🦾](#http-terminator)\n    * [Behaviour](#http-terminator-behaviour)\n    * [API](#http-terminator-api)\n    * [Usage](#http-terminator-usage)\n        * [Usage with Express](#http-terminator-usage-usage-with-express)\n        * [Usage with Fastify](#http-terminator-usage-usage-with-fastify)\n        * [Usage with Koa](#http-terminator-usage-usage-with-koa)\n        * [Usage with other HTTP frameworks](#http-terminator-usage-usage-with-other-http-frameworks)\n    * [Alternative libraries](#http-terminator-alternative-libraries)\n    * [FAQ](#http-terminator-faq)\n        * [What is the use case for http-terminator?](#http-terminator-faq-what-is-the-use-case-for-http-terminator)\n\n\n\u003ca name=\"http-terminator-behaviour\"\u003e\u003c/a\u003e\n## Behaviour\n\nWhen 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.\n\nhttp-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.\n\n\u003ca name=\"http-terminator-api\"\u003e\u003c/a\u003e\n## API\n\n```js\nimport {\n  createHttpTerminator,\n} from 'http-terminator';\n\n/**\n * @property gracefulTerminationTimeout Number of milliseconds to allow for the active sockets to complete serving the response (default: 5000).\n * @property server Instance of http.Server.\n */\ntype HttpTerminatorConfigurationInputType = {|\n  +gracefulTerminationTimeout?: number,\n  +server: Server,\n|};\n\n/**\n * @property terminate Terminates HTTP server.\n */\ntype HttpTerminatorType = {|\n  +terminate: () =\u003e Promise\u003cvoid\u003e,\n|};\n\n\nconst httpTerminator: HttpTerminatorType = createHttpTerminator(\n  configuration: HttpTerminatorConfigurationInputType\n);\n\n```\n\n\u003ca name=\"http-terminator-usage\"\u003e\u003c/a\u003e\n## Usage\n\nUse `createHttpTerminator` to create an instance of http-terminator and instead of using `server.close()`, use `httpTerminator.terminate()`, e.g.\n\n```js\nimport http from 'http';\nimport {\n  createHttpTerminator,\n} from 'http-terminator';\n\nconst server = http.createServer();\n\nconst httpTerminator = createHttpTerminator({\n  server,\n});\n\nawait httpTerminator.terminate();\n\n```\n\n\u003ca name=\"http-terminator-usage-usage-with-express\"\u003e\u003c/a\u003e\n### Usage with Express\n\nUsage with [Express](https://www.npmjs.com/package/express) example:\n\n```js\nimport express from 'express';\nimport {\n  createHttpTerminator,\n} from 'http-terminator';\n\nconst app = express();\n\nconst server = app.listen();\n\nconst httpTerminator = createHttpTerminator({\n  server,\n});\n\nawait httpTerminator.terminate();\n\n```\n\n\u003ca name=\"http-terminator-usage-usage-with-fastify\"\u003e\u003c/a\u003e\n### Usage with Fastify\n\nUsage with [Fastify](https://www.npmjs.com/package/fastify) example:\n\n```js\nimport fastify from 'fastify';\nimport {\n  createHttpTerminator,\n} from 'http-terminator';\n\nconst app = fastify();\n\nvoid app.listen(0);\n\nconst httpTerminator = createHttpTerminator({\n  server: app.server,\n});\n\nawait httpTerminator.terminate();\n\n```\n\n\u003ca name=\"http-terminator-usage-usage-with-koa\"\u003e\u003c/a\u003e\n### Usage with Koa\n\nUsage with [Koa](https://www.npmjs.com/package/koa) example:\n\n```js\nimport Koa from 'koa';\nimport {\n  createHttpTerminator,\n} from 'http-terminator';\n\nconst app = new Koa();\n\nconst server = app.listen();\n\nconst httpTerminator = createHttpTerminator({\n  server,\n});\n\nawait httpTerminator.terminate();\n\n```\n\n\u003ca name=\"http-terminator-usage-usage-with-other-http-frameworks\"\u003e\u003c/a\u003e\n### Usage with other HTTP frameworks\n\nAs 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.\n\n\u003ca name=\"http-terminator-alternative-libraries\"\u003e\u003c/a\u003e\n## Alternative libraries\n\nThere are several alternative libraries that implement comparable functionality, e.g.\n\n* https://github.com/hunterloftis/stoppable\n* https://github.com/thedillonb/http-shutdown\n* https://github.com/tellnes/http-close\n* https://github.com/sebhildebrandt/http-graceful-shutdown\n\nThe main benefit of http-terminator is that:\n\n* it does not monkey-patch Node.js API\n* it immediately destroys all sockets without an attached HTTP request\n* it allows graceful timeout to sockets with ongoing HTTP requests\n* it properly handles HTTPS connections\n* it informs connections using keep-alive that server is shutting down by setting a `connection: close` header\n* it does not terminate the Node.js process\n\n\u003ca name=\"http-terminator-faq\"\u003e\u003c/a\u003e\n## FAQ\n\n\u003ca name=\"http-terminator-faq-what-is-the-use-case-for-http-terminator\"\u003e\u003c/a\u003e\n### What is the use case for http-terminator?\n\nTo gracefully terminate a HTTP server.\n\nWe say that a service is gracefully terminated when service stops accepting new clients, but allows time to complete the existing requests.\n\nThere are several reasons to terminate services gracefully:\n\n* Terminating a service gracefully ensures that the client experience is not affected (assuming the service is load-balanced).\n* If your application is stateful, then when services are not terminated gracefully, you are risking data corruption.\n* Forcing termination of the service with a timeout ensures timely termination of the service (otherwise the service can remain hanging indefinitely).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgajus%2Fhttp-terminator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgajus%2Fhttp-terminator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgajus%2Fhttp-terminator/lists"}