Copacetic
A package to help your service check the health of its dependencies.
Requirements
Node v6.4.0 and aboveInstallation
npm install @fresh8/copacetic --save
Quick Start - Javascript
const Copacetic = require('@fresh8/copacetic')
const level = require('@fresh8/copacetic').dependencyLevel
const copacetic = Copacetic()
// Register a dependency
copacetic.registerDependency({
name: 'My-Dependency',
url: 'https://my-Dependency.io',
// Defaults to SOFT
level: level.HARD
})
// Check its health
copacetic
.check({
name: 'My-Dependency',
retries: 2
})
.on('healthy', (Dependency) => {
/**
* { name: 'My-Dependency',
* healthy: true/false,
* lastChecked: Date,
* level: 'SOFT'
* }
*/
})
.on('unhealthy', (Dependency) => {
// Handle degraded state...
})
// in promise mode
copacetic.eventEmitterMode = false
copacetic
.check({ name: 'my-web-service' })
.then((res) => {
console.log(`${res.name} is healthy!`)
})
.catch((err) => {
console.log(err)
})
Quick Start - Typescript
import * as Copacetic from '@fresh8/copacetic'
const copacetic = Copacetic('my-service')
const myDependencyOverHttp : Copacetic.DependencyOptions = {
name: 'my-web-service',
url: 'http://example.com'
}
copacetic.registerDependency(myDependencyOverHttp)
instance
.check({ name: 'my-web-service' })
.on('healthy', (res: Copacetic.Health) => {
// do something with your healthy dependency :)
})
.on('unhealthy', (res: Copacetic.Health) => {
// handle degraded state
})
// in promise mode
copacetic.eventEmitterMode = false
async function waitForWebService () {
try {
const res = await instance
.check<Copacetic.Health>({ name: 'my-web-service' })
console.log(`${res.name} is healthy!`)
} catch (err) {
console.log(err)
}
}
Quick Start - cluster mode
const Copacetic = require('@fresh8/copacetic')
const level = require('@fresh8/copacetic').dependencyLevel
const copacetic = Copacetic("A name", false)
Copacetic.cluster.attach(copacetic)
if (process.worker) {
//register your usual dependencies like databases
//use the line below to have the worker ask the master process a full health report
copacetic.checkCluster() //`checkCluster` is only defined if the process is a worker and if you called `attach()`
.then(console.log)
} else {
copacetic.checkAll()
.then(() => {
console.log(copacetic.healthReport) //Contains health information as reported by the workers
})
}
Classes
- Copacetic ⇐
EventEmitter
Typedefs
- HealthReport :
Object
The full health report including isHealthy and dependencies
Copacetic ⇐ EventEmitter
Kind: global classExtends:
EventEmitter
- Copacetic ⇐
EventEmitter
* [new Copacetic([name])](#new_Copacetic_new)
* [.isHealthy](#Copacetic+isHealthy) ⇒ <code>Boolean</code>
* [.healthInfo](#Copacetic+healthInfo) ⇒ <code>Array.<DependencyHealth></code>
* [.healthReport](#Copacetic+healthReport) ⇒ [<code>HealthReport</code>](#HealthReport)
* [.getDependency(dependency)](#Copacetic+getDependency) ⇒ <code>Dependency</code>
* [.isDependencyRegistered(dependency)](#Copacetic+isDependencyRegistered) ⇒ <code>Boolean</code>
* [.registerDependency(opts)](#Copacetic+registerDependency) ⇒ [<code>Copacetic</code>](#Copacetic)
* [.deregisterDependency(name)](#Copacetic+deregisterDependency) ⇒ [<code>Copacetic</code>](#Copacetic)
* [.pollAll([interval], [parallel], [schedule])](#Copacetic+pollAll) ⇒ [<code>Copacetic</code>](#Copacetic)
* [.poll([name], [dependencies], [interval], [parallel], [schedule])](#Copacetic+poll) ⇒ [<code>Copacetic</code>](#Copacetic)
* [.stop()](#Copacetic+stop)
* [.checkAll([parallel])](#Copacetic+checkAll) ⇒ [<code>Copacetic</code>](#Copacetic)
* [.check([name], [dependencies], [retries], [parallel])](#Copacetic+check) ⇒ [<code>Copacetic</code>](#Copacetic)
* [.waitFor(opts)](#Copacetic+waitFor)
* [._checkOne(name, maxDelay)](#Copacetic+_checkOne) ⇒ <code>Promise</code>
* [._checkMany(dependencies, parallel)](#Copacetic+_checkMany) ⇒ <code>Promise</code>
new Copacetic(name)
| Param | Type | Default | Description | | --- | --- | --- | --- | | name |String
| ''
| The name of your service |copacetic.isHealthy ⇒ Boolean
Kind: instance property of Copacetic
Returns:
Boolean
- Copacetic is healthy when all hard dependencies are healthycopacetic.healthInfo ⇒ Array.<DependencyHealth>
Kind: instance property of Copacetic
Returns:
Array.<DependencyHealth>
- Health information on all dependenciescopacetic.healthReport ⇒ HealthReport
Kind: instance property of Copacetic
Returns:
HealthReport
- A full report of health information and dependenciescopacetic.getDependency(dependency) ⇒ Dependency
Kind: instance method of Copacetic
| Param | Type | | --- | --- | | dependency |
Dependency
\| String
| copacetic.isDependencyRegistered(dependency) ⇒ Boolean
Kind: instance method of Copacetic
Returns:
Boolean
- Whether the dependency has been registered| Param | Type | | --- | --- | | dependency |
Dependency
\| String
| copacetic.registerDependency(opts) ⇒ Copacetic
Adds a dependency to a Copacetic instanceKind: instance method of
Copacetic
| Param | Type | Description | | --- | --- | --- | | opts |
Object
| The configuration for a dependency |copacetic.deregisterDependency(name) ⇒ Copacetic
Removes a dependency from a Copacetic instanceKind: instance method of
Copacetic
| Param | Type | Description | | --- | --- | --- | | name |
String
| The name used to identify a dependency |copacetic.pollAll(interval, parallel, schedule) ⇒ Copacetic
Polls the health of all registered dependenciesKind: instance method of
Copacetic
| Param | Type | Default | | --- | --- | --- | | interval |
String
| '5 seconds'
|
| parallel | Boolean
| true
|
| schedule | String
| 'start'
| copacetic.poll(name, dependencies, interval, parallel, schedule) ⇒ Copacetic
Polls the health of a set of dependenciesKind: instance method of
Copacetic
Emits:
Copacetic#event:health
| Param | Type | Default | Description | | --- | --- | --- | --- | | name |
String
| | The identifier of a single dependency to be checked |
| dependencies | Array.<Object>
| | An explicit set of dependencies to be polled |
| interval | String
| '5 seconds'
| |
| parallel | Boolean
| true
| Kick of health checks in parallel or series |
| schedule | String
| 'start'
| Schedule the next check to start (interval - ms) | ms |Example
copacetic.poll({
dependencies: [
{ name: 'my-dep' },
{ name: 'my-other-dep', retries: 2, maxDelay: '2 seconds' }
],
schedule: 'end',
interval: '1 minute 30 seconds'
})
.on('health', (serviceHealth, stop) => {
// Do something with the result
// [{ name: String, health: Boolean, level: HARD/SOFT, lastCheck: Date }]
// stop polling
stop()
})
Examplecopacetic.poll({ name: 'my-dependency' })
.on('health', () => { ... Do something })
copacetic.stop()
stops polling registered dependenciesKind: instance method of
Copacetic
copacetic.checkAll(parallel) ⇒ Copacetic
Checks the health of all registered dependenciesKind: instance method of
Copacetic
| Param | Type | Default | Description | | --- | --- | --- | --- | | parallel |
Boolean
| true
| Kick of health checks in parallel or series |copacetic.check(name, dependencies, retries, parallel) ⇒ Copacetic
Checks the health of a set, or single dependencyKind: instance method of
Copacetic
Emits:
Copacetic#event:health
, Copacetic#event:healthy
, Copacetic#event:unhealthy
| Param | Type | Default | Description | | --- | --- | --- | --- | | name |
String
| | The identifier of a single dependency to be checked |
| dependencies | Array.<Object>
| | An explicit set of dependencies to be checked |
| retries | Integer
| 1
| How many times should a dependency be checked, until it is deemed unhealthy |
| parallel | Boolean
| true
| Kick of health checks in parallel or series |Example
copacetic.check({ name: 'my-dependency' })
Examplecopacetic.check({ name: 'my-dependency', retries: 5 })
.on('healthy', serviceHealth => { ... Do stuff })
.on('unhealthy', serviceHealth => { ... Handle degraded state })
Examplecopacetic.check({ dependencies: [
{ name: 'my-dep' },
{ name: 'my-other-dep', retries: 2, maxDelay: '1 second' }
] })
.on('health', (servicesHealth) => {
// Do something with the result
// [{ name: String, health: Boolean, level: HARD/SOFT, lastCheck: Date }]
})
Examplecopacetic.check({ name: 'my-dependency' })
.then((health) => { ... Do Stuff })
.catch((err) => { ... Handle degraded state })
copacetic.waitFor(opts)
Convenience method that waits for a single, or set of dependencies to become healthy. Calling this means copacetic will keep re-checking indefinitely until the dependency(s) become healthy. If you want more control, use .check().Kind: instance method of
Copacetic
| Param | Type | Description | | --- | --- | --- | | opts |
Object
| options accepted by check() |Example
// wait indefinitely
copacetic.waitFor({ name: 'my-dependency'})
.on('healthy', serviceHealth => { ... Do stuff })
Example// give up after 5 tries
copacetic.waitFor({ name: 'my-dependency', retries: 5})
.on('healthy', serviceHealth => { ... Do stuff })
copacetic.\_checkOne(name, maxDelay) ⇒ Promise
Kind: instance method of Copacetic
| Param | Type | Description | | --- | --- | --- | | name |
String
| The name used to identify a dependency |
| maxDelay | Integer
| The maximum interval of time to wait when retrying |copacetic.\_checkMany(dependencies, parallel) ⇒ Promise
Checks an array of dependencies in parallel or sequantiallyKind: instance method of
Copacetic
| Param | Type | | --- | --- | | dependencies |
Array.<Dependency>
|
| parallel | Boolean
| HealthReport : Object
The full health report including isHealthy and dependenciesKind: global typedef
Properties
| Name | Type | Description | | --- | --- | --- | | isHealthy |
Boolean
| The result of isHealthy |
| Name | String
| |
| dependencies | Array.<DependencyHealth>
| The result of healthInfo |