README
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.