boom

README

Boom

boom provides a set of functions for returning HTTP errors. Each function responds with a JSON object which includes the following properties:

• statusCode - the HTTP status code.
• error- the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived from statusCode.
• message - the error message which can be optionally set by the developer.

All boom functions take a http.ResponseWriter as an argument which means boom should be compatible with any Golang http frameworks that also use http.ResponseWriter.

To see the full list of boom functions, check out the documentation on godoc.org

This library is inspired by the wonderful JavaScript library https://www.npmjs.com/package/boom.

Install

go get github.com/darahayes/go-boom

Import

import (
	"github.com/darahayes/go-boom"
)

Example Usage

package main

import (
	"fmt"
	"net/http"
	"github.com/darahayes/go-boom"
)

func myHandler(w http.ResponseWriter, r *http.Request) {
	boom.NotFound(w, "Sorry, there's nothing here.")
}

func main() {
	http.HandleFunc("/", myHandler)
	http.ListenAndServe(":8080", nil)
}

With this example, the response from the / endpoint would be:

{
  "error": "Not Found",
  "message": "Sorry, there's nothing here.",
  "statusCode": 404
}

boom also accepts arguments of type error, or any struct that implements the built in error interface. (i.e. has an Error() function which returns a string)

func myHandler(w http.ResponseWriter, r *http.Request) {
	err := errors.New("You shall not pass!")
	boom.Unathorized(w, err)
}

and the response:

{
  "error": "Unathorized",
  "message": "You shall not pass!",
  "statusCode": 401
}

It's also possible to provide no error message at all:

func myHandler(w http.ResponseWriter, r *http.Request) {
	boom.BadRequest(w)
}

and the response:

{
  "error": "Bad Request",
  "message": "Bad Request",
  "statusCode": 400
}

boom.RecoverHandler

boom also comes with a RecoverHandler middleware function that can be used to recover from unexpected panics. It can be used directly or with any router library that deals with the http.Handler type. (most of them do!)

boom.RecoverHandler does three things:

1. Recovers from unexpected panics.
2. Logs a stack trace in the server logs.
3. Uses boom.Internal() to return a generic 500 Internal Server Error. This prevents accidental leakage of sensitive info in the response.

Example usage with plain http library

func myHandler(w http.ResponseWriter, r *http.Request) {
	panic("Uh oh, something happened")
}

func main() {
	http.Handle("/", boom.RecoverHandler(http.HandlerFunc(myHandler)))
	http.ListenAndServe(":8080", nil)
}

Example usage with the mux router

func myHandler(w http.ResponseWriter, r *http.Request) {
	panic("Uh oh, something happened")
}

func main() {
	router := mux.NewRouter().StrictSlash(true)
	router.HandleFunc("/", myHandler)
	
	router.Use(boom.RecoverHandler)
	
	http.ListenAndServe(":8080", router)
}

In both examples above, a stack trace is printed in the server logs and the response is the following:

{
  "error": "Internal Server Error",
  "message": "Internal Server Error",
  "statusCode": 500
}

API Methods

To see the full list of API methods check out the documentation on godoc.org

Documentation

Index

• func BadData(w http.ResponseWriter, message ...interface{})
• func BadGateway(w http.ResponseWriter, message ...interface{})
• func BadImplementation(w http.ResponseWriter, message ...interface{})
• func BadRequest(w http.ResponseWriter, message ...interface{})
• func ClientTimeout(w http.ResponseWriter, message ...interface{})
• func Conflict(w http.ResponseWriter, message ...interface{})
• func EntityTooLarge(w http.ResponseWriter, message ...interface{})
• func ExpectationFailed(w http.ResponseWriter, message ...interface{})
• func Forbidden(w http.ResponseWriter, message ...interface{})
• func GatewayTimeout(w http.ResponseWriter, message ...interface{})
• func Illegal(w http.ResponseWriter, message ...interface{})
• func Internal(w http.ResponseWriter, message ...interface{})
• func LengthRequired(w http.ResponseWriter, message ...interface{})
• func Locked(w http.ResponseWriter, message ...interface{})
• func MethodNotAllowed(w http.ResponseWriter, message ...interface{})
• func NotAcceptable(w http.ResponseWriter, message ...interface{})
• func NotFound(w http.ResponseWriter, message ...interface{})
• func NotFoundHandler(w http.ResponseWriter, r *http.Request)
• func NotImplemented(w http.ResponseWriter, message ...interface{})
• func PaymentRequired(w http.ResponseWriter, message ...interface{})
• func PreconditionFailed(w http.ResponseWriter, message ...interface{})
• func PreconditionRequired(w http.ResponseWriter, message ...interface{})
• func ProxyAuthRequired(w http.ResponseWriter, message ...interface{})
• func RangeNotSatisfiable(w http.ResponseWriter, message ...interface{})
• func RecoverHandler(next http.Handler) http.Handler
• func ResourceGone(w http.ResponseWriter, message ...interface{})
• func ServerUnavailable(w http.ResponseWriter, message ...interface{})
• func Success(w http.ResponseWriter, message ...interface{})
• func Teapot(w http.ResponseWriter, message ...interface{})
• func TooManyRequests(w http.ResponseWriter, message ...interface{})
• func URITooLong(w http.ResponseWriter, message ...interface{})
• func Unathorized(w http.ResponseWriter, message ...interface{})
• func UnsupportedMediaType(w http.ResponseWriter, message ...interface{})

Functions

func BadData

func BadData(w http.ResponseWriter, message ...interface{})

BadData responds with a 422 Unprocessable Entity error. Takes an optional message of either type string or type error, which will be returned in the response body.

func BadGateway

func BadGateway(w http.ResponseWriter, message ...interface{})

BadGateway responds with a 502 Bad Gateway error. Takes an optional message of either type string or type error, which will be returned in the response body.

func BadImplementation

func BadImplementation(w http.ResponseWriter, message ...interface{})

BadImplementation responds with a 500 Internal Server Error error. Alias for boom.Internal. Takes an optional message of either type string or type error but, will always return a generic message in the response body. This behaviour protects the developer from accidentally returning sensitive data in the response during a panic.

func BadRequest

func BadRequest(w http.ResponseWriter, message ...interface{})

BadRequest responds with a 400 Bad Request error. Takes an optional message of either type string or type error, which will be returned in the response body.

func ClientTimeout

func ClientTimeout(w http.ResponseWriter, message ...interface{})

ClientTimeout responds with a 408 Request Time-out error. Takes an optional message of either type string or type error, which will be returned in the response body.

func Conflict

func Conflict(w http.ResponseWriter, message ...interface{})

Conflict responds with a 409 Conflict error. Takes an optional message of either type string or type error, which will be returned in the response body.

func EntityTooLarge

func EntityTooLarge(w http.ResponseWriter, message ...interface{})

EntityTooLarge responds with a 413 Request Entity Too Large error. Takes an optional message of either type string or type error, which will be returned in the response body.

func ExpectationFailed

func ExpectationFailed(w http.ResponseWriter, message ...interface{})

ExpectationFailed responds with a 417 Expectation Failed error. Takes an optional message of either type string or type error, which will be returned in the response body.

func Forbidden

func Forbidden(w http.ResponseWriter, message ...interface{})

Forbidden responds with a 403 Forbidden error. Takes an optional message of either type string or type error, which will be returned in the response body.

func GatewayTimeout

func GatewayTimeout(w http.ResponseWriter, message ...interface{})

GatewayTimeout responds with a 504 Gateway Time-out error. Takes an optional message of either type string or type error, which will be returned in the response body.

func Illegal

func Illegal(w http.ResponseWriter, message ...interface{})

Illegal responds with a 451 Unavailable For Legal Reasons error. Takes an optional message of either type string or type error, which will be returned in the response body.

func Internal

func Internal(w http.ResponseWriter, message ...interface{})

Internal responds with a 500 Internal Server Error error. Takes an optional message of either type string or type error but, will always return a generic message in the response body. This behaviour protects the developer from accidentally returning sensitive data in the response during a panic.

func LengthRequired

func LengthRequired(w http.ResponseWriter, message ...interface{})

LengthRequired responds with a 411 Length Required error. Takes an optional message of either type string or type error, which will be returned in the response body.

func Locked

func Locked(w http.ResponseWriter, message ...interface{})

Locked responds with a 423 Locked error. Takes an optional message of either type string or type error, which will be returned in the response body.

func MethodNotAllowed

func MethodNotAllowed(w http.ResponseWriter, message ...interface{})

MethodNotAllowed responds with a 405 Method Not Allowed error. Takes an optional message of either type string or type error, which will be returned in the response body.

func NotAcceptable

func NotAcceptable(w http.ResponseWriter, message ...interface{})

NotAcceptable responds with a 406 Not Acceptable error. Takes an optional message of either type string or type error, which will be returned in the response body.

func NotFound

func NotFound(w http.ResponseWriter, message ...interface{})

NotFound responds with a 404 Not Found error. Takes an optional message of either type string or type error, which will be returned in the response body.

func NotFoundHandler

func NotFoundHandler(w http.ResponseWriter, r *http.Request)

NotFoundHandler handler function that uses boom.NotFound() to create a structured 404 response. Can be used to configure routers that accept a handler for 404 cases

func NotImplemented

func NotImplemented(w http.ResponseWriter, message ...interface{})

NotImplemented responds with a 501 Not Implemented error. Takes an optional message of either type string or type error, which will be returned in the response body.

func PaymentRequired

func PaymentRequired(w http.ResponseWriter, message ...interface{})

PaymentRequired responds with a 402 Payment Required error. Takes an optional message of either type string or type error, which will be returned in the response body.

func PreconditionFailed

func PreconditionFailed(w http.ResponseWriter, message ...interface{})

PreconditionFailed responds with a 412 Precondition Failed error. Takes an optional message of either type string or type error, which will be returned in the response body.

func PreconditionRequired

func PreconditionRequired(w http.ResponseWriter, message ...interface{})

PreconditionRequired responds with a 428 Precondition Required error. Takes an optional message of either type string or type error, which will be returned in the response body.

func ProxyAuthRequired

func ProxyAuthRequired(w http.ResponseWriter, message ...interface{})

ProxyAuthRequired responds with a 407 Proxy Authentication Required error. Takes an optional message of either type string or type error, which will be returned in the response body.

func RangeNotSatisfiable

func RangeNotSatisfiable(w http.ResponseWriter, message ...interface{})

RangeNotSatisfiable responds with a 416 Requested Range Not Satisfiable error. Takes an optional message of either type string or type error, which will be returned in the response body.

func RecoverHandler

func RecoverHandler(next http.Handler) http.Handler

RecoverHandler is a middleware handler function that can be used to recover from unexpected panics, log a stack trace and respond with a generic 500 Internal Server Error. Ensures no sensitive data is leaked during panics.

func ResourceGone

func ResourceGone(w http.ResponseWriter, message ...interface{})

ResourceGone responds with a 410 Gone error. Takes an optional message of either type string or type error, which will be returned in the response body.

func ServerUnavailable

func ServerUnavailable(w http.ResponseWriter, message ...interface{})

ServerUnavailable .eturns a 503 Service Unavailable error. Takes an optional message of either type string or type error, which will be returned in the response body.

func Success

func Success(w http.ResponseWriter, message ...interface{})

func Teapot

func Teapot(w http.ResponseWriter, message ...interface{})

Teapot responds with a 418 I'm a Teapot error. Takes an optional message of either type string or type error, which will be returned in the response body.

func TooManyRequests

func TooManyRequests(w http.ResponseWriter, message ...interface{})

TooManyRequests responds with a 429 Too Many Requests error. Takes an optional message of either type string or type error, which will be returned in the response body.

func URITooLong

func URITooLong(w http.ResponseWriter, message ...interface{})

URITooLong responds with a 414 Request-URI Too Large error Takes an optional message of either type string or type error, which will be returned in the response body.

func Unathorized

func Unathorized(w http.ResponseWriter, message ...interface{})

Unathorized responds with a 401 Unauthorized error. Takes an optional message of either type string or type error, which will be returned in the response body.

func UnsupportedMediaType

func UnsupportedMediaType(w http.ResponseWriter, message ...interface{})

UnsupportedMediaType responds with a 415 Unsupported Media Type error. Takes an optional message of either type string or type error, which will be returned in the response body.