fastify-http-errors-enhanced

A error handling plugin for Fastify that uses enhanced HTTP errors.

View on GitHub

Introduction

%s %s %s %s

A error handling plugin for Fastify that uses enhanced HTTP errors.

http://sw.cowtech.it/fastify-http-errors-enhanced

Installation

Just run:

npm install fastify-http-errors-enhanced --save

Usage

Register as a plugin, optional providing any of the following options:

Once registered, the server will use the plugin handlers for all errors (basically, both setErrorHandler and setNotFoundHandler are called).

The handler response format will compatible with standard fastify error response, which is the following:

{ 
  statusCode: number 
  error: string 
  message: string 
}

If the original error's code properties does not start with HTTP_ERROR_ (http-errors-enhanced standard error prefix), then the code is also included in output object. In addition, the response headers will contain all headers defined in error.headers and the response body will contain all additional enumerable properties of the error.

To clarify, take this server as a example:

import fastify from 'fastify' 
import fastifyHttpErrorsEnhanced from 'fastify-http-errors-enhanced' 
import { NotFoundError } from 'http-errors-enhanced' 
 
const server = fastify() 
 
/* 
Since fastify-http-errors-enhanced uses an onRoute hook, you have to either: 
 
* use `await register...` 
* wrap you routes definitions in a plugin 
 
See: https://www.fastify.io/docs/latest/Guides/Migration-Guide-V4/#synchronous-route-definitions 
*/ 
await server.register(fastifyHttpErrorsEnhanced) 
 
server.get('/invalid', { 
  handler: async function (request, reply) { 
    throw new NotFoundError('You are not supposed to reach this.', { 
      header: { 'X-Req-Id': request.id, id: 123 }, 
      code: 'UNREACHABLE' 
    }) 
  } 
}) 
 
server.listen({ port: 3000 }, err => { 
  if (err) { 
    throw err 
  } 
})

When hitting /invalid it will return the following:

{ 
  "error": "Not Found", 
  "code": "UNREACHABLE", 
  "message": "You are not supposed to reach this.", 
  "statusCode": 404, 
  "id": 123 
}

and the X-Req-Id will be set accordingly.

Unhandled error handling

Once installed the plugin will also manage unhandled server errors.

In particular, if error hiding is enabled, all unhandled errors will return the following response:

{ 
  "error": "Internal Server Error", 
  "message": "An error occurred trying to process your request.", 
  "statusCode": 500 
}

and the error will be logged using error severity.

If not hidden, instead, the error will be returned in a standard response that also add the stack property (as a array of strings) and any additional error enumerable property.

To clarify, take this server as a example:

import fastify from 'fastify' 
import fastifyHttpErrorsEnhanced from 'fastify-http-errors-enhanced' 
import { NotFoundError } from 'http-errors-enhanced' 
import createError from 'http-errors' 
 
await server.register(fastifyHttpErrorsEnhanced, { hideUnhandledErrors: false }) 
 
server.get('/invalid', { 
  handler(request, reply) { 
    const error = new Error('This was not supposed to happen.') 
    error.id = 123 
    throw error 
  } 
}) 
 
server.listen({ port: 3000 }, err => { 
  if (err) { 
    throw err 
  } 
})

When hitting /invalid it will return the following:

{ 
  "error": "Internal Server Error", 
  "message": "[Error] This was not supposed to happen.", 
  "statusCode": 500, 
  "id": 123, 
  "stack": ["..."] 
}

Validation and response validation errors

If enabled, response will have status of 400 or 500 (depending on whether the request or response validation failed) and the the body will have the failedValidations property.

Example of a client validation error:

{ 
  "statusCode": 400, 
  "error": "Bad Request", 
  "message": "One or more validations failed trying to process your request.", 
  "failedValidations": { "query": { "val": "must match pattern \"ab{2}c\"", "val2": "is not a valid property" } } 
}

Example of a response validation error:

{ 
  "error": "Internal Server Error", 
  "message": "The response returned from the endpoint violates its specification for the HTTP status 200.", 
  "statusCode": 500, 
  "failedValidations": { 
    "response": { 
      "a": "must be a string", 
      "b": "must be present", 
      "c": "is not a valid property" 
    } 
  } 
}

ESM Only

This package only supports to be directly imported in a ESM context.

For informations on how to use it in a CommonJS context, please check this page.

Contributing to fastify-http-errors-enhanced

Copyright

Copyright (C) 2019 and above Shogun (shogun@cowtech.it).

Licensed under the ISC license, which can be found at https://choosealicense.com/licenses/isc.