@fresh8/copacetic

A package to help your service check the health of its dependencies.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
@fresh8/copacetic
5.0.02 years ago7 years agoMinified + gzip package size for @fresh8/copacetic in KB

Readme

Copacetic
JavaScript Style Guide Coverage Status CircleCI
A package to help your service check the health of its dependencies.

Requirements

Node v6.4.0 and above

Installation

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

CopaceticEventEmitter

Typedefs

HealthReport : Object

The full health report including isHealthy and dependencies


Copacetic ⇐ EventEmitter

Kind: global class
Extends: 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 healthy

copacetic.healthInfo ⇒ Array.<DependencyHealth>

Kind: instance property of Copacetic
Returns: Array.<DependencyHealth> - Health information on all dependencies

copacetic.healthReport ⇒ HealthReport

Kind: instance property of Copacetic
Returns: HealthReport - A full report of health information and dependencies

copacetic.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 instance
Kind: instance method of Copacetic
| Param | Type | Description | | --- | --- | --- | | opts | Object | The configuration for a dependency |

copacetic.deregisterDependency(name) ⇒ Copacetic

Removes a dependency from a Copacetic instance
Kind: 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 dependencies
Kind: 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 dependencies
Kind: 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()
})
Example
copacetic.poll({ name: 'my-dependency' })
.on('health', () => { ... Do something })

copacetic.stop()

stops polling registered dependencies
Kind: instance method of Copacetic

copacetic.checkAll(parallel) ⇒ Copacetic

Checks the health of all registered dependencies
Kind: 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 dependency
Kind: 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' })
Example
copacetic.check({ name: 'my-dependency', retries: 5 })
.on('healthy', serviceHealth => { ... Do stuff })
.on('unhealthy', serviceHealth => { ... Handle degraded state })
Example
copacetic.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 }]
})
Example
copacetic.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 sequantially
Kind: instance method of Copacetic
| Param | Type | | --- | --- | | dependencies | Array.<Dependency> | | parallel | Boolean |

HealthReport : Object

The full health report including isHealthy and dependencies
Kind: global typedef
Properties
| Name | Type | Description | | --- | --- | --- | | isHealthy | Boolean | The result of isHealthy | | Name | String | | | dependencies | Array.<DependencyHealth> | The result of healthInfo |