backend-pool/README.md

A module to keep an updated list of healthy backends

# backend-pool

A module to keep an updated list of healthy backends. It ensures background healthchecking according to the defined options and support great customization.

## How to use

	const BackendPool = require('backend-pool');
	
	const pool = new BackendPool({
	  healthcheck:   '/health',     // default healthcheck path
	  healthyAfter:      3,         // successful responses
	  unhealthyAfter:    2,         // unsuccessful response
	  removeAfter:      10,         // unsuccessful reponses
	  checkInterval:  5000,         // ms
	  checkTimeout:   1000,         // ms
	  isHealthy:      (res, cb) => { cb(true|false) },
	});

	pool.add('http://whatever.net');
	pool.add({
	  address: 'http://xpto.etc',
	  unhealthyAfter: 1,
	  checkInterval: 20000
	});

	setInterval(() => console.log(pool.getHealthyAddresses()), 10000);



## Supported options

All options can be passed to the constructor as defaults and can also be passed to the `.add({...})` method if they are backend-specific settings.

- `healthcheckPath`: The healthcheck path to be used. Mandatory to be defined at construction time or as `.add()` option;
- `healthyAfter`: Number of consecutive successful responses to consider a backend as 'healthy'; (default: 3);
- `unhealthyAfter`: Number of consecutive unsuccessful responses to consider a backend as 'unhealthy'; (default: 1);
- `removeAfter`: Number of consecutive unsuccessful responses to remove a backend from the pool; A value of `undefined` or `null` means backends are never removed; (default: `undefined`);
- `checkInterval`: The time (in ms) between health checks; (default: 10000);
- `checkTimeout`: The maximum time to wait for a healthcheck endpoint to answer; (default: 1000);
- `isHealthy`: A function which decides if a response represents a healthy state; The function arguments are `(httpResponse, callback)`; If you need the response data, you'll need to read it from the stream; (default: 200 status code).


## Events

Both the backend pool and the individual backend objects (returned by `.add()` and `.get*()`) emit events.

- `healthy`: Notifies when a backend was considered healthy;
- `unhealthy`: Notifies when a backend was considered unhealthy;
- `removed`: Notified when a backend is going to be removed.


## Methods

A backend pool object supports the following methods:

- `get(address)`: Returns a backend object for a backend with a specific address or `null` in case a backend isn't found;
- `getHealthy()`: Returns a list of backend objects for the backends in healthy state;
- `getByState(state)`: Returns a list of backend objects for the backends in a specific state;
- `getHealthyAddresses()`: Returns a list of backend addresses for the backends in healthy state;
- `add(address|options)`: Adds a backend to the pool (in `NEW` state) by its address (URL) or object containing all the backend-specific options (and an `address` extra options)`; Supports all options defined defined above for the constructor;
- `remove(address|backendObject)`: Removes a backend from the pool;