qerror

qerror
================

error handler hook for fatal signals

qerror provides an easy to use hook to install a shutdown handler on receipt of
fatal signals. Runs the qerror.handler function before exiting, letting the app
flush logs and clean up. Catches SIGINT, SIGTERM, SIGHUP and uncaught
exceptions, invokes the handler, and rethrows them as errors.

var qerror = require('qerror');
qerror.timeout = 30000;
qerror.handler = function(err, callback) {
console.log("fatal error, shutting down app:", err.message);
callback();
}

process.kill(process.pid, 'SIGTERM');

outputs

2017-07-10T02:47:25.545Z -- fatal error: SIGTERM
fatal error, shutting down app: SIGTERM

/hd1/home/andras/node/git/qerror/qerror.js:55
if (err instanceof SignalError) throw err;
^
Error: SIGTERM
at process.catchSigterm (/hd1/home/andras/node/git/qerror/qerror.js:102:30)
at emitNone (events.js:86:13)
at process.emit (events.js:185:7)
at Signal.wrap.onsignal (internal/process.js:199:44)

Signals
----------------

- SIGINT - fatal, command line kill with ^C
- SIGTERM - fatal, the standard way to kill a process
- SIGHUP - fatal unless handled. If this signal is listened for, qerror ignores it,
otherwise it is treated as a fatal error.
- uncaughtException - errors not caught by the program are fatal, and terminate
execution. qerror invokes the shutdown handler on otherwise uncaught errors.

API
----------------

$3

A user-provided handler to invoke on fatal error to shut down the running app.
If falsy, the fatal error is rethrown immediately, killing the app. Default is falsy.

$3

If set, the function to use to output a notice that a fatal error has occurred.
If falsy, no notice will be output. The default is a line composed of a timestamp,
"fatal error:" and the error message, eg 2017-07-08T22:18:35.784Z fatal error: SIGTERM.

To have the app handle uncaught exceptions instead of qerror, set qerror.ignoreUncaughtException.

$3

How long to allow for the shutdown function to finish before calling its callback, in
milliseconds. Default is 30000 for 30 seconds. If this limit is exceeded, an
uncaught error is thrown.

$3

If set, do not terminate the program on uncaught exceptions, instead let the
application handle them.

$3

The error that caused qerror to call the application shutdown handler, or null if none.

$3

Unhook the error handler from the signals and uncaught exceptions. qerror is by
default hooked to SIGINT, SIGTERM, SIGHUP and uncaught exceptions.

$3

Rehook the error handler to the signals and uncaught exceptions. qerror by default
is already install-ed. See uninstall.

$3

Internal flag set whenever the error handler is hooked to listen for signals.
Set by default and by install, cleared by uninstall.

$3

Internal flag set if a fatal error has been caught and the shutdown handler has
been invoked. Subsequent errors are suppressed while waiting for the shutdown handler to
finish and call its callback. To force the app to exit immediately, kill it with SIGKILL.

Change Log
----------------

- 0.2.0 - let app handle uncaught exceptions if .ignoreUncaughtException is set, only call
alert and handler if they are functions, expose the fatal .error
- 0.1.3 - do not emit a duplicate uncaught exception
- 0.1.2 - _installed flag
- 0.1.1 - remove redundant module.exports line, add is-already-installed test
- 0.1.0 - initial version

Todo
----------------

- fix: coffee-script has to explicitly qerror.install() for the handler to run