BitMonX Disocvery Client for Node.js

A Node.js client for the BisMonX Discovery Server. This client is used to register a service with the discovery server and to send health data to the discovery server.

Features

• Automatic registration of services with the discovery server
• Heartbeat mechanism to renew it's lease with the discovery server
• endpoint for the discovery server to query the health of the service
• Automatic reregistration of services in case of a network failure with retry mechanism
• Automatic Service registry fetching to cache the services in the client
• querying capability to get the services info from the cache as well as the discovery server

Installing

Install the package using npm:

npm install bitmonx-discovery-client --save-dev

Usage

Add BitMonX Discovery Client to your project

First, create a json config file name bitmonx.config.json in the root of your project. The file should contain the following fields:

{
  "discovery": {
    "server": {
      "host": "localhost",
      "port": 8765,
      "protocol": "http"
    },
    "meta": {
      "max_attempts": 10,
      "retry_interval": 1000,
      "fetch_registry_interval": 5000
    }
  },
  "service": {
    "name": "service_name",
    "instance_name": "app_name",
    "mapping": "/api/v1/mapping",
    "host": "localhost",
    "port": 8888,
    "health_check_url": "/bitmonx/health",
    "health_check_interval": 3000,
    "timeout": 5000,
    "heartbeat": {
      "interval": 10000
    },
    "metadata": {
      "protocol": "http",
      "version": "1.0.0",
      "environment": "dev"
    }
  }
}

The bitmonx-discovery-client package provides a class BitMonX that you can use to start the client. The init method of the class takes an express app or http server as an argument. The client will start the service registration and health check endpoints on the express app.

const express = require('express');
const BitMonX = require('bitmonx-discovery-client');
// Create an express app
const app = express();

// Create an instance of BitMonX client
const bitmonx = new BitMonX();
// start the client with the express app
bitmonx.init(app);

Register with BitMonX Discovery & start application heartbeats

const app = express();
bitmonx.init(app);

De-register with BitMonX Discovery & stop application heartbeats

bitmonx.stop();

Get service ID of the application

const serviceId = bitmonx.getServiceId();

Get instance ID of the application

const instanceId = bitmonx.getInstanceId();

Providing Custom Request Middleware

The bitmonx client exposes the ability to modify the outgoint request options object prior to the request being made for BitMonX dicovery server. This will be called for every request made to the discovery server. If the middleware returns anything other than an object, the discovery request will immediately fail and perform a retry in background if configured.

const bitmonx = new BitMonX({
  requestMiddleware: (options, callback) => {
    // Modify the options object
    options.headers['Authorization'] = ' Bearer ' + 'token';
    // Call the callback with the modified options object
    callback(options);
});

Querying the local cache for services

The bitmonx client caches the services that are registered with the discovery server. The cache will be invalidate after every fresh registry fetching from the discovery server. You can query the cache to get the services that are registered with the discovery server.

You can query the instances by their registerd instance name or service name. It will return an object containing the service information.

const instance = bitmonx.getInstanceByInstanceName('app_name');
const instances = bitmonx.getInstancesByServiceName('service_name');

Also, you can query the cache using the service mapping. It will return an object containing the service information.

const instances = bitmonx.getServiceByMapping('/api/v1/mapping');

Advanced Configuration Options

Option	Description	Default
requestMiddleware	The middleware function to modify the request options object	null
discovery.server.host	The host of the discovery server	NA
discovery.server.port	The port of the discovery server	NA
discovery.server.protocol	The protocol of the discovery server	http
discovery.meta.max_attempts	The maximum number of attempts to retry the request	10
discovery.meta.retry_interval	The interval between retries in milliseconds	1000
discovery.meta.fetch_registry_interval	The interval between fetching the registry from the discovery server in milliseconds	30000
discovery.meta.fetch_regsitry_filter	The filter to fetch the registry from the discovery server	ALL
service.name	The name of the service	NA
service.instance_name	The name of the instance	NA
service.mapping	The mapping of the service	NA
service.host	The host of the service	NA
service.port	The port of the service	NA
service.health_check_url	The health check URL of the service	/bitmonx/health
service.health_check_interval	The interval between health checks in milliseconds	30000
service.timeout	The timeout for the health check in milliseconds	30000
service.heartbeat.interval	The interval between heartbeats in milliseconds	30000
service.metadata.protocol	The protocol of the service	http
service.metadata.version	The version of the service	1.0.0
service.metadata.environment	The environment of the service	dev

Events

BitMonX client is an instance of EventEmitter. It emits the following events:

Event Name	Description
started	Emitted when the service is started and the client is initialized
registered	Emitted when the service is successfully registered with the discovery server
deregistered	Emitted when the service is successfully deregistered with the discovery server
heartbeat	Emitted when the service sends a heartbeat to the discovery server
registryFetched	Emitted when the service fetches the registry from the discovery server

Contributors

• Shavin Anjitha

Acknowledgement

This project is developed as a part of the BitMonX project.

This project would not have been possible without the support from:

• The developers of async and lodash, which are used in this project.

This project is isnpired from the Eureka Client, which is a Java client for the Eureka server which is used to register services with the Eureka server.

Changelog

See the CHANGELOG file for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.