{"id":24869986,"url":"https://github.com/deepal/canarify","last_synced_at":"2026-05-04T06:32:12.810Z","repository":{"id":57193542,"uuid":"148114557","full_name":"deepal/canarify","owner":"deepal","description":"A minimalistic library to implement Canary Health-check endpoints in NodeJS microservices","archived":false,"fork":false,"pushed_at":"2018-09-10T20:53:49.000Z","size":6,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-01T03:36:19.682Z","etag":null,"topics":["healthcheck","healthcheck-monitor","microservices","node","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deepal.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-10T07:14:16.000Z","updated_at":"2020-08-25T20:42:18.000Z","dependencies_parsed_at":"2022-09-15T22:20:58.342Z","dependency_job_id":null,"html_url":"https://github.com/deepal/canarify","commit_stats":null,"previous_names":["dpjayasekara/canarify"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepal%2Fcanarify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepal%2Fcanarify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepal%2Fcanarify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deepal%2Fcanarify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deepal","download_url":"https://codeload.github.com/deepal/canarify/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245743330,"owners_count":20665090,"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":["healthcheck","healthcheck-monitor","microservices","node","nodejs"],"created_at":"2025-02-01T03:36:22.863Z","updated_at":"2026-05-04T06:32:12.766Z","avatar_url":"https://github.com/deepal.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Canarify\n\n![alt](https://img.shields.io/badge/stability-alpha-red.svg)\n![alt](https://img.shields.io/badge/node%20version-%3E%3D%20v8.x.x-brightgreen.svg)\n\n\u003e This module is still in alpha and the API is subject to change frequently.\n\nCanarify makes it so easy to implement Canary Healthcheck endpoints in NodeJS microservices. This minimalistic library can be integrated with any web framework including express, restify etc.\n\n### What is a Canary Endpoint anyway?\n\nA Canary endpoint is a healthcheck REST endpoint implemented in a microservice, which upon called will check health of itself, as well as the health of all its dependencies (databases, message queues, other microservices etc.). Compared to the most common type of healthcheck endpoints where a simple message is echoed back to the client, a Canary endpoint can indicate a more accurate status of the microservice functionality. \n\nHowever, there are multiple caveats in implementing Canary endpoints in practice, including\n\n- Canary endpoint taking too long to respond (this is because it will have to check the health of all its dependencies before sending the response)\n- Checking the health of all its dependencies might not be necessary in some cases (serving certain clients might not require all the dependencies up and running)\n- Circular dependencies can cause infinite response time\n\nCanarify attempts to solve most of these problems by providing the features and the flexibility to develop your Canary endpoints as you wish. \n\n### Current status\n\n|Feature|Status|\n|------|----|\n|Multiple dependency support|✅|\n|Status Caching|❌|\n|Custom Timeouts|❌|\n|Circular dependency detection|❌|\n|Client-aware health checks|❌|\n\n### Installation\n\n```\nnpm install canarify\n```\n\n### Usage\n\n```js\nconst Canarify = require('canarify');\nconst canary = new Canarify('myapp');\n\nfunction checkDatabaseHealth() {\n\t// perform an action to check whether the database is up and running\n}\n\ncanary.action('database', checkDatabaseHealth);\n```\n\nIn the above example, the `checkDatabaseHealth` function will check the health of the `database` dependency. More than one healthchecks can also be provided.\n\ne.g,\n\n```js\nconst Canarify = require('canarify');\nconst canary = new Canarify({ name: 'myapp'});\n\n// ... \n\ncanary.action('database', checkDatabaseHealth);\ncanary.action('mq-service', checkMQHealth);\ncanary.action('users-ms', checkBackendHealth);\n```\nTo understand how to implement the healthcheck action functions, see the API reference at the bottom.\n\n### Executing the Canary\n\n`canary.execute` will call all the healthcheck actions and will produce an output containing the results returned by all the healthcheck actions.\n\ne.g,\n\n```\n[ { action: 'database',\n    success: true,\n    result: { dbStatus: 'alive', transPerSec: 12000 },\n    time: 1.2524792599999999 },\n  { action: 'mq-service',\n    success: true,\n    result: { mqsize: 123513, serviceTime: 0.23 },\n    time: 0.000105344 },\n  { action: 'users-ms',\n    success: true,\n    result: { processTime: 123513 },\n    time: 0.500422045 } ]\n```\n\n### Example usage of Canarify with Express\n\n```js\napp.get('/health/canary', (req, res) =\u003e {\n\tcanary.execute().then((results) =\u003e {\n\t\tconst success = results.map(r =\u003e r.status).some(s =\u003e s \u003c 200 || s \u003e= 300);\n  \t\tconst statusCode = success ? 200 : 500;\n\t\tres.status(statusCode).send({\n\t\t\tsuccess,\n\t\t\tresults\n\t\t});\n\t}).catch((err) =\u003e {\n\t\tres.status(500).send({\n\t\t\tsuccess: false\n\t\t});\n\t})\n})\n```\n\n## API Reference\n\n### Constructor: Canarify(options)\n\n- `options.name` (String) Name of the microservice\n\n```js\nconst canary = new Canarify({ name: 'my-microservice' });\n```\n\n### canary.action(dependencyName, healthCheckAction)\n- `dependencyName ` (String) Name of the dependency\n- `healthCheckAction` (Function) Health check function for the dependency. This function should return a promise. If the promise is resolve with data, the resolved data will be included in the `result` property of the given microservice. If the promise is rejected with an error, the property `success` will be set to false and the `result` property value will be the error object.\n\ne.g,\n\n```\n[\n\t{ \n\t\taction: 'database',\n\t\tsuccess: true,\n\t\tresult: { dbStatus: 'alive', transPerSec: 12000 },\n\t\ttime: 1.2524792599999999 \n\t}\n]\n```\n\ne.g, \n\n```js\ncanary.action('users-microservice', () =\u003e {\n\t// send a request to the health check endpoint of the  users-microservice\n});\n```\n\n### canary.execute\n\nThis function does not accept any parameters.\n\ne.g,\n\n```\ncanary.execute()\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepal%2Fcanarify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeepal%2Fcanarify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeepal%2Fcanarify/lists"}