Service registry for Node.js on top of etcd
Latest commit 6f87a5f Mar 10, 2015 @mafintosh 2.1.1
Failed to load latest commit information.
.gitignore first commit Jan 29, 2014
LICENSE add full license text Aug 21, 2014 updated docs Apr 28, 2014
bin.js fixed slack and wait timeouts Apr 14, 2014
example.js added example Jan 29, 2014
index.js fix cb typo Mar 10, 2015
package.json 2.1.1 Mar 10, 2015
test.js new registry for each test Apr 27, 2014


Service registry for Node.js on top of etcd

npm install etcd-registry

To install the command line tool

npm install -g etcd-registry
etcd-registry help


var registry = require('etcd-registry');

// Pass the nodes in your cluster in a connection string
var services = registry(',,');

// Join the registry
services.join('my-service-name', {port:8080});

// Wait a bit and do a lookup
services.lookup('my-service-name', function(err, service) {
    console.log('Found the following service:');

Running the above example will produce the following output

Found the following service:
    name: 'my-service-name',
    port: 8080,
    hostname: '',
    host: '',
    url: ''

Full api

  • services = registry(connection-string) Create a new registry client
  • services.join(name, service, [cb]) Join the registry with a new service
  • services.leave([name], [cb]) Leave the registry. Omit the name to remove local services
  • services.lookup(name, cb) Lookup a single service
  • services.list([name], cb) List all services as an array. Omit the name to list all services

Connection string

The connection has the following format


The protocol can be https or http and defaults to http. If you set a namespace all keys will be prefixed with the value. If you do not specify a port in the hosts 4001 will be used (default etcd port).


Services are just JSON documents. etcd-registry will add a default hostname and a couple of other properties. An example of a service document could be:

    name: 'my-service',
    port: 8080,
    hostname: '',       // added by etcd-registry
    host: '',      // added by etcd-registry
    url: '' // added by etcd-registry

These documents are saved in etcd with a TTL of 10s. Every 5s etcd-registry will send a heartbeat for each service to the registry which resets the expiration counter. If possible you should call services.leave() before exiting your service process. Otherwise your service will be garbage collected after (at most) 10s

Fault tolerance

If a operation fails etcd-registry will try another node in the cluster until it has tried everyone. Every once in a while etcd-registry will ping your cluster to see if new machines has joined and update the connection string