mu-error

Generic Error Maker for mu, the microservices toolkit

Usage with mu

If you are using the mu library, then there is probably no need to require this module directly, simply use the mu.error instance.

Overview

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 mue with a string.

const mu = require('mu')()
const mue = require('mu-error')()

mu.define({role: 'some': cmd: 'thing'}, function (args, cb) {
  if (!args.pattern.user) {
    return cb(mue('no user found!'))
  }
  cb(null, {some: 'data'})
})

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' },
     headers: {},
     mu:
      { code: 1,
        error: 'general service error',
        message: 'no user found!' } },
  reformat: [Function],
  isMu: true }

Dev Mode

If we want to see the mu error object returned over HTTP, we can pass a dev option, it makes sense set this based on the NODE_ENV environment variable.

const mue = require('mu-error')({dev: process.NODE_ENV !== 'production'})

This will add the output.mu object to output.payload.mu also.

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:

require('mu-error')({serializeErrorProps: false})

Remote Errors

Errors that have been propagated from another service can be passed to mue.wrapRemote. This is for cases where the deserialized stack property relates to a stack in another process. Passing the error to mue.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.define({role: 'some': cmd: 'thing'}, function (args, cb) {
  if (!args.pattern.user) {
    return cb(mue(401, 'no user found'))
  }
  cb(null, {some: 'data'})
})

The boom methods are also supported

mu.define({role: 'some': cmd: 'thing'}, function (args, cb) {
  if (!args.pattern.user) {
    return cb(mue.unauthorized('no user found'))
  }
  cb(null, {some: 'data'})
})

See the boom docs for more.

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:

require('mu-error')({httpCode: 509})

If we want to specify an error code on an individual basis we can use the mue.makeMuError method directly (see API).

API

require('mu-error')(options)

Instantiate mu-error.

Options are

• dev (false) - see Dev Mode
• httpCode (500) - see Custom mu error HTTP status code
• serializeErrorProps (true) - see Serialize Error Props
• maxRemoteStacks (dev ? Infinity : 20) see Remote Errors

mue(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: mue.create

mue.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.

mue.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: mue.remote

mue.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.

mue.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.log(mue.extract(mue('no user found!'))) 

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' } }

Alias: require('mu-error').extract

Mu Constants

The mue.ERRORS object has the following constants

  SERVICE: 1,
  FRAMEWORK: 2,
  TRANSPORT: 3,
  UNKNOWN: 99

Mu Codes

The following codes (mue.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.

mue.service(message|Error, data)

Generate a service error.

When passed a message, this is functionally equivalent to calling mue directly without a code. (mue('message') === mue.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 mue.wrap (mue.wrap(Error('foo') === mue.service(Error('foo')))

mue.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

mue.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

License

MIT

Acknowledgements

• Sponsored by nearForm