{"id":15018973,"url":"https://github.com/soundcloud/dns-endpoint-pool","last_synced_at":"2025-10-19T16:32:08.027Z","repository":{"id":23715566,"uuid":"27088261","full_name":"soundcloud/dns-endpoint-pool","owner":"soundcloud","description":"Manage and load-balance a pool of service endpoints retrieved from a DNS lookup for a service discovery name.","archived":false,"fork":false,"pushed_at":"2024-06-16T11:20:05.000Z","size":175,"stargazers_count":7,"open_issues_count":6,"forks_count":8,"subscribers_count":163,"default_branch":"master","last_synced_at":"2025-01-29T21:22:57.228Z","etag":null,"topics":[],"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/soundcloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2014-11-24T18:14:17.000Z","updated_at":"2021-12-14T09:22:32.000Z","dependencies_parsed_at":"2023-01-13T23:44:59.195Z","dependency_job_id":null,"html_url":"https://github.com/soundcloud/dns-endpoint-pool","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundcloud%2Fdns-endpoint-pool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundcloud%2Fdns-endpoint-pool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundcloud%2Fdns-endpoint-pool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundcloud%2Fdns-endpoint-pool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soundcloud","download_url":"https://codeload.github.com/soundcloud/dns-endpoint-pool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237172111,"owners_count":19266614,"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-09-24T19:52:41.491Z","updated_at":"2025-10-19T16:32:07.717Z","avatar_url":"https://github.com/soundcloud.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## DNS Endpoint Pool\n\nManage and load-balance a pool of service endpoints retrieved from a DNS lookup for a service discovery name.\n\n![Empty pool](https://farm4.staticflickr.com/3480/3192156375_ca9377272a_z.jpg)\n\n## Example\n\nGiven a DNS setup like so:\n\n```shell\n$ dig +tcp +short SRV my.domain.example.com\n0 0 8000 first.example.com.\n0 0 8000 second.example.com.\n0 0 8000 third.example.com.\n```\n\nThis library exposes those service endpoints via an interface which will load balance (using unweighted round-robin\nonly), and apply a circuit breaker to remove failing endpoints from the pool temporarily. Endpoints will be\nautomatically updated on a timer.\n\n```js\nvar DNSEndpointPool = require('dns-endpoint-pool');\n\nvar pool = new DNSEndpointPool('my.domain.example.com', 10000, 5, 10000);\n\nvar endpointInfo = pool.getEndpoint();\nif (endpointInfo) {\n  sendRequest('http://' + endpointInfo.url, function (err) {\n    // let the pool know if the request was successful\n    endpointInfo.callback(err);\n  });\n}\n```\n\nIf the usage of a endpoint is unsuccessful too many times within a window of time, it will be temporarily disabled.\nDuring this time, `getEndpoints()` will not return that endpoint. Afterwards, it will be returned to the pool for one\nsingle usage, and removed again. If that usage is successful, it is restored to the pool fully. If it is unsuccessful,\nit is disabled once again.\n\n## API\n\n### `new DNSEndpointPool(serviceDiscoveryName, ttl, circuitBreakerConfig, onReady)`\n\nCreates a new pool object.\n\n- `serviceDiscoveryName`: the domain name to get endpoint values from\n- `ttl`: the time (in ms) that the DNS lookup values are valid for. They will automatically be refreshed on this\n  interval.\n- `circuitBreakerConfig`: optional configuration for circuit breaker behavior. If specified, errors on a particular endpoint will be tracked and bad endpoints removed from the pool. If none provided, no circuit breaker logic is applied. There are two different circuit-breaker behaviors available:\n  - Errors over time: the CB is configured with the an error threshold within a sliding time window. (eg: 5 errors in 10 seconds)\n    - `maxFailures`: how many failures from a single endpoint before it is removed from the pool.\n    - `failureWindow`: size of the sliding window of time in which the failures are counted.\n    - `resetTimeout`: The timeout before a failing endpoint will be re-entered to the pool and tried again.\n  - Error rate: the CB is configured with the percentage of errors within a sliding window of requests. (eg: 50% errors over 20 requests).\n    - `failureRate`: a number, `0 \u003c n \u003c= 1` that describes the rate at which the endpoint is disabled.\n    - `failureRateWindow`: the number of requests over which to calculate the failure rate.\n    - `resetTimeout`: The timeout before a failing endpoint will be re-entered to the pool and tried again.\n- `onReady`: callback that will be executed after the list of endpoints is fetched for the first time. This does *not* guarantee that the endpoint list is not empty.\n\n### `pool.getEndpoint()`\n\nReturns the next active `endpoint` from the pool, or `null` if none are available. If none are available, the pool will\nemit `'noEndpoints'`. If using circuit breakers, you _must_ call `endpoint.callback(err)` with the result of a call to this endpoint.\n\n### `pool.getStatus()`\n\nReturns an object containing information about the health of the pool. There are three values:\n\n- `total`: The total number of endpoints in the pool, in any state.\n- `unhealthy`: The number of endpoints which are unavailable (eg: due to their circuit breaker being open)\n- `age`: The number of milliseconds since the last successful update of endpoints.\n\n### `endpoint.url`\n\nThe endpoint url (without protocol) from the DNS lookup.\n\n### `endpoint.callback(err)`\n\nA callback which should be executed exactly once for each call to `getEndpoint`. If the `err` is truthy, this will count\nas a failure of the endpoint. If falsey, it marks the endpoint as successful and allows it to remain in the pool.\n\n## Events\n\n- If a request to update the endpoints fails, the pool will emit an `'updateError'` event. The endpoint pool will continue to\n  function, using the previously fetched endpoints.\n- If it is not possible to return any values from `getEndpoints()` (because all endpoints are disabled, for example), the\n  pool will emit `'noEndpoints'`.\n\n\n```js\nvar pool = new DNSEndpointPool('my.domain.example.com', 10000, {\n  maxFailures: 5,\n  failureWindow: 10000,\n  resetTimeout: 10000\n});\n\npool.on('updateError', function (err) {\n  log('Could not fetch endpoints');\n});\npool.on('noEndpoints', function () {\n  log('No endpoints available');\n})\n```\n\n## Photo credit\n\n[Photo](https://www.flickr.com/photos/perspective23/3192156375) of a scary pool by [perspective23](https://www.flickr.com/photos/perspective23/) used under [CC license](https://creativecommons.org/licenses/by-nc-nd/2.0/)\n\n## License\n\nMIT, SoundCloud.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoundcloud%2Fdns-endpoint-pool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoundcloud%2Fdns-endpoint-pool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoundcloud%2Fdns-endpoint-pool/lists"}