@goa/http-errors

@goa/http-errors is Creates HTTP Errors For Goa Apps.

yarn add @goa/http-errors

Table Of Contents

• Table Of Contents
• API
  • HttpError
• httpErrors(status: number, message: string, props: string): !Error
• new createError.ErrorType([msg]))
• Copyright & License

API

The package is available by importing its default function and named class:

import httpErrors, { HTTPError } from '@goa/http-errors'

HttpError: The error constructor that extends Error.

Name	Type	Description
status	number	The status message.
statusCode	string	The status code.
headers	*	Can be an object of header names to values to be sent to the client, defaulting to undefined. When defined, the key names should all be lower-cased.
message	string	The traditional error message, which should be kept short and all single line.
expose	boolean	Whether to expose the error to the client. For client errors the default is true, for server errors (status >= 500) is false.

httpErrors(
  status: number,
  message: string,
  props: string,
): !Error

Create a new error object with the given message msg. The error object inherits from createError.HttpError.

• status* number: The status code as number.
• message* string: The message. By default, will look up in the status code table.
• props* string: Additional custom properties to attach to object.

import { aqt } from 'rqt'
import httpErrors from '@goa/http-errors'
import Goa from '@goa/koa'

const goa = new Goa()

goa.use(() => {
  throw httpErrors(401, 'Please login to view this page.')
})
goa.listen(async function() {
  const url = `http://localhost:${this.address().port}`
  const res = await aqt(url)
  console.log(res)
  this.close()
})

{ body: 'Please login to view this page.',
  headers: 
   { 'content-type': 'text/plain; charset=utf-8',
     'content-length': '31',
     date: 'Sat, 14 Dec 2019 18:32:50 GMT',
     connection: 'close' },
  statusCode: 401,
  statusMessage: 'Unauthorized' }

Another example that extends the given error. Koa will automatically set status 404 for errors with ENOENT code.

import { aqt } from 'rqt'
import { readFile } from 'fs'
import createError from '@goa/http-errors'
import Goa from '@goa/koa'
import { join } from 'path'

const goa = new Goa()

goa.use(async (ctx) => {
  await new Promise((r, j) => {
    readFile(join('example', ctx.path), (err) => {
      let httpError
      if (err.code == 'ENOENT') {
        httpError = createError(404, err, { expose: false })
      } else {
        httpError = createError(500, err)
      }
      j(httpError)
    })
  })
})
goa.listen(async function() {
  // 404
  console.log('Request missing file')
  let url = `http://localhost:${this.address().port}/missing.txt`
  let res = await aqt(url)
  console.log(res)
  // 500
  console.log('\nRequest a dir')
  url = `http://localhost:${this.address().port}/dir`
  res = await aqt(url)
  console.log(res)
  this.close()
})

Request missing file
{ body: 'Not Found',
  headers: 
   { 'content-type': 'text/plain; charset=utf-8',
     'content-length': '9',
     date: 'Sat, 14 Dec 2019 18:32:50 GMT',
     connection: 'close' },
  statusCode: 404,
  statusMessage: 'Not Found' }

Request a dir
{ body: 'Internal Server Error',
  headers: 
   { 'content-type': 'text/plain; charset=utf-8',
     'content-length': '21',
     date: 'Sat, 14 Dec 2019 18:32:50 GMT',
     connection: 'close' },
  statusCode: 500,
  statusMessage: 'Internal Server Error' }

The app will write to stderr on internal error:

Error: EISDIR: illegal operation on a directory, read

new createError.ErrorType([msg]))

A new error could be created from a name or code, like so:

import createError from '@goa/http-errors'

const err = new createError.NotFound()
console.log(err)

{ NotFoundError: Not Found
    at Object.<anonymous> (example/constructor.js:3:13)
    at Module._compile (module.js:653:30)
    at Module.p._compile (node_modules/documentary/node_modules/alamode/compile/depack.js:49:18)
    at Module._extensions..js (module.js:664:10)
    at Object.k.(anonymous function).y._extensions.(anonymous function) [as .js] (node_modules/documentary/node_modules/alamode/compile/depack.js:51:7)
    at Module.load (module.js:566:32)
    at tryModuleLoad (module.js:506:12)
    at Function.Module._load (module.js:498:3)
    at Module.require (module.js:597:17)
    at require (internal/module.js:11:18)
  message: 'Not Found',
  status: 404,
  statusCode: 404,
  expose: true,
  headers: null,
  name: 'NotFoundError' }

It's not possible to import specific errors as they are properties on the exported function, and not exports themselves.

List of all constructors

Status Code	Constructor Name
400	BadRequest
401	Unauthorized
402	PaymentRequired
403	Forbidden
404	NotFound
405	MethodNotAllowed
406	NotAcceptable
407	ProxyAuthenticationRequired
408	RequestTimeout
409	Conflict
410	Gone
411	LengthRequired
412	PreconditionFailed
413	PayloadTooLarge
414	URITooLong
415	UnsupportedMediaType
416	RangeNotSatisfiable
417	ExpectationFailed
418	ImATeapot
421	MisdirectedRequest
422	UnprocessableEntity
423	Locked
424	FailedDependency
425	UnorderedCollection
426	UpgradeRequired
428	PreconditionRequired
429	TooManyRequests
431	RequestHeaderFieldsTooLarge
451	UnavailableForLegalReasons
500	InternalServerError
501	NotImplemented
502	BadGateway
503	ServiceUnavailable
504	GatewayTimeout
505	HTTPVersionNotSupported
506	VariantAlsoNegotiates
507	InsufficientStorage
508	LoopDetected
509	BandwidthLimitExceeded
510	NotExtended
511	NetworkAuthenticationRequired

Copyright & License

GNU Affero General Public License v3.0

Original work by Jonathan Ong and Douglas Christopher Wilson under MIT license found in COPYING.

© Idio™ 2019