{"id":17188254,"url":"https://github.com/jclem/clusterflock","last_synced_at":"2025-04-13T19:14:05.203Z","repository":{"id":14633430,"uuid":"17350965","full_name":"jclem/clusterflock","owner":"jclem","description":"a clustering server for node that speaks in signals","archived":false,"fork":false,"pushed_at":"2014-10-27T18:05:23.000Z","size":340,"stargazers_count":9,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-10T17:31:09.036Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"npmjs.org/package/clusterflock","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/jclem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-03-03T00:48:38.000Z","updated_at":"2023-10-28T21:56:27.000Z","dependencies_parsed_at":"2022-09-17T10:30:58.157Z","dependency_job_id":null,"html_url":"https://github.com/jclem/clusterflock","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jclem%2Fclusterflock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jclem%2Fclusterflock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jclem%2Fclusterflock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jclem%2Fclusterflock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jclem","download_url":"https://codeload.github.com/jclem/clusterflock/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248766751,"owners_count":21158301,"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":"2024-10-15T01:08:31.564Z","updated_at":"2025-04-13T19:14:05.180Z","avatar_url":"https://github.com/jclem.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clusterflock  [![Build Status](https://travis-ci.org/jclem/clusterflock.png)](https://travis-ci.org/jclem/clusterflock)\n\n![flocking birds](http://cl.ly/image/0e3E400R1n0U/81938785_7755757d8a_m.jpg)\n\nclusterflock is a simple clustering HTTP server for Node. It accepts a single request handler and a hash of options. The goal of clusterflock is to eliminate my own repeated need for a simple clustering server that implements graceful worker shutdown and re-forking of dead workers.\n\n**This package is deprecated.** I wrote a much more well-tested version without the known bugs of clusterflock called [teamster](https://www.npmjs.org/package/teamster).\n\n\n## Installation\n\n```sh\n$ npm install clusterflock --save\n```\n\n## Usage\n\nBy default, clusterflock will fork the number of workers equal to `os.cpus().length`. When it receives a `SIGINT` or `SIGTERM` signal, it will begin attempting to shut down gracefully by ceasing to receive requests and closing all servers after existing requests have been completed.\n\nThe simplest use case of clusterflock is to pass it a single request handler function:\n\n```javascript\nvar clusterflock = require('clusterflock');\n\nclusterflock(function (req, res) {\n  res.end('ok');\n});\n```\n\nSince clusterflock essentially just calls `http.createServer` in the worker process, anything that can be normally passed to that function can be passed to the `clusterflock` main function, including [express](http://expressjs.com) apps:\n\n```javascript\nvar clusterflock = require('clusterflock'),\n    express      = require('express'),\n    app          = express();\n    \napp.use(express.bodyParser()); // \u0026c.\nclusterflock(app);\n```\n\n### Worker Re-forking\n\nWhen a worker disconnects, the master checks the value of its [`suicide`](http://nodejs.org/api/cluster.html#cluster_worker_suicide) attribute. If that value is true, master does nothing. If that value is not true (i.e. the worker died/was killed unintentionally), the master forks a new worker.\n\n## Options\n\nThe `clusterflock` function accepts an options object:\n\n```javascript\nvar clusterflock = require('clusterflock'),\n    app          = require('./lib/app');\n    \nclusterflock(app, {\n  numWorkers: 1,\n  port      : 3000,\n  timeout   : 5000\n});\n```\n \nName         | Type(s)            | Default | Description\n------------ | ------------------ | --------------------------   | ------------------\n`numWorkers` | `Number`           | `os.cpus().length`           | number of worker processes to fork\n`port`       | `Number`, `String` | \u003ccode\u003eprocess.env.PORT \u0026#124;\u0026#124; 5000\u003c/code\u003e   | port the workers will listen on\n`timeout`    | `Number`           | `1000`                       | amount of time after receiving a graceful shutdown signal that the master will immediately kill workers\n\n## Signals\n\nclusterflock responds to signals. [heroku, for example](https://devcenter.heroku.com/articles/dynos#graceful-shutdown-with-sigterm), sends `SIGTERM` to stop and restart dynos, which will cause clusterflock to initiate a graceful shutdown. `SIGINT`, on the other hand, will force clusterflock to shut down immediately.\n\nSignal    | Behavior\n--------- | --------------------------------------------------------\n`SIGTTIN` | Fork an additonal worker\n`SIGTTOU` | Disconnect the least-recently forked worker\n`SIGINT`  | Kill master process (and therefore workers) immediately.\n`SIGTERM` | Forward myself `SIGQUIT`.\n`SIGQUIT` | Attempt a graceful shutdown (stop serving requests, serve remaining requests, and shut down).\n\n## Testing\n\nTo run the tests:\n\n```sh\n$ npm test\n```\n\n## Contributing\n\n1. Fork it.\n2. Create a branch (`git checkout -b my-clusterflock`)\n3. Commit your changes (`git commit -am \"add unicorns\"`)\n4. Push to the branch (`git push origin my-clusterflock`)\n5. Open a [Pull Request](http://github.com/jclem/clusterflock/pulls)\n\n## Meta\n\nThe photo in this readme is by Flickr user [Eugene Zemlyanskiy](http://www.flickr.com/photos/pictureperfectpose/81938785/). It has a [CC BY 2.0](http://creativecommons.org/licenses/by/2.0/) license.\n\n## Thanks, Heroku\n\nWhile I created and maintain this project, it was done while I was an employee\nof [Heroku][heroku] on the Human Interfaces Team, and they were kind enough to\nallow me to open source the work. Heroku is awesome.\n\n[heroku]: https://www.heroku.com/home\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjclem%2Fclusterflock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjclem%2Fclusterflock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjclem%2Fclusterflock/lists"}