{"id":28423511,"url":"https://github.com/itteco/graceful-cluster","last_synced_at":"2025-06-25T11:31:17.025Z","repository":{"id":57252955,"uuid":"64152524","full_name":"itteco/graceful-cluster","owner":"itteco","description":"Gracefully restart node.js http cluster with zero downtime. Shutdown server without active inbound connections reset.","archived":false,"fork":false,"pushed_at":"2019-09-11T21:45:58.000Z","size":16,"stargazers_count":22,"open_issues_count":3,"forks_count":9,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-22T00:59:25.793Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/itteco.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}},"created_at":"2016-07-25T17:00:06.000Z","updated_at":"2025-02-18T16:52:03.000Z","dependencies_parsed_at":"2022-09-06T05:20:19.343Z","dependency_job_id":null,"html_url":"https://github.com/itteco/graceful-cluster","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/itteco/graceful-cluster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itteco%2Fgraceful-cluster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itteco%2Fgraceful-cluster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itteco%2Fgraceful-cluster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itteco%2Fgraceful-cluster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itteco","download_url":"https://codeload.github.com/itteco/graceful-cluster/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itteco%2Fgraceful-cluster/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261862955,"owners_count":23221457,"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":[],"created_at":"2025-06-05T09:08:39.172Z","updated_at":"2025-06-25T11:31:17.011Z","avatar_url":"https://github.com/itteco.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Graceful cluster\n\nInstall:\n\n    npm install graceful-cluster\n    \n## How to use\n\n### 1. Enable graceful server shutdown\n\nThis patch will prevent active connections reset when server receives `SIGKILL` or `SIGTERM`. Idle (keep-alive) inbound connections without active requests will be destroyed.\n \nExample 'server.js':\n\n```js\n// Example server with 'express'.\nvar express = require('express');\nvar app = express();\nvar listener = app.listen(8000);\n\nvar GracefulServer = require('graceful-cluster').GracefulServer;\nvar gracefulServer = new GracefulServer({\n    server: listener,\n    shutdownTimeout: 10 * 1000,             // 10 sec.\n});\n```\n    \nGracefulServer options description:\n\n| option                   | info\n| ------------------------ | ---\n|`log`                     | function, custom log function, `console.log` used by default.\n|`server`                  | required, http server instance.\n|`shutdownTimeout`         | ms, force worker shutdown on `SIGTERM` timeout. Defaults to 5000ms.\n \nAlso you can initiate graceful shutdown when needed:\n\n```js\ngracefulServer.shutdown();\n```\n\n### 2. Use simplified cluster initialization\n\nThis cluster wrapper will send `SIGTERM` signal to workers and wait till they finished all requests.\n\nAlso it can gracefully restart all workers one by one with zero cluster downtime on some conditions:\n\n  1. Worker memory used.\n  2. Worker time online.\n  3. Your custom condition: just call `GracefulCluster.gracefullyRestartCurrentWorker()` to restart current worker in `serverFunction`.\n  4. On `SIGUSR2` signal to cluster process.\n\nExample 'cluster.js':\n\n```js\nvar GracefulCluster = require('graceful-cluster').GracefulCluster;\n\nprocess.title = '\u003cyour-cluster-title\u003e';     // Note, process title must be near filename (cluster.js) length, longer title truncated.\n\nGracefulCluster.start({\n    shutdownTimeout: 10 * 1000,             // 10 sec.\n    restartOnTimeout: 5 * 3600 * 1000,      // 5 hours.\n    restartOnMemory: 150 * 1024 * 1024,     // 150 MB.\n    serverFunction: function() {\n        require('./server');                // Your 'server.js' code module with server logic.\n    }\n});\n```\n\nGracefulCluster options description:\n\n| option                   | info\n| ------------------------ | ---\n| `disableGraceful`        | disable graceful shutdown for faster debug.\n| `exitFunction`           | optional, function that is called when the master needs to exit. The default function exits with exit code 0.\n| `log`                    | function, custom log function, `console.log` used by default.\n| `restartOnMemory`        | bytes, optional. restart worker on memory usage.\n| `restartOnTimeout`       | ms, optional. restart worker by timer.\n| `serverFunction`         | **required**, function with worker logic.\n| `shutdownTimeout`        | ms, optional. force worker shutdown on `SIGTERM` timeout. Defaults to 5000ms.\n| `workersCount`           | workers count, if not specified `os.cpus().length` will be used.\n\n### Gracefully restart cluster\n\nGraceful restart performed by `USR2` signal:\n\n```sh\npkill -USR2 \u003cyour-cluster-title\u003e\n```\n\nor\n\n```sh\nkill -s SIGUSR2 \u003ccluster-pid\u003e\n```\n    \nThis method is also good if your app is launched with [forever](https://github.com/foreverjs/forever):\n\n```sh\nforever start cluster.js\n```\n\n### Using with PM2\n\nIf you prefer [PM2](https://github.com/Unitech/pm2) you should use 'server.js' patch only. This will force PM2 to wait until active connections are closed when using:\n\n```sh\npm2 reload \u003cid\u003e\n```\n\nWith PM2 graceful reload don`t forget to set important process parameters:\n\n - `\"instances\": 0`         - use cluster with multiple instances, so one instance will still work when another is reloaded.\n - `\"kill_timeout\": 5000`   - wait more time to allow active connections finish their responses.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitteco%2Fgraceful-cluster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitteco%2Fgraceful-cluster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitteco%2Fgraceful-cluster/lists"}