Documentation
¶
Overview ¶
Package errors contains helpful types and structures simplifying error handling.
Handler Errors ¶
Handler errors consist of a status code a log message and a body. The status code and body can be send to the client and the log message can obviously be logged.
Errors for handlers can easily be constructed using chaining. You can start the construction of an error with the:
Construct(status int)
or
ConstructWithContext(status int, logMsg string)
method. The latter is just a shortcut for:
Construct(status).WithLog(logMsg).WithStackTrace(0)
This constructs an error with given status code and a log message that contains the logMsg and a little stack trace showing where the error was constructed which allows to find the root of an error more easily.
The parameter for the WithStackTrace method determines how far up the stack the trace should be taken from. A 0 means the trace should be taken from the caller of the WithStackTrace method. If you create your own construction function for commonly constructed errors you can set this to 1 to take the trace of the code calling your construction function instead of taking the trace from your construction function itself.
Similarly to the WithStackTrace(skip int) there is the WithCause(cause error) method which appends the message of given cause to the log of the error.
Both of these method require that the WithLog(logMsg string) has been called before them or else they will panic.
To determine the content of the errors body the following methods can be used:
WithBody(body string) WithBodyModal(title, msg string) WriteToBody(write func(io.Writer))
The first one simply writes the given string to the body. The second parses given title and msg into a html-template containing an error modal. The third allows to directly write to the body without interrupting the chaining of calls. It accepts a function taking a writer to which in can write the content of the body.
To finish the construction and retrieve the created error simply use the Finish() method which will return the constructed error.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BadRequest ¶
func BadRequest(w http.ResponseWriter)
BadRequest shows an error displaying, that a request has been made that shouldn't have happen or was caused by an client error (Status Code 400)
func Log ¶
func Log(error HandlerError)
Log logs the given error.
If the log message contained in the error isn't empty the following message will be written to the log:
Handler error. Status: <Text representation of status code> <error.Error()>
func Respond ¶
func Respond(error HandlerError, w http.ResponseWriter)
Respond writes the given error to the given response writer and logs the incidence.
The errors body will be written to the response writer. The errors status code will be written to the response writer.
If the log message contained in the error isn't empty the following message will be written to the log:
Handler error. Status: <Text representation of status code> <error.Error()>
Example ¶
recorder := httptest.NewRecorder()
err := Construct(http.StatusInternalServerError).
WithLog("This is the log message.").
WithCause(errors.New("this is the causing error")).
WithBody("This will be the body.").
Finish()
// Remove time stamp form log in order to
// allow the output to be reliable.
log.SetFlags(0)
// Let log write to Stdout to show logged
// data as output.
log.SetOutput(os.Stdout)
Respond(err, recorder)
fmt.Println("-Status-")
fmt.Println(recorder.Result().StatusCode)
fmt.Println("-Body-")
fmt.Println(recorder.Body.String())
Output: Handler error. Status: Internal Server Error This is the log message. Caused by: this is the causing error -Status- 500 -Body- This will be the body.
func WrongPath ¶
func WrongPath(w http.ResponseWriter, r *http.Request)
WrongPath shows that a path does not exist (Status Code 404)
func WrongRequestMethod ¶
func WrongRequestMethod(w http.ResponseWriter, r *http.Request)
WrongRequestMethod shows an error displaying, that a request has been made using an unsupported method (Status Code 405)
Types ¶
type HandlerError ¶
type HandlerError interface {
// Error returns the error message that
// should be logged once the error occurs.
Error() string
// StatusCode returns the http status code that should
// be sent to the client.
StatusCode() int
// Body returns the body this error contains and
// should be written to the client response.
Body() string
}
HandlerError is an error that occurs in handlers the defined function will be used to write the error to a ResponseWriter and to the log.
type HandlerErrorConstructor ¶
type HandlerErrorConstructor interface {
// WithBodyModal adds a compiled error modal template
// to the errors body using given title and message.
WithBodyModal(title, msg string) HandlerErrorConstructor
// WithBody adds the given string to the body of
// the error.
WithBody(body string) HandlerErrorConstructor
// WriteToBody allows to directly writing to the body of the error without
// interrupting chaining.
WriteToBody(write func(io.Writer)) HandlerErrorConstructor
// WithLog adds the given message to the log entry
// of the error.
WithLog(logMsg string) HandlerErrorConstructor
// WithStackTrace adds the line and file from the call stack
// to the errors log message.
//
// The argument skip is the number of stack frames
// to ascend, with 0 identifying the caller of this method.
//
// Please call WithLog before calling this method or else it
// will panic.
//
// The new message looks like this:
//
// <current message>
// Created at: line <caller line> in file '<caller file>'
WithStackTrace(skip int) HandlerErrorConstructor
// WithCause adds the error message of given cause
// to this errors log.
//
// Please call WithLog before calling this method or else it
// will panic.
//
// The new message looks like this:
//
// <current message>
// Caused by: <cause.Error()>
WithCause(cause error) HandlerErrorConstructor
// Copy copies this constructor. Calls to the copy have no influence
// on the constructor it was copied from. This can be used to create
// template for error which can be copied an further modified without changing
// the original.
Copy() HandlerErrorConstructor
// Finish finishes the construction and returns the constructed error.
Finish() HandlerError
}
HandlerErrorConstructor is used to construct a HandlerError. It allows chaining methods that consequently define the errors attributes.
func Construct ¶
func Construct(status int) HandlerErrorConstructor
Construct lets you construct a new handler error using the constructor.
Example ¶
err := Construct(http.StatusInternalServerError).
WithLog("This is the log message.").
WithCause(errors.New("this is the causing error")).
WithBody("This will be the body.").
Finish()
fmt.Println(err.StatusCode())
fmt.Println(err.Body())
fmt.Println(err.Error())
Output: 500 This will be the body. This is the log message. Caused by: this is the causing error
func ConstructWithStackTrace ¶
func ConstructWithStackTrace(status int, logMsg string) HandlerErrorConstructor
ConstructWithStackTrace this method is a convenient shortcut for: Construct(status).WithLog(logMsg).WithStackTrace(0)
Source Files