{"id":16255293,"url":"https://github.com/qubyte/dominion","last_synced_at":"2025-04-08T13:18:47.071Z","repository":{"id":15521771,"uuid":"18256173","full_name":"qubyte/dominion","owner":"qubyte","description":"Express domain middleware.","archived":false,"fork":false,"pushed_at":"2017-09-14T23:17:16.000Z","size":13,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-04-26T19:22:03.471Z","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/qubyte.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":"2014-03-30T02:54:36.000Z","updated_at":"2014-04-21T11:01:56.000Z","dependencies_parsed_at":"2022-09-06T17:20:57.929Z","dependency_job_id":null,"html_url":"https://github.com/qubyte/dominion","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/qubyte%2Fdominion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qubyte%2Fdominion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qubyte%2Fdominion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qubyte%2Fdominion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qubyte","download_url":"https://codeload.github.com/qubyte/dominion/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247847614,"owners_count":21006100,"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-10T15:29:20.847Z","updated_at":"2025-04-08T13:18:47.037Z","avatar_url":"https://github.com/qubyte.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dominion\n\n[![Coverage Status](https://img.shields.io/coveralls/qubyte/dominion.svg?style=flat)](https://coveralls.io/r/qubyte/dominion?branch=master)\n[![Build Status](https://img.shields.io/travis/qubyte/dominion/master.svg?style=flat)](https://travis-ci.org/qubyte/dominion)\n\n[![npm](https://img.shields.io/npm/v/dominion.svg?style=flat)](https://npmjs.org/dominion)\n[![npm](https://img.shields.io/github/release/qubyte/dominion.svg?style=flat)](https://github.com/qubyte/dominion/releases)\n\nDomain middleware for Express and vanilla Node.js. Dominion has no production dependencies.\n\nDominion will attempt to gracefully close all servers registered with it when any requests using\nthe domain middleware throw an otherwise uncaught exception. Dominion is intended to be used with\non cluster workers, but will also work on master instances to make testing a little easier for its\ndependents.\n\n## Usage\n\nDominion provides both a middleware function and a function to add server instances. Dominion is\nslightly atypical in that it requires references to all server instances that a worker is running.\nThis middleware must only be used on cluster worker processes. Cluster and domain are two sides of\nthe same coin, so this should be no surprise.\n\n```javascript\nvar dominion = require('dominion');\nvar express = require('express');\n\nvar app = express();\n\n// Add at the beginning of the middleware chain.\napp.use(dominion.middleware);\n\n// Add other middleware and routes...\n\n// The server object is returned from `app.listen`.\nvar server = app.listen(3000, function () {\n    console.log('Server listening.');\n});\n\n// Register the server object with dominion. This is required!\ndominion.addServer(server);\n\n// Give dominion a chance to finish its job, but avoid hangs.\ndominion.once('shutdown', function () {\n    var killtimer = setTimeout(function () {\n        process.exit(1);\n    }, 5000);\n\n    killtimer.unref();\n});\n```\n\nTo use with vanilla Node HTTP servers, you can spoof the `vanilla` method:\n\n```javascript\nvar http = require('http');\nvar dominion = require('dominion');\n\n// Give dominion a chance to finish its job, but avoid hangs.\ndominion.once('shutdown', function () {\n    var killtimer = setTimeout(function () {\n        process.exit(1);\n    }, 5000);\n\n    killtimer.unref();\n});\n\n\n// Create a server.\nvar server = http.createServer(function (req, res) {\n    'use strict';\n\n    dominion.vanilla(req, res);\n\n    // Other handler logic...\n});\n\n// Register the server with dominion.\ndominion.addServer(server);\n\nserver.listen(3000);\n```\n\nYou should register all servers with dominion. If any exceptions are generated by a request or a\nresponse, then all registered servers are closed to stop new incoming connections. You should\nregister a listener on the `'shutdown'` event to for the server to close after some time, in case\nthe server hangs.\n\n## Methods\n\n### `dominion.middleware(req, res, next)`\n\nThis is a traditional express middleware. If an error is caught by the domain, then it attempts to\nsend a 500 response and close all registered servers.\n\n### `dominion.vanilla(req, res)`\n\nThis behaves much like the middleware, but is intended for use with vanilla Node HTTP servers.\nPlace at the top of your response handler.\n\n### `dominion.addServer(server)`\n\nAdd the HTTP server object to the dominion module. All registered servers will be closed if dominion\nintercepts an error. Since dominion will shut down all servers before quitting the worker process,\nall should be registered. On a cluster worker, all servers will be closed whether of not they have\nbeen registered.\n\n## Events\n\nEvents for logging and shutdown are emitted by dominion. It is assumed that you'll have your own\nlogging solution.\n\n### `shutdown`: `(request, response, error, sendError)`\n\nEmitted when the domain inside the middleware catches an error. You should register a listener on\nthis event to set a timeout to force the process to close if it is hung for whatever reason.\nListeners will receive the arguments:\n\n - `request` - The request object.\n - `response` - The response object.\n - `error` - The error caught by the domain middleware.\n - `sendError` - This will be defined only if an error occurs when trying to send a response.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqubyte%2Fdominion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqubyte%2Fdominion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqubyte%2Fdominion/lists"}