README
Requeirements
- NodeJS >= 12
Description
PingCheck is basic HTTP(s) JSON API that provides easy way to set service health status. It is configurable and it support's both HTTP and HTTPS protocols. Binding to custom address is supported, as well as port on which server should listen. Also- custom path on which health check endpoint should listen is supported.
This library relies on singletop pattern, therefor everyting that is done is related to same class, and is accessed via static methods/properties.
NOTE: This only provides current data, historical values are not yet implemented.
Usage
Using HTTP
const PingCheck = require('pingcheck');
PingCheck.initialize()
.then(() => { console.log('Server listening') })
.catch(console.error);
This example will start server with default configurations. Default address: http://localhost:8080/health
Using HTTPS
const PingCheck = require('pingcheck');
const options = {
keyPath: '/path/to/ssl/key.key',
certificatePath: '/path/to/ssl/certificate.pem',
passphrase: 'custom key passphrase',
};
PingCheck.initialize(options)
.then(() => { console.log('Server listening') })
.catch(console.error);
In example aboce, we provide only SSL certificate, therefor default address will be used. Default address: https://localhost:8080/health
Protected Endpoint
const PingCheck = require('pingcheck');
const options = {
secret: 'MY_SECRET',
};
PingCheck.initialize(options)
.then(() => { console.log('Server listening') })
.catch(console.error);
To protect endpoint You can provide secret
property to PingCheck.initialize
options.
Providing secret
makes endpoint locked behind that secret, which will require client to send either header x-check-secret
that matches provided secret
, or query parameter checkSecret
also matching secret
parameter.
NOTE: This is most basic protection
One of possible way to access following example is by using query paraeter checkSecret
Address: http://localhost:8080/health?checkSecret=MY_SECRET
Initialize options
options.host
(default='localhost')- Address on which server is listening
options.port
(default=8080)- Port on which server is listening
options.path
(default='/health')- Path on which health status is served.
options.secret
(default=null)- API Secret used to prevent access to unknowns.
options.key
(default=null)- SSL Key (required for HTTPS)
options.certificate
(default=null)- SSL Certificate
options.keyPath
(default=null, ignored if options.key is set)- Path to SSL key file
options.certificatePath
(default=null, ignored if options.certificate is set)- Path to SSL certificate file.
options.passphrase
(default=null)- Custom passphrase for SSL certificate
Health Notifier
In order for API to provide proper or any data, some parts of Your application/service/script MUST trigger PingCheck.notify
method.
PingCheck.notify
can be used to notify rest server about state of specific service.
There is always service called default
and its used when we want to notify on "global" level. For sub-grouping we can provide custom service identifier when notifying.
Notify Global
const PingCheck = require('pingcheck');
// This will set global (default) Ok status, without message.
PingCheck.notify();
// This will set global (default) health status to "warning" with provided message.
PingCheck.notify({
status: PingCheck.Status.Warning,
message: 'High load',
});
Notify as specific service
const PingCheck = require('pingcheck');
// This will set service "users" health status to "warning" with provided message.
PingCheck.notify('users', {
status: PingCheck.Status.Warning,
message: 'High load',
});
Notify health status with expiration time
const PingCheck = require('pingcheck');
// This will set service "users" health status to "warning" with provided message and expiration time.
PingCheck.notify('users', {
status: PingCheck.Status.Warning,
message: 'High load',
expiration: '2020-03-24 23:59:59',
});
NOTE: This status will be valid as long as check time is less than expiration. In case that state has expired last "non-expiring" state is used. In case that there is no previous "non-expiring" state, status "error" without message is used.