srv-discovery

A small DNS SRV record based service-discovery helper for Node.js.

Most basic usage example:

const request = require('request-promise-native');
const { resolve } = require('srv-discovery');

// Find an hostname and port where the service is listening and then make a
// HTTP request to it:
resolve('_myservice._tcp.example.com')
.then(addr => request(http://${addr}/path/to/123))
.then(res => console.log(res));

Calling resolve() the first time performs a DNS query. After that answer is
cached for as long as the TTL field allows. Note that while calling resolve()
past TTL triggers a new DNS query resolve() might return a cache address
without waiting for the DNS answer. This behavior can be adjusted using the
maxStale option.

Advanced usage

It is possible to configure the behavior of the resolve() function by
creating a custom Agent:

const { Agent } = require('srv-discovery');
const agent = new Agent({
// Number of seconds, how long past TTL are the cached addresses still
// good for.
maxStale: 120,

// Maximum number of seconds to wait after repeating a failed DNS
// query.
maxRetryWait: 30,

// Maximum number of milliseconds to wait for a DNS answer before
// timing out.
resolveTimeoutMs: 1200,

// List of custom name servers to use. By default the system's
// nameservers are used.
nameservers: ['8.8.8.8', '8.8.4.4:53'],
});

// Resolve addresses using the agent
agent.resolve(...);

It is also possible to give feedback when the resolved address turns out to be
a bad one:

agent.resolveFor('_myservice._tcp.example.com', (addr) => {
return request(http://${addr}/path/to/123);
}).then((res) => {
console.log('response: ', res);
});

In the above example, if the request library rejects with an ECONNREFUSED
error then the agent will see it and know not to return that address from
future resolve() calls. The address will return back to circulation either
when (a) new addresses are received via DNS, or (b) all addresses have been
marked as "bad".

The behavior of resolveFor can be adjusted using various options:

const opts = {
// Maximum number of times to repeat operations that failed because of
a bad address. By default this is set to 0.
maxRetries: 1,

// The function accepts an error as its argument and return whether
// that error was caused by a bad address.
test: (err) => err.name === 'ECONNREFUSED',
};

agent.resolveFor('_myservice._tcp.example.com', opts, (addr) => {
return request(http://${addr}/path/to/123);
});

Known issues / features:

- The SRV "weight" and "priority" parameters are not considered.