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
ConstructWithStackTrace(status int, logMsg string)
method. The latter is just a shortcut for:
Construct(status).WithLog(logMsg).WithStackTrace(1)
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 1 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 2 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) WriteToBody(write func(io.Writer))
The first one simply writes the given string to the body. The second 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.
The HandlerErrorConstructor is also a io.Writer which means you can directly write to the errors body by passing it as writer.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Handle ¶ added in v0.8.0
func Handle(err error, w http.ResponseWriter, r *http.Request)
Handle checks what type of error occurred and send an appropriate response to the client.
func Log ¶
func Log(err 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.
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
// Shows the log part of this error.
fmt.Stringer
}
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 {
// 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
// WithLogf adds the given message to the log entry
// of the error. It formats given message using
// fmt.Sprintf.
WithLogf(logMsg string, values ...interface{}) HandlerErrorConstructor
// WithRequestDump adds a dump of given request to the errors log message.
WithRequestDump(r *http.Request) 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
// Respond directly finishes the construction and writes the error to given
// response writer. The log message is also triggered.
Respond(w http.ResponseWriter)
// Enables direct writes to the errors body.
io.Writer
}
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 ConstructStd ¶ added in v0.8.0
func ConstructStd(status int, title, msg string, r *http.Request) HandlerErrorConstructor
ConstructStd starts the construction of a standard error using given status code and writing the given title and message into the errors body as
a) an error modal if the request was a fragment request or nil
b) a full error page otherwise
The given msg will be interpreted as plain HTML so don't put user given input in there unless properly sanitized.
func ConstructWithStackTrace ¶
func ConstructWithStackTrace(status int, logMsg string) HandlerErrorConstructor
ConstructWithStackTrace this method is a convenient shortcut for: Construct(status).WithLog(logMsg).WithStackTrace(0)
func DefaultError ¶ added in v1.0.0
func DefaultError(status int) HandlerErrorConstructor
DefaultError returns the default error which is generated by status
Source Files