{"id":15916897,"url":"https://github.com/jquatier/eureka-js-client","last_synced_at":"2025-05-15T17:07:27.417Z","repository":{"id":36489713,"uuid":"40795324","full_name":"jquatier/eureka-js-client","owner":"jquatier","description":"JS implementation of a client for Eureka (https://github.com/Netflix/eureka), the Netflix OSS service registry.","archived":false,"fork":false,"pushed_at":"2024-07-25T09:10:02.000Z","size":297,"stargazers_count":330,"open_issues_count":11,"forks_count":101,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-27T10:42:11.985Z","etag":null,"topics":["cloud","eureka-js-client","eureka-server","microservices","netflix","nodejs","service-discovery"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":false,"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/jquatier.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-08-16T01:46:04.000Z","updated_at":"2025-03-07T08:33:22.000Z","dependencies_parsed_at":"2024-06-18T12:31:03.981Z","dependency_job_id":"d243858e-0144-4933-be6f-062c78dff290","html_url":"https://github.com/jquatier/eureka-js-client","commit_stats":{"total_commits":180,"total_committers":21,"mean_commits":8.571428571428571,"dds":"0.44999999999999996","last_synced_commit":"c83bbfb998104c98f96e4ec15078fe8296da7e53"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jquatier%2Feureka-js-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jquatier%2Feureka-js-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jquatier%2Feureka-js-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jquatier%2Feureka-js-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jquatier","download_url":"https://codeload.github.com/jquatier/eureka-js-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251971012,"owners_count":21673353,"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":["cloud","eureka-js-client","eureka-server","microservices","netflix","nodejs","service-discovery"],"created_at":"2024-10-06T18:06:35.716Z","updated_at":"2025-05-15T17:07:22.409Z","avatar_url":"https://github.com/jquatier.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# eureka-js-client\n[![npm version](https://badge.fury.io/js/eureka-js-client.svg)](http://badge.fury.io/js/eureka-js-client) [![Build Status](https://api.travis-ci.org/jquatier/eureka-js-client.svg?branch=master)](https://travis-ci.org/jquatier/eureka-js-client) [![Coverage Status](https://coveralls.io/repos/jquatier/eureka-js-client/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/jquatier/eureka-js-client?branch=master) [![Dependency Status](https://david-dm.org/jquatier/eureka-js-client.svg)](https://david-dm.org/jquatier/eureka-js-client) [![bitHound Overall Score](https://www.bithound.io/github/jquatier/eureka-js-client/badges/score.svg)](https://www.bithound.io/github/jquatier/eureka-js-client)\n\nA JavaScript implementation of a client for Eureka (https://github.com/Netflix/eureka), the Netflix OSS service registry.\n\n![](./img/eureka-js-client.jpg)\n\n## Usage\n\nFirst, install the module into your node project:\n\n```shell\nnpm install eureka-js-client --save\n```\n\n### Add Eureka client to a Node application.\n\nThe Eureka module exports a JavaScript function that can be constructed.\n\n```javascript\nimport Eureka from 'eureka-js-client';\n\n// Or, if you're not using a transpiler:\nconst Eureka = require('eureka-js-client').Eureka;\n\n// example configuration\nconst client = new Eureka({\n  // application instance information\n  instance: {\n    app: 'jqservice',\n    hostName: 'localhost',\n    ipAddr: '127.0.0.1',\n    port: 8080,\n    vipAddress: 'jq.test.something.com',\n    dataCenterInfo: {\n      name: 'MyOwn',\n    },\n  },\n  eureka: {\n    // eureka server host / port\n    host: '192.168.99.100',\n    port: 32768,\n  },\n});\n```\n\nThe Eureka client searches for the YAML file `eureka-client.yml` in the current working directory. It further searches for environment specific overrides in the environment specific YAML files (e.g. `eureka-client-test.yml`). The environment is typically `development` or `production`, and is determined by environment variables in this order: `EUREKA_ENV`, if present, or `NODE_ENV`, if present. Otherwise it defaults to `development`. The options passed to the constructor overwrite any values that are set in configuration files.\n\nYou can configure a custom directory to load the configuration files from by specifying a `cwd` option in the object passed to the `Eureka` constructor.\n\n```javascript\nconst client = new Eureka({\n  cwd: `${__dirname}/config`,\n});\n```\n\nIf you wish, you can also overwrite the name of the file that is loaded with the `filename` property. You can mix the `cwd` and `filename` options.\n\n```javascript\nconst client = new Eureka({\n  filename: 'eureka',\n  cwd: `${__dirname}/config`,\n});\n```\n\n### Register with Eureka \u0026 start application heartbeats\n\n```javascript\nclient.start();\n```\n\n### De-register with Eureka \u0026 stop application heartbeats\n\n```javascript\nclient.stop();\n```\n\n### Get Instances By App ID\n\n```javascript\nconst instances = client.getInstancesByAppId('YOURSERVICE');\n```\n\n### Get Instances By Vip Address\n\n```javascript\nconst instances = client.getInstancesByVipAddress('YOURSERVICEVIP');\n```\n\n### Providing Custom Request Middleware\nThe client exposes the ability to modify the outgoing [request](https://www.npmjs.com/package/request) options object prior to a eureka call. This is useful when adding authentication methods such as OAuth, or other custom headers. This will be called on every eureka request, so it highly suggested that any long-lived external calls made in the middleware are cached or memoized. If the middleware returns anything other than an object, the eureka request will immediately fail and perform a retry if configured.\n\n```javascript\n// example using middleware to set-up HTTP authentication\nconst client = new Eureka({\n  requestMiddleware: (requestOpts, done) =\u003e {\n    requestOpts.auth = {\n      user: 'username',\n      password: 'somepassword'\n    };\n    done(requestOpts);\n  }\n});\n```\n\n## Configuring for AWS environments\n\nFor AWS environments (`dataCenterInfo.name == 'Amazon'`) the client has built-in logic to request the AWS metadata that the Eureka server requires. See [Eureka REST schema](https://github.com/Netflix/eureka/wiki/Eureka-REST-operations) for more information.\n\n```javascript\n// example configuration for AWS\nconst client = new Eureka({\n  // application instance information\n  instance: {\n    app: 'jqservice',\n    port: 8080,\n    vipAddress: 'jq.test.something.com',\n    statusPageUrl: 'http://__HOST__:8080/info',\n    healthCheckUrl: 'http://__HOST__:8077/healthcheck',\n    homePageUrl: 'http://__HOST__:8080/',\n    dataCenterInfo: {\n      name: 'Amazon',\n    },\n  },\n  eureka: {\n    // eureka server host / port / EC2 region\n    host: 'eureka.test.mydomain.com',\n    port: 80,\n  },\n});\n```\n\nNotes:\n  - Under this configuration, the instance `hostName` and `ipAddr` will be set to the public host and public IP that the AWS metadata provides. You can set `eureka.useLocalMetadata` to `true` to use the private host and private IP address instead.\n  - If you want to register using the IP address as the hostname, set `eureka.preferIpAddress` to `true`. This may be used in combination with `eureka.useLocalMetadata` for selecting the private or public IP.\n  - For status and healthcheck URLs, you may use the replacement key of `__HOST__` to use the host from the metadata.\n  - Metadata fetching can be disabled by setting `config.eureka.fetchMetadata` to `false` if you want to provide your own metadata in AWS environments.\n\n### Looking up Eureka Servers using DNS\nIf your have multiple availability zones and your DNS entries set up according to the Wiki article [Deploying Eureka Servers in EC2](https://github.com/Netflix/eureka/wiki/Deploying-Eureka-Servers-in-EC2#configuring-eips-using-dns), you'll want to set `config.eureka.useDns` to `true` and set `config.eureka.ec2Region` to the current region (usually this can be pulled into your application via an environment variable, or passed in directly at startup).\n\nThis will cause the client to perform a DNS lookup using `config.eureka.host` and `config.eureka.ec2Region`. The naming convention for the DNS TXT records required for this to function is also described in the Wiki article above. This feature will also work in non-EC2 environments as long as the DNS records conform to the same convention. The results of the DNS resolution are cached in memory and refreshed every 5 minutes by default (set `config.eureka.clusterRefreshInterval` to override).\n\n##### Zone Affinity\nBy default, the client will first try to connect to the Eureka server located in the same availability-zone as it's currently in. If `availability-zone` is not set in the instance metadata, a random server will be chosen. This also applies when statically configuring the cluster (mapped by zone, see below). To disable this feature, set `config.eureka.preferSameZone` to `false`, and a random server will be chosen.\n\n### Statically configuring Eureka server list\nWhile the recommended approach for resolving the Eureka cluster is using DNS (see above), you can also statically configure the list of Eureka servers by zone or just using a simple default list. Make sure to provide the full protocol, host, port, and path to the Eureka REST service (usually `/apps/`) when using this approach.\n\n#### Static cluster configuration (map by zone)\n\n```javascript\n// example configuration for AWS (static map of Eureka cluster by availability-zone)\nconst client = new Eureka({\n  instance: {\n    ... // application instance information\n  },\n  eureka: {\n    availabilityZones: {\n      'us-east-1': ['us-east-1c', 'us-east-1d', 'us-east-1e']\n    },\n    serviceUrls: {\n      'us-east-1c': [\n        'http://ec2-fake-552-627-568-165.compute-1.amazonaws.com:7001/eureka/v2/apps/', 'http://ec2-fake-368-101-182-134.compute-1.amazonaws.com:7001/eureka/v2/apps/'\n      ],\n      'us-east-1d': [...],\n      'us-east-1e': [...]\n    }\n  },\n});\n```\n\n#### Static cluster configuration (list)\n\n```javascript\n// example configuration (static list of Eureka cluster servers)\nconst client = new Eureka({\n  instance: {\n    ... // application instance information\n  },\n  eureka: {\n    serviceUrls: {\n      default: [\n        'http://ec2-fake-552-627-568-165.compute-1.amazonaws.com:7001/eureka/v2/apps/', 'http://ec2-fake-368-101-182-134.compute-1.amazonaws.com:7001/eureka/v2/apps/'\n      ]\n    }\n  },\n});\n```\n\n## Advanced Configuration Options\noption | default value | description\n---- | --- | ---\n`requestMiddleware` | noop | Custom middleware function to modify the outgoing [request](https://www.npmjs.com/package/request) to eureka\n`logger` | console logging | logger implementation for the client to use\n`shouldUseDelta` | false | Experimental mode to fetch deltas from eureka instead of full registry on update\n`eureka.maxRetries` | `3` | Number of times to retry all requests to eureka\n`eureka.requestRetryDelay` | `500` | milliseconds to wait between retries. This will be multiplied by the # of failed retries.\n`eureka.heartbeatInterval` | `30000` | milliseconds to wait between heartbeats\n`eureka.registryFetchInterval` | `30000` | milliseconds to wait between registry fetches\n`eureka.registerWithEureka` | `true` | enable/disable Eureka registration\n`eureka.fetchRegistry` | `true` | enable/disable registry fetching\n`eureka.filterUpInstances` | `true` | enable/disable filtering of instances with status === `UP`\n`eureka.servicePath` | `/eureka/v2/apps/` | path to eureka REST service\n`eureka.ssl` | `false` | enable SSL communication with Eureka server\n`eureka.useDns` | `false` | look up Eureka server using DNS, see [Looking up Eureka Servers in AWS using DNS](#looking-up-eureka-servers-in-aws-using-dns)\n`eureka.preferSameZone` | `true` | enable/disable zone affinity when locating a Eureka server\n`eureka.clusterRefreshInterval` | `300000` | milliseconds to wait between refreshing cluster hosts (DNS resolution only)\n`eureka.fetchMetadata` | `true` | fetch AWS metadata when in AWS environment, see [Configuring for AWS environments](#configuring-for-aws-environments)\n`eureka.useLocalMetadata` | `false` | use local IP and local hostname from metadata when in an AWS environment.\n`eureka.preferIpAddress` | `false` | use IP address (local or public) as the hostname for registration when in an AWS environment.\n\n## Events\n\nEureka client is an instance of `EventEmitter` and provides the following events for consumption:\n\nevent | data provided | description\n---- | --- | ---\n`started` | N/A | Fired when eureka client is fully registered and all registries have been updated.\n`registered` | N/A | Fired when the eureka client is registered with eureka.\n`deregistered` | N/A | Fired when the eureka client is deregistered with eureka.\n`heartbeat` | N/A | Fired when the eureka client has successfully renewed it's lease with eureka.\n`registryUpdated` | N/A | Fired when the eureka client has successfully update it's registries.\n\n## Debugging\n\nThe library uses [request](https://github.com/request/request) for all service calls, and debugging can be turned on by passing `NODE_DEBUG=request` when you start node. This allows you you double-check the URL being called as well as other request properties.\n\n```shell\nNODE_DEBUG=request node example.js\n```\n\nYou can also turn on debugging within the library by setting the log level to debug:\n\n```javascript\nclient.logger.level('debug');\n```\n\n## Known Issues\n\n### 400 Bad Request Errors from Eureka Server\n\nLater versions of Eureka require a slightly different JSON POST body on registration. If you are seeing 400 errors on registration it's probably an issue with your configuration and it could be the formatting differences below. The history behind this is unclear and there's a discussion [here](https://github.com/Netflix-Skunkworks/zerotodocker/issues/46). The main differences are:\n\n- `port` is now an object with 2 required fields `$` and `@enabled`.\n- `dataCenterInfo` has an `@class` property.\n\nSee below for an example:\n\n```javascript\nconst client = new Eureka({\n  // application instance information\n  instance: {\n    app: 'jqservice',\n    hostName: 'localhost',\n    ipAddr: '127.0.0.1',\n    port: {\n      '$': 8080,\n      '@enabled': true,\n    },\n    vipAddress: 'jq.test.something.com',\n    dataCenterInfo: {\n      '@class': 'com.netflix.appinfo.InstanceInfo$DefaultDataCenterInfo',\n      name: 'MyOwn',\n    },\n  },\n  eureka: {\n    // eureka server host / port\n    host: '192.168.99.100',\n    port: 32768,\n  },\n});\n```\nIf you are planning on connecting to a eureka service in AWS you will need to add the corresponding `dataCenterInfo` information:\n\n```javascript\n\n  dataCenterInfo: {\n   '@class': 'com.netflix.appinfo.AmazonInfo',\n   name: 'Amazon',\n  }\n```\n\n### 404 Not Found Errors from Eureka Server\n\nThis probably means that the Eureka REST service is located on a different path in your environment. The default is `http://\u003cEUREKA_HOST\u003e/eureka/v2/apps`, but depending on your setup you may need to set `eureka.servicePath` in your configuration to another path. The REST service could be hung under `/eureka/apps/` or possibly `/apps/`.\n\n### Usage with Spring Cloud\n\nIf you are using Spring Cloud you'll likely need the following settings:\n\n  - Set `eureka.servicePath` in your config to `/eureka/apps/`.\n  - Use the newer style of the configuration [here](#400-bad-request-errors-from-eureka-server) or Spring Cloud Eureka will throw a 500 error.\n  - Set `statusPageUrl` to a valid URL for your application, Spring Cloud [seems to require this](https://github.com/jquatier/eureka-js-client/issues/113) when the instance information is parsed.\n  - Put single quotes around boolean `@enabled`. Unfortunately, a 500 error regarding parsing [seems to occur](https://github.com/jquatier/eureka-js-client/issues/63) without that.\n\nBelow is an example configuration that should work with Spring Cloud Eureka server:\n\n```javascript\nconst client = new Eureka({\n  instance: {\n    app: 'jqservice',\n    hostName: 'localhost',\n    ipAddr: '127.0.0.1',\n    statusPageUrl: 'http://localhost:8080/info',\n    port: {\n      '$': 8080,\n      '@enabled': 'true',\n    },\n    vipAddress: 'jq.test.something.com',\n    dataCenterInfo: {\n      '@class': 'com.netflix.appinfo.InstanceInfo$DefaultDataCenterInfo',\n      name: 'MyOwn',\n    },\n  },\n  eureka: {\n    host: '192.168.99.100',\n    port: 32768,\n    servicePath: '/eureka/apps/'\n  },\n});\n```\n\n## Tests\n\nThe test for the module are written using mocha and chai. To run the unit tests, you can use the gulp `test` task:\n\n```shell\ngulp test\n```\n\nIf you wish to have the tests watch the `src/` and `test/` directories for changes, you can use the `test:watch` gulp task:\n\n```shell\ngulp test:watch\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjquatier%2Feureka-js-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjquatier%2Feureka-js-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjquatier%2Feureka-js-client/lists"}