Documentation
¶
Overview ¶
Package errors is a drop-in replacement for the errors package in the standard library, with extensions useful for developing web applications.
Index ¶
- Constants
- func As(err error, target interface{}) bool
- func Errorf(format string, args ...interface{}) error
- func HTTPStatusf(status int, format string, args ...interface{}) error
- func InspectFields(err error) map[string]interface{}
- func InspectHTTPStatus(err error) int
- func Is(err, target error) bool
- func New(message string) error
- func Unwrap(err error) error
- func WithField(err error, key string, value interface{}) error
- func WithFields(err error, fields Fields) error
- func WithHTTPStatus(err error, status int) error
- func WithStack(err error) error
- type Fields
- type Frame
- type Notes
- type StackTrace
- type Standard
Constants ¶
const ( StatusBadRequest = Standard(http.StatusBadRequest) StatusPaymentRequired = Standard(http.StatusPaymentRequired) StatusForbidden = Standard(http.StatusForbidden) StatusNotFound = Standard(http.StatusNotFound) StatusMethodNotAllowed = Standard(http.StatusMethodNotAllowed) StatusNotAcceptable = Standard(http.StatusNotAcceptable) StatusProxyAuthRequired = Standard(http.StatusProxyAuthRequired) StatusRequestTimeout = Standard(http.StatusRequestTimeout) StatusConflict = Standard(http.StatusConflict) StatusGone = Standard(http.StatusGone) StatusLengthRequired = Standard(http.StatusLengthRequired) StatusPreconditionFailed = Standard(http.StatusPreconditionFailed) StatusRequestEntityTooLarge = Standard(http.StatusRequestEntityTooLarge) StatusRequestURITooLong = Standard(http.StatusRequestURITooLong) StatusUnsupportedMediaType = Standard(http.StatusUnsupportedMediaType) StatusRequestedRangeNotSatisfiable = Standard(http.StatusRequestedRangeNotSatisfiable) StatusExpectationFailed = Standard(http.StatusExpectationFailed) StatusTeapot = Standard(http.StatusTeapot) StatusMisdirectedRequest = Standard(http.StatusMisdirectedRequest) StatusUnprocessableEntity = Standard(http.StatusUnprocessableEntity) StatusLocked = Standard(http.StatusLocked) StatusFailedDependency = Standard(http.StatusFailedDependency) StatusTooEarly = Standard(http.StatusTooEarly) StatusUpgradeRequired = Standard(http.StatusUpgradeRequired) StatusPreconditionRequired = Standard(http.StatusPreconditionRequired) StatusTooManyRequests = Standard(http.StatusTooManyRequests) StatusRequestHeaderFieldsTooLarge = Standard(http.StatusRequestHeaderFieldsTooLarge) StatusInternalServerError = Standard(http.StatusInternalServerError) StatusNotImplemented = Standard(http.StatusNotImplemented) StatusBadGateway = Standard(http.StatusBadGateway) StatusGatewayTimeout = Standard(http.StatusGatewayTimeout) StatusHTTPVersionNotSupported = Standard(http.StatusHTTPVersionNotSupported) StatusVariantAlsoNegotiates = Standard(http.StatusVariantAlsoNegotiates) StatusInsufficientStorage = Standard(http.StatusInsufficientStorage) StatusLoopDetected = Standard(http.StatusLoopDetected) StatusNotExtended = Standard(http.StatusNotExtended) StatusNetworkAuthenticationRequired = Standard(http.StatusNetworkAuthenticationRequired) )
Standard HTTP status codes as errors.
Variables ¶
This section is empty.
Functions ¶
func As ¶
As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true. Otherwise, it returns false.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target.
An error type might provide an As method so it can be treated as if it were a different error type.
As panics if target is not a non-nil pointer to either a type that implements error, or to any interface type.
func Errorf ¶
Errorf formats according to a format specifier and returns the string as a value that satisfies error.
If the format specifier includes a %w verb with an error operand, the returned error will implement an Unwrap method returning the operand. It is invalid to include more than one %w verb or to supply it with an operand that does not implement the error interface. The %w verb is otherwise a synonym for %v.
Errorf also records the stack trace at the point it was called.
func HTTPStatusf ¶
HTTPStatusf works like calling WithHTTPStatus(status, Errorf(format, args ...)).
func InspectFields ¶
InspectFields traverses the entire error chain, looking for embedded fields. In case of duplicate keys, the outter-most value takes precident. If no field annotations are found, nil is returned.
func InspectHTTPStatus ¶
InspectHTTPStatus returns the outter-most HTTP status in the error stack.
If err is nil, 0 is returned.
If no HTTP status is found, http.StatusInternalServerError is returned.
This function understand HTTPStatusErrors (i.e. interface { HTTPStatus() int }), as well as echo3 and echo4 HTTPError type.
TODO: Support gRPC and Twirp errors.
func Is ¶
Is reports whether any error in err's chain matches target.
The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap.
An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true.
An error type might provide an Is method so it can be treated as equivalent to an existing error. For example, if MyError defines
func (m MyError) Is(target error) bool { return target == fs.ErrExist }
then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for an example in the standard library.
func New ¶
New returns an error with the supplied message. New also records the stack trace at the point it was called.
func Unwrap ¶
Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.
func WithField ¶
WithField annotates err with the provided key/value pair, which can be inspected with the InspectFields() function. It also adds the stacktrace where WithField is called. If err is nil, nil is returned.
func WithFields ¶
WithFields annotates err with the provided fields, which can be inspected with the InspectFields() function. It also adds the stacktrace where WithFields is called.
func WithHTTPStatus ¶
WithHTTPStatus annotates err with the provided HTTP status. If err is nil, WithHTTPStatus returns nil.
Types ¶
type Fields ¶
type Fields map[string]interface{}
Fields represents arbitrary key/value fields with which errors may be annotated. This is intended for use with structured logging systems such as logrus.
type Frame ¶
Frame represents a program counter inside a stack frame. For historical reasons if Frame is interpreted as a uintptr its value represents the program counter + 1.
type Notes ¶
type Notes interface {
// HTTPStatus returns a new Notes instance which wraps the original and
// adds the provided HTTP status.
HTTPStatus(int) Notes
// Field returns a new Notes instance which wraps the original and adds the
// provided key/value field pair.
Field(string, interface{}) Notes
// Fields returns a new Notes instance which wraps the original and adds
// the provided fields.
Fields(Fields) Notes
// Wrap annotates the provided error with the annotations. If error is nil
// nil is returned. A stacktrace is also added where Wrap is called.
Wrap(error) error
}
Notes is a collection of zero or more error annotations, which can be attached to an error.
type StackTrace ¶
type StackTrace = pkgerrors.StackTrace
StackTrace is stack of Frames from innermost (newest) to outermost (oldest).
Source Files