probejs

Probe endpoints for expected responses and take action if needed

Introduction

It's often necessary to probe HTTP endpoints to ensure services are available or to build health or dependency checking frameworks.

In these types of checks the following scenarios are common:

• pass - the request returns a valid response
• fail - the request returns an invalid response
• error - something else went wrong

A probe is a simple, configurable, event-emitting object designed with this in mind. It handles building and sending requests to endpoints at specified intervals, expects given responses and emits events which can be listened to in order to take action based on the scenarios above.

Installation

npm install --save probejs

Usage

const Probe = require('probe');

// create a new probe providing any required config
const probe = new Probe({
  endpoint: 'http://mydomain:1234/path/to/probe', // the endpoint to probe
  interval: 30,                                   // how often to send a request (in seconds)
  validResponses: [200]                           // array of responses that we'll consider a 'pass'
});

// create any required event listeners
probe.on('fail', (response) => {
  // take some action e.g. send an alert
});

// start the probe
probe.start();

Config

When creating a new Probe() the constructor expects a config object which supports the following keys:

• method
• endpoint
• auth
• headers
• body
• validResponses
• interval
• timeout

method

type:        string
required:    false
default:     'GET'

the HTTP request method to use

endpoint

type:        string
required:    true
default:     none

the endpoint to probe

supports HTTP/HTTPS, custom ports, paths and query parameters

auth

type:        object
required:    false
default:     none

support for basic auth & bearer tokens

Object expects the following keys:

• username string (required with password, not valid with bearer)
• password string (required with username, not valid with bearer)
• bearer string (not valid with username or password)

headers

type:        object
required:    false
default:     none

custom headers to add to the requests

body

type:        any
required:    false
default:     none

a request body to send e.g. in POST requests

validResponses

type:        array
required:    false
default:     [200]

an array of responses that will be considered a pass

any response not in this array will be considered a fail

interval

type:        int
required:    false
default:     30

the interval in seconds between sending requests

requests continue to be sent until probe.stop() is called

setting this to 0 is equivalent to sending a single request followed by probe.stop()

timeout

type:        int
required:    false
default:     10

the timeout in seconds to wait for a request to complete

note that if the underlying TCP connection cannot be established, the OS-wide TCP connection timeout will overrule the timeout option

Events

The following events can be listened to:

• start - emitted when probe.start() is called
• stop - emitted when probe.stop() is called
• error - emitted when an error occurred trying to send the request
• complete - emitted at the end of every request, regardless of 'error', 'pass' or 'fail'
• pass - emitted when the status code of the response was in the validResponses array of the probe config
• fail - emitted when the status code of the response was NOT in the validResponses array in the probe config