{"id":23176182,"url":"https://github.com/smartiniongithub/fastify-healthcheck","last_synced_at":"2025-06-20T16:06:07.061Z","repository":{"id":33224446,"uuid":"154896400","full_name":"smartiniOnGitHub/fastify-healthcheck","owner":"smartiniOnGitHub","description":"Fastify Plugin to serve responses for health checks","archived":false,"fork":false,"pushed_at":"2024-11-09T16:53:16.000Z","size":83,"stargazers_count":39,"open_issues_count":0,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T06:05:21.038Z","etag":null,"topics":["docker","fastify","fastify-plugin","health-check","kubernetes"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smartiniOnGitHub.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-26T21:28:07.000Z","updated_at":"2025-02-09T16:54:54.000Z","dependencies_parsed_at":"2024-06-18T16:41:55.217Z","dependency_job_id":"445b0066-49a1-411e-9f80-fd390962fc74","html_url":"https://github.com/smartiniOnGitHub/fastify-healthcheck","commit_stats":{"total_commits":98,"total_committers":4,"mean_commits":24.5,"dds":0.05102040816326525,"last_synced_commit":"4e5d4b519337edbe4bceb809417e4be85d5b8765"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartiniOnGitHub%2Ffastify-healthcheck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartiniOnGitHub%2Ffastify-healthcheck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartiniOnGitHub%2Ffastify-healthcheck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smartiniOnGitHub%2Ffastify-healthcheck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smartiniOnGitHub","download_url":"https://codeload.github.com/smartiniOnGitHub/fastify-healthcheck/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299831,"owners_count":20916190,"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":["docker","fastify","fastify-plugin","health-check","kubernetes"],"created_at":"2024-12-18T06:15:41.096Z","updated_at":"2025-04-05T07:03:12.894Z","avatar_url":"https://github.com/smartiniOnGitHub.png","language":"JavaScript","readme":"# fastify-healthcheck\r\n\r\n  [![NPM Version](https://img.shields.io/npm/v/fastify-healthcheck.svg?style=flat)](https://npmjs.org/package/fastify-healthcheck/)\r\n  [![NPM Downloads](https://img.shields.io/npm/dm/fastify-healthcheck.svg?style=flat)](https://npmjs.org/package/fastify-healthcheck/)\r\n  [![Code Style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](http://standardjs.com/)\r\n\r\nFastify Plugin to serve responses that report about the web application,\r\nif it's still running and alive (health checks).\r\n\r\nThis is very useful with Containers like `Docker`\r\nand orchestrators like `Kubernetes`.\r\n\r\nWith this plugin, Fastify by default expose an healthcheck route configured\r\nfor `/health` GET requests, and even a script that can be executed to get\r\ncontent via HTTP GET from that running web application.\r\n\r\n\r\n## Usage\r\n\r\nThe plugin can be used without specifying options, so good default values\r\nwill be used, but if needed can be specified:\r\n- `healthcheckUrl`, to set a different uri for the healthcheck route\r\n- `healthcheckUrlDisable`, to not publish the healthcheck route\r\n- `healthcheckUrlAlwaysFail`, to always return failure responses (useful to test failure responses)\r\n- `exposeUptime`, to return even Node.js process uptime (by default disabled)\r\n- `underPressureOptions`, for options to send directly to under-pressure\r\n- `schemaOptions`, for options to use for route schema (no default value provided)\r\n\r\nUnder the hood, the healthcheck status is determined by the \r\n[@fastify/under-pressure](https://www.npmjs.com/package/@fastify/under-pressure) plugin, \r\nused here as a dependency; so it's possible to specify all its\r\nconfiguration options in related option.\r\n\r\nTo use all default values for `healthcheck` options, do not set its options\r\n(or set with undefined values); in that way no `under-pressure` specific\r\noptions will be overridden by them.\r\n\r\n\r\nSample usage:\r\n\r\n```js\r\nconst fastify = require('fastify')()\r\n\r\n// example without specifying options, returning a default healthcheck\r\n// route mapped to '/health' that only reply to a GET request\r\nfastify.register(require('fastify-healthcheck'))\r\n// or\r\n// example with custom healthcheck url and response to always fail\r\n// fastify.register(require('fastify-healthcheck'), { healthcheckUrl: '/custom-health', healthcheckUrlAlwaysFail: true })\r\n//\r\n\r\nfastify.listen({ port: 3000, host: 'localhost' })\r\n\r\n// To test, for example (in another terminal session) do:\r\n// `npm start`, or\r\n// `curl http://127.0.0.1:3000/health` =\u003e returning an HTTP response 200 (OK)\r\n// and a JSON response like: {\"statusCode\":200,\"status\":\"ok\"}\r\n// or run the healthcheck script, for example with:\r\n// `node src/healthcheck http://localhost:3000/health`\r\n// and get the same HTTP response seen before\r\n```\r\n\r\nIn the [example](./example/) folder there is a simple server scripts that\r\nuses the plugin (inline but it's the same using it from npm registry).\r\n\r\nThe file `Dockerfile.example` is a sample container definition for\r\nthe example webapp (using the plugin) to show Docker HEALTHCHECK directive\r\nboth using 'curl' (but commented) and calling the healthcheck script\r\navailable by the plugin.\r\nFor convenience, all Docker commands have been defined in `package.json`,\r\nto run many of them in a simple way (with `npm run custom-command`),\r\nlike in the following sequence:\r\n- `docker:build`, to build the image, where the entry point is the example\r\n- `docker:build:fail`, to build the image, but as entry point the example\r\n  that is triggering the `Service Unavailable` error (HTTP 503) in the\r\n  healthcheck route\r\n- `docker:run`, to start the container from generated image, \r\n  in detached mode\r\n- `docker:healthcheck-manual`, to run the healthcheck script in the\r\n  container but manually\r\n- `docker:status`, to get the health status of the container\r\n- and others like: `docker:inspect` (interactive), `docker:log`\r\n  (\u003cCTRL\u003eC to close), `docker:process`, etc ...\r\n- `docker:stop`, to stop running container\r\n- `docker:clean`, to remove generated image\r\n\r\n\r\n## Requirements\r\n\r\nFastify ^5.0.0 , Node.js 20 LTS (20.9.0) or later.\r\nNote that plugin releases 4.x are for Fastify 4.x, 5.x for Fastify 5.x, etc.\r\n\r\n\r\n## Sources\r\n\r\nSource code is all inside main repo:\r\n[fastify-healthcheck](https://github.com/smartiniOnGitHub/fastify-healthcheck).\r\n\r\nDocumentation generated from source code (library API):\r\n[here](https://smartiniongithub.github.io/fastify-healthcheck/).\r\n\r\n\r\n## Note\r\n\r\nTo fully encapsulate `under-pressure` features inside the scope \r\nof this plugin, the plugin is not exposed by [fastify-plugin](https://github.com/fastify/fastify-plugin);\r\nfor more info look [here](https://github.com/fastify/fastify/blob/master/docs/Plugins.md#handle-the-scope), [here](https://github.com/fastify/fastify/blob/master/docs/Plugins-Guide.md#how-to-handle-encapsulation-and-distribution).\r\n\r\nThe plugin map a default endpoint on the URI `/health` to be\r\ncalled via GET, but it's possible to change it with the setting 'url'\r\nin plugin options.\r\n\r\nThe plugin exposes even another script that tries to get some content\r\n(via HTTP GET) from the current web application where it's running.\r\nIn a container environment this could be useful to let containers runtime\r\ndo the healthcheck without the need to use other tools\r\nlike `curl` or `wget` that must be available in the container.\r\n\r\nBoth approaches could be useful in most common cases, like\r\nKubernetes HTTP GET, or Kubernetes EXEC or Docker HEALTHCHECK,\r\nor others similar.\r\n\r\nNote that the healthcheck script gets the URL to call from the command-line,\r\nbut if not specified it will use a default value of \r\n[http://localhost:3000/health](http://localhost:3000/health).\r\n\r\nTo execute the healthcheck script from another Node.js project/package, \r\nyou need to run something like: \r\n`node node_modules/fastify-healthcheck/src/healthcheck http://localhost:8000/health`,\r\nwith the webapp exposed to the port `8000` in this case.\r\n\r\n\r\n## License\r\n\r\nLicensed under [Apache-2.0](./LICENSE).\r\n\r\n----\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartiniongithub%2Ffastify-healthcheck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmartiniongithub%2Ffastify-healthcheck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmartiniongithub%2Ffastify-healthcheck/lists"}