xbrew-stir - Service Discovery Client Library for xbrew

xbrew-stir (pronounced "Cross Brew Stir") is a client library for xbrew, a service discovery server.

Installation

$ yarn add xbrew-stir
-- or --
$ npm install xbrew-stir

Usage

Create a client

To create a client, use DiscoveryNode class.

const client = new DiscoveryNode({
    host: "host.of.xbrew",
    port: 12580
});

Declare a service

To declare a service, use DiscoveryNode#declareService(.) or DiscoveryNode#declareServicePort(.). Both of these method will return a promise of your service ID.

const id = await client.declareService('my_service_type', 'my_address:my_port');

const id = await client.declareServicePort('my_service_type', 12345);
// This method will try to figure out your IP address.
// The guess is pretty good, it works both in physical machines 
// and in Docker

Obtain a service

To obtain a service, use DiscoveryNode#obtainServiceInstance(.).

const instance = await client.obtainServiceInstance('my_service_type', MyServiceClass, myServiceCredential);

The instance will be a ManagedService<MyServiceClass>.

If the service you obtaining is not a gRPC based service, use DiscoveryNode#obtainService(.) which returns a promise of service address.

const address = await client.obtainService('my_service_type');

Using managed service

A managed service will monitor the state the service and handle retry and reconnect for you.

Mark as critical service

By default, all services are marked as non critical. When a service fail, it would print a log and everything goes normally. While when a critical service fail, the application should be terminated.

To mark a managed service as a critical service, use: service.isCritical = true.

Obtaining service class

Managed service does not extend the actual service class (yet). To call methods defined in the service, you need to obtain the instance first. The ManagedService#ref member exposes the service class.

Note that it is impossible to propagate reference in JavaScript. Holding the reference may cause undesired consequences such as unable to automatically reconnect to a new service provider and memory leaks.

client.ref?.action(); // good

const actualService = client.ref!; // DO NOT
actualService.action(); // actualService will not be updated!

Define failing condition

You may want to try to obtain a service for a certain times instead of just retrying indefinitely. You can define a failing condition to specify when to consider an action has failed.

Fail on obtaining service

Using DiscoveryNode#obtainService(Instance)OrFail(.), you can specify the retry count and timeout of obtaining a service at the last parameter:

client.obtainServiceOrFail('my_service_type', {
    tryCount: 3,
    timeout: 2000
});

Failing on reobtaining a service

For managed instance, the fail condition will be used by the ManagedClient class as a failing condition. Service will be considered failed when the failing condition met.

Examples

See fudbarn and helowrd.