mu-error
The official error handling library for mu
- Sponsor: nearForm
- Status: Experimental
Part of the Official [mu][Mu Suite].
mu-error
provides distributed error handling functionality to [mu][mu
]. Of note, it ensures stack serialization, preserves remote stack traces and prevents exposing internal errors to production users.
Overview
mu-error
is exported on the mu
object as mu.error
. There is usually no need to install.
mu.error
creates decorated boom
objects, which allows
for compatibility with the Hapi reply
function, without losing any value when
integrating with other frameworks such as Express or Koa.
While boom
allows HTTP status codes of 400+, mu-error
reserves the range
of 1..99 for mu specific errors, creating an error with this a code this range
will generate an HTTP status code of 500 by default and inject the mu error context into the boom
error output
object.
Quick Start
Example
If used in a service context, simply call mu.error
with a string.
const mu = dev: processNODE_ENV !== 'production' mu
This will create an object like the following:
Error: <Error Object> data: null isBoom: true isServer: true output: statusCode: 500 payload: statusCode: 500 error: 'Internal Server Error' message: 'An internal server error occurred' mu: code: 1 error: 'general service error' message: 'no user found!' headers: {} mu: code: 1 error: 'general service error' message: 'no user found!' reformat: Function isMu: true }
This output assumes NODE_ENV
is not 'production', when not in dev mode the output.payload.mu
is not added, which means error specifics are hidden from production users.
API
require('mu')({errors: MU_ERROR_OPTIONS})
mu-error
is created automatically by mu
, the errors
property of the options object passed to mu
is passed on to mu-error
which has the following options:
dev
(false
) if set on theerrors
object it can override the top leveldev
option for mu - see Dev ModehttpCode
(500
) - see Custom mu error HTTP status codeserializeErrorProps
(true
) - see Serialize Error PropsmaxRemoteStacks
(dev ? Infinity : 20
) see Remote Errors
mu.error(code|message, message|data, data)
The main function for creating mu error objects.
The first arguments may be a number between 1 and 99, or 400+, or a string (or undefined).
As with boom, a data
parameter can be passed to attach any useful state to the
error context.
Alias: mu.error.create
mu.error.wrap(error, muCode, statusCode, message)
Same concept as boom.wrap
.
Wraps an Error
(or boom
) object (included deserialized boom
objects) with a mu error object,
or adds mu context to a pre-existing boom
object.
mu.error.wrapRemote(error, muCode, statusCode, message)
Intended to wraps a (usually deserialized boom
schema) object (i.e. an error propagating across a transport), and keeps a live list of remote stacks as an array on err.remoteStacks
. See Remote Errors.
Alias: mu.error.remote
mu.error.makeMuError(muCode, httpStatusCode, message, data)
Directly create a mu error object, this method can be used to create a single mu error object with a custom http status code.
mu.error.extract(err)
Inverts the shape of the boom
object so that the mu error context is at the top level, along with payload and data objects.
For example:
console
Would give
code: 1 error: 'service error' message: 'no user found!' data: null payload: statusCode: 500 error: 'Internal Server Error' message: 'An internal server error occurred'
Mu Constants
The mu.error.ERRORS
object has the following constants
SERVICE: 1 FRAMEWORK: 2 TRANSPORT: 3 UNKNOWN: 99
Mu Codes
The following codes (mu.error.MU_CODES
) represent internal mu errors
1: 'service error' 2: 'framework error' 3: 'transport error' 99: 'unknown'
In userland the only code currently of interest is the service error
, the other codes are used in mu internally.
mu.error.service(message|Error, data)
Generate a service error.
When passed a message, this is functionally equivalent to calling mu.error
directly without a code. (mu.error('message') === mu.error.service('message')
).
When passed an Error
(or boom
) object it wraps the object with the correct mu context
When passed an Error
this is the equivalent of calling mu.error.wrap
(mu.error.wrap(Error('foo') === mu.error.service(Error('foo'))
)
mu.error.framework(message|Error, data)
Generate a framework error, used internally by mu
When passed an Error
(or boom
) object it wraps the object with the correct mu context
mu.error.transport(message|Error, data)
Generate a transport error, used internally by mu
When passed an Error
(or boom
) object it wraps the object with the correct mu context
Features
Remote Errors
Errors that have been propagated from another service can be passed to mu.error.wrapRemote
. This is for cases where the deserialized stack
property relates to a stack in another process. Passing the error to mu.error.wrapRemote
will place a new local stack on the err.stack
property, and append the remote stack to a err.remoteStacks
array, which contains the object of the form {timestamp, stack}
.
The maxRemoteStacks
option can be used to set the maximum allowed stacks to retain in err.remoteStacks
. This defaults to 30 when the dev
option is false, or Infinity
in dev
mode.
Generate Specific HTTP errors
mu.error
can be used in the same way as boom
to create http errors
mu
The boom
methods are also supported
mu
See the boom docs for more.
Error Serialization
mu.error
uses boom
and boom
objects are Error
objects.
The native Error
object has message
and stack
properties but they are non-enumerable, which means they don't get serialized (via JSON.stringify
). This is somewhat awkward in a service-based system.
By default mu.error
will make sure these values end up in the stringify output. To turn this off (e.g. perhaps in production) use serializeErrorProps
:
errors: serializeErrorProps: false
Custom mu error HTTP status code
In the event of a mu error, the status code is 500 (internal server error).
We can set this to default to another code:
errors: httpCode: 509
If we want to specify an error code on an individual basis we can use the mu.error.makeMuError
method directly (see #api).
Install
mu-error
is exported on the mu
object, so for general usage we install mu
:
$ npm install mu
Then access
const mu = console
For internal usage, or testing purposes mu-error
can also be installed directly:
$ npm install mu-error
License
Copyright David Mark Clements & Contributors, Licensed under MIT.