{"id":13510202,"url":"https://github.com/godaddy/terminus","last_synced_at":"2025-05-14T03:08:38.498Z","repository":{"id":37335029,"uuid":"112529625","full_name":"godaddy/terminus","owner":"godaddy","description":"Graceful shutdown and Kubernetes readiness / liveness checks for any Node.js HTTP applications","archived":false,"fork":false,"pushed_at":"2024-05-02T04:41:49.000Z","size":1952,"stargazers_count":1874,"open_issues_count":15,"forks_count":96,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-04-10T19:52:44.183Z","etag":null,"topics":["graceful-shutdown","hacktoberfest","kubernetes","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/godaddy.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-29T21:26:00.000Z","updated_at":"2025-04-10T15:49:50.000Z","dependencies_parsed_at":"2024-05-02T05:40:48.970Z","dependency_job_id":"9f3ad838-334d-4627-a16e-67883248e0ed","html_url":"https://github.com/godaddy/terminus","commit_stats":{"total_commits":162,"total_committers":57,"mean_commits":"2.8421052631578947","dds":0.8580246913580247,"last_synced_commit":"f61009ac7f84323e231dbeffc5a8ac33c0eec897"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fterminus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fterminus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fterminus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godaddy%2Fterminus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/godaddy","download_url":"https://codeload.github.com/godaddy/terminus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059507,"owners_count":22007768,"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":["graceful-shutdown","hacktoberfest","kubernetes","nodejs"],"created_at":"2024-08-01T02:01:28.550Z","updated_at":"2025-05-14T03:08:38.448Z","avatar_url":"https://github.com/godaddy.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","nodejs","Diagnostics \u0026 Troubleshooting"],"sub_categories":[],"readme":"# terminus\n\n[![Build Status](https://github.com/godaddy/terminus/actions/workflows/cicd.yml/badge.svg)](https://github.com/godaddy/terminus/actions/workflows/cicd.yml/badge.svg)\n\nAdds graceful shutdown and Kubernetes readiness / liveness checks for any HTTP applications.\n\n## Installation\n\nInstall via npm:\n\n```console\nnpm i @godaddy/terminus --save\n```\n\n## Usage\n\n```javascript\nconst http = require('http');\nconst { createTerminus } = require('@godaddy/terminus');\n\nfunction onSignal () {\n  console.log('server is starting cleanup');\n  return Promise.all([\n    // your clean logic, like closing database connections\n  ]);\n}\n\nfunction onShutdown () {\n  console.log('cleanup finished, server is shutting down');\n}\n\nfunction healthCheck ({ state }) {\n  // `state.isShuttingDown` (boolean) shows whether the server is shutting down or not\n  return Promise.resolve(\n    // optionally include a resolve value to be included as\n    // info in the health check response\n  )\n}\n\nconst server = http.createServer((request, response) =\u003e {\n  response.end(\n    `\u003chtml\u003e\n      \u003cbody\u003e\n        \u003ch1\u003eHello, World!\u003c/h1\u003e\n       \u003c/body\u003e\n     \u003c/html\u003e`\n   );\n})\n\nconst options = {\n  // health check options\n  healthChecks: {\n    '/healthcheck': healthCheck,    // a function accepting a state and returning a promise indicating service health,\n    verbatim: true,                 // [optional = false] use object returned from /healthcheck verbatim in response,\n    __unsafeExposeStackTraces: true // [optional = false] return stack traces in error response if healthchecks throw errors\n  },\n  caseInsensitive,                  // [optional] whether given health checks routes are case insensitive (defaults to false)\n\n  statusOk,                         // [optional = 200] status to be returned for successful healthchecks\n  statusOkResponse,                 // [optional = { status: 'ok' }] status response to be returned for successful healthchecks\n  statusError,                      // [optional = 503] status to be returned for unsuccessful healthchecks\n  statusErrorResponse,              // [optional = { status: 'error' }] status response to be returned for unsuccessful healthchecks\n\n  // cleanup options\n  timeout: 1000,                    // [optional = 1000] number of milliseconds before forceful exiting\n  signal,                           // [optional = 'SIGTERM'] what signal to listen for relative to shutdown\n  signals,                          // [optional = []] array of signals to listen for relative to shutdown\n  useExit0,                         // [optional = false] instead of sending the received signal again without beeing catched, the process will exit(0)\n  sendFailuresDuringShutdown,       // [optional = true] whether or not to send failure (503) during shutdown\n  beforeShutdown,                   // [optional] called before the HTTP server starts its shutdown\n  onSignal,                         // [optional] cleanup function, returning a promise (used to be onSigterm)\n  onShutdown,                       // [optional] called right before exiting\n  onSendFailureDuringShutdown,      // [optional] called before sending each 503 during shutdowns\n\n  // both\n  logger                            // [optional] logger function to be called with errors. Example logger call: ('error happened during shutdown', error). See terminus.js for more details.\n};\n\ncreateTerminus(server, options);\n\nserver.listen(PORT || 3000);\n```\n\n### With custom error messages\n\n```js\nconst http = require('http');\nconst { createTerminus, HealthCheckError } = require('@godaddy/terminus');\n\ncreateTerminus(server, {\n  healthChecks: {\n    '/healthcheck': async function () {\n      const errors = []\n      return Promise.all([\n        // all your health checks goes here\n      ].map(p =\u003e p.catch((error) =\u003e {\n        // silently collecting all the errors\n        errors.push(error)\n        return undefined\n      }))).then(() =\u003e {\n        if (errors.length) {\n          throw new HealthCheckError('healthcheck failed', errors)\n        }\n      })\n    }\n  }\n});\n```\n\n### With custom headers\n```js\nconst http = require(\"http\");\nconst express = require(\"express\");\nconst { createTerminus, HealthCheckError } = require('@godaddy/terminus');\nconst app = express();\n\napp.get(\"/\", (req, res) =\u003e {\n  res.send(\"ok\");\n});\n\nconst server = http.createServer(app);\n\nfunction healthCheck({ state }) {\n  return Promise.resolve();\n}\n\nconst options = {\n  healthChecks: {\n    \"/healthcheck\": healthCheck,\n    verbatim: true,\n    __unsafeExposeStackTraces: true,\n  },\n  headers: {\n    \"Access-Control-Allow-Origin\": \"*\",\n    \"Access-Control-Allow-Methods\": \"OPTIONS, POST, GET\",\n  },\n};\n\nterminus.createTerminus(server, options);\n\nserver.listen(3000);\n```\n\n### With express\n\n```javascript\nconst http = require('http');\nconst express = require('express');\nconst { createTerminus } = require('@godaddy/terminus');\nconst app = express();\n\napp.get('/', (req, res) =\u003e {\n  res.send('ok');\n});\n\nconst server = http.createServer(app);\n\nconst options = {\n  // opts\n};\n\ncreateTerminus(server, options);\n\nserver.listen(PORT || 3000);\n```\n\n### With koa\n\n```javascript\nconst http = require('http');\nconst Koa = require('koa');\nconst { createTerminus } = require('@godaddy/terminus');\nconst app = new Koa();\n\nconst server = http.createServer(app.callback());\n\nconst options = {\n  // opts\n};\n\ncreateTerminus(server, options);\n\nserver.listen(PORT || 3000);\n```\n\n### With cluster (and eg. express)\n\nIf you want to use (`cluster`)[https://nodejs.org/api/cluster.html] to use more than one CPU, you need to use `terminus` per worker.\nThis is heavily inspired by https://medium.com/@gaurav.lahoti/graceful-shutdown-of-node-js-workers-dd58bbff9e30.\n\nSee `example/express.cluster.js`.\n\n## How to set Terminus up with Kubernetes?\n\nWhen Kubernetes or a user deletes a Pod, Kubernetes will notify it and wait for `gracePeriod` seconds before killing it.\n\nDuring that time window (30 seconds by default), the Pod is in the `terminating` state and will be removed from any Services by a controller.\nThe Pod itself needs to catch the `SIGTERM` signal and start failing any readiness probes.\n\n\u003e If the ingress controller you use route via the Service, it is not an issue for your case. At the time of this writing, we use the nginx ingress controller which routes traffic directly to the Pods.\n\nDuring this time, it is possible that load-balancers (like the nginx ingress controller) don't remove the Pods \"in time\", and when the Pod dies, it kills live connections.\n\nTo make sure you don't lose any connections, we recommend delaying the shutdown with the number of milliseconds that's defined by the readiness probe in your deployment configuration.\nTo help with this, terminus exposes an option called `beforeShutdown` that takes any Promise-returning function.\n\nAlso it makes sense to use the `useExit0 = true` option to signal Kubernetes that the container exited gracefully.\nOtherwise APM's will send you alerts, in some cases.\n\n```javascript\nfunction beforeShutdown () {\n  // given your readiness probes run every 5 second\n  // may be worth using a bigger number so you won't\n  // run into any race conditions\n  return new Promise(resolve =\u003e {\n    setTimeout(resolve, 5000)\n  })\n}\ncreateTerminus(server, {\n  beforeShutdown,\n  useExit0: true\n})\n```\n\n[Learn more](https://github.com/kubernetes/contrib/issues/1140#issuecomment-231641402)\n\n## Limited Windows support\n\nDue to inherent platform limitations, `terminus` has limited support for Windows.\nYou can expect `SIGINT` to work, as well as `SIGBREAK` and to some extent `SIGHUP`.\nHowever `SIGTERM` will never work on Windows because killing a process in the task manager is unconditional, i.e., there's no way for an application to detect or prevent it.\nHere's some relevant documentation from [`libuv`](https://github.com/libuv/libuv) to learn more about what `SIGINT`, `SIGBREAK` etc. signify and what's supported on Windows - [http://docs.libuv.org/en/v1.x/signal.html]([http://docs.libuv.org/en/v1.x/signal.html).\nAlso, see [https://nodejs.org/api/process.html#process_signal_events](https://nodejs.org/api/process.html#process_signal_events).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodaddy%2Fterminus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgodaddy%2Fterminus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodaddy%2Fterminus/lists"}