README

Boom

Documentation Coverage Status Go Report Card CircleCI

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

Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

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

                                                                  Types

                                                                  This section is empty.