A package to help your service check the health of its dependencies
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

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])

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: 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)

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: health, healthy, 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

"healthy"

Health information on a single dependency

Kind: event emitted by Copacetic

"unhealthy"

Health information on a single dependency

Kind: event emitted by Copacetic

"health"

Health information on a set of dependencies

Kind: event emitted by Copacetic

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