Registry

The Registry interface defines an API for announcing and resolving services in a service registry. A service registry is a key primitive in distributed systems, where multiple applications coordinate to accomplish an objective. The registry allows applications to dynamically look up the locations of needed services, and those services can be scaled out and in on demand, which more instances started when load increases and stopped when load subsides.

Terminology

• An "application" is a program running on a computer that provides one or more services.
• A "domain" is a unique name that identifies a realm of functionality, such as an application or logical grouping of services.
• A "location" is an IP address and port or URL at which an instance of a service is accessible.
• A "service" is a set of functionality exposed for consumption by applications, which is identified by an assigned type string.

API

announce(domain, service, location, cb)

{string} domain - Domain in which to announce service.
{string} service - Type of service being announced.
{string} location - Location of service being announced.
{function} cb - Callback invoked after service has been announced.

Announces availability of a service within a domain at a given location.

The domain parameter provides a way to isolate collections of services that logically comprise a single system. For example, security.example.local. might indicate internal security services while dashboard.example.com. would consist of services that provide a dashboard application served via the web.

The service parameter indicates the type of service being announced. This is an well-known string that will be used by other services that need to consume the announced service. In order to encourage standardization, when announcing services that run over a transport protocol (such as TCP or UDP), it is recommended to use IANA-assigned service names. When announcing services that run over application protocols (such as HTTP, XMPP, etc.), it is recommended to use a link relation, if assigned.

The location parameter is the location at which the announced service is available. When announcing services that run over a transport protocol (such as TCP or UDP), it is recommended to use : notation. When announcing services that run over application protocols (such as HTTP, XMPP, etc.), it is recommended to use an absolute URL.

Examples:

registry.announce('api.example.com.', 'oauth2-token', 'http://127.0.0.1:8080/token', function(err) {
  // ...
});

registry.announce('chat.example.com.', '_irc._tcp', '127.0.0.1:194', function(err) {
  // ...
});

registry.announce('security.example.local.', 'http://schemas.example.com/api/assertion-signing/v1', 'http://127.0.0.1:58101/', function(err) {
  // ...
});

resolve(domain, service, cb)

{string} domain - Domain in which to resolve service.
{string} service - Type of service being resolved.
{function} cb - Callback invoked after service has been resolved.

Resolves a service within a domain to an array of locations.

The callback has arguments (err, locations). The locations argument is an array of locations, formatted as announced by the service (typically a URL or IP address and port).

Examples:

registry.resolve('security.example.local.', 'http://schemas.example.com/api/assertion-signing/v1', function(err, locations) {
  if (err) { throw err; }
  console.log('locations: ' + JSON.stringify(locations));
});