errors

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 Append(err error, errs ...error) error
• func As(err error, target interface{}) bool
• func AttachStack(err error, st StackTrace) error
• func Errorf(format string, args ...interface{}) error
• func ExtractGRPCCode(err error) (codes.Code, bool)
• func ExtractGRPCStatus(err error) (*status.Status, bool)
• func ExtractHTTPStatus(err error) (int, bool)
• func HTTPStatusf(status int, format string, args ...interface{}) error
• func InspectErrors(err error) []error
• func InspectFields(err error) map[string]interface{}
• func InspectGRPCCode(err error) codes.Code
• func InspectGRPCStatus(err error) *status.Status
• func InspectHTTPStatus(err error) int
• func InspectRetryAfter(err error) string
• func Internal(err error) error
• func Is(err, target error) bool
• func MustLog(err error) error
• func New(message string) error
• func ReadChan(errCh <-chan error) error
• func ReadChanN(errCh <-chan error, n int) 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 WithRetryAfter(err error, t time.Time) error
• func WithRetryAfterDur(err error, dur time.Duration) error
• func WithStack(err error) error
• func WithStackN(err error, skip int) error
• func WithoutRetryAfter(err error) error
• type Fields
• type Frame
• type Notes
  • func NewNotes() Notes
• type StackTrace
  • func Callers(n int) StackTrace
  • func InspectDeepStackTrace(err error) StackTrace
  • func InspectStackTrace(err error) StackTrace
• type Standard
  • func (e Standard) Error() string
  • func (e Standard) HTTPStatus() int

Constants

const (
	StatusBadRequest                   = Standard(http.StatusBadRequest)
	StatusUnauthorized                 = Standard(http.StatusUnauthorized)
	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)
	StatusUnavailableForLegalReasons   = Standard(http.StatusUnavailableForLegalReasons)

	StatusInternalServerError           = Standard(http.StatusInternalServerError)
	StatusNotImplemented                = Standard(http.StatusNotImplemented)
	StatusBadGateway                    = Standard(http.StatusBadGateway)
	StatusServiceUnavailable            = Standard(http.StatusServiceUnavailable)
	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.

Functions

func Append

func Append(err error, errs ...error) error

Append joins zero or more errors into a single error. Any nil values are excluded, returning nil if all inputs are nil. Any multi-errors in the input are treated as multiple errors. If the final result is a single error, it is returned unaltered, otherwise a multi-error value is returned, which can in turn be exploded by calling the Errors() method.

func As

func As(err error, target interface{}) bool

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 AttachStack

func AttachStack(err error, st StackTrace) error

AttachStack annotates err with the provided stack trace.

func Errorf

func Errorf(format string, args ...interface{}) error

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 ExtractGRPCCode

func ExtractGRPCCode(err error) (codes.Code, bool)

ExtractGRPCCode works just like ExtractGRPCCode, but returns only the status code.

func ExtractGRPCStatus

func ExtractGRPCStatus(err error) (*status.Status, bool)

ExtractGRPCStatus works just like the standard status.FromError(), except that it works on wrapped errors as well. The bool value will be true if err wraps a GRPCStatus error. If err is not a GRPCStatus error, a Status with code.Unknown is returned. If err is nil, a status with code OK and message OK is returned.

func ExtractHTTPStatus

func ExtractHTTPStatus(err error) (int, bool)

ExtractHTTPStatus returns the outter-most HTTP status in the error stack. The bool value will be true if err includes an explicit HTTP status code.

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.

func HTTPStatusf

func HTTPStatusf(status int, format string, args ...interface{}) error

HTTPStatusf works like calling WithHTTPStatus(status, Errorf(format, args ...)).

func InspectErrors

func InspectErrors(err error) []error

InspectErrors explodes a multi-error, such as that returned by Append, and returns a slice of the underlying errors. If err is not a multi-error, it will be the only element in the returned slice.

Any error which satisfies the following method is considered a multi-error:

type multiError interface {
	Errors() error
}

func InspectFields

func InspectFields(err error) map[string]interface{}

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 InspectGRPCCode

func InspectGRPCCode(err error) codes.Code

InspectGRPCCode works just like InspectGRPCStatus, but returns only the status code.

func InspectGRPCStatus

func InspectGRPCStatus(err error) *status.Status

InspectGRPCStatus is like ExtractGRPCStatus, but disregards the bool value.

func InspectHTTPStatus

func InspectHTTPStatus(err error) int

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 InspectRetryAfter

func InspectRetryAfter(err error) string

InspectRetryAfter returns the outter-most RetryAfter value in the error stack.

If err is nil, there is no RetryAfter value found, or the RetryAfter value is blank (as when set by WithoutRetryAfter), the empty string is returned.

func Internal

func Internal(err error) error

Internal promotes err to an Internal Server Error. Shorter equivalent of WithHTTPStatus(err, http.StatusInternalServerError)

func Is

func Is(err, target error) bool

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 MustLog

func MustLog(err error) error

MustLog flags that an error should be logged, regardless of its HTTP status.

func New

func New(message string) error

New returns an error with the supplied message. New also records the stack trace at the point it was called.

func ReadChan

func ReadChan(errCh <-chan error) error

ReadChan reads errors from an error channel, until the channel is closed, returning a multi-error. To inspect the individual errors, use the Errors() method, or use the InspectErrors function.

func ReadChanN

func ReadChanN(errCh <-chan error, n int) error

ReadChanN reads up to n errors from an error channel, returning a multi-error. To inspect the individual errors, use the Errors() method, or use the InspectErrors function.

When n values (including nils) are read, or errCh is closed, the function returns. If n=0, there is no limit.

func Unwrap

func Unwrap(err error) error

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

func WithField(err error, key string, value interface{}) error

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

func WithFields(err error, fields Fields) error

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

func WithHTTPStatus(err error, status int) error

WithHTTPStatus annotates err with the provided HTTP status. If err is nil, WithHTTPStatus returns nil.

func WithRetryAfter

func WithRetryAfter(err error, t time.Time) error

WithRetryAfter wraps err such that when queried with InspectRetryAfter, it will return a RetryAfter value based on t.

func WithRetryAfterDur

func WithRetryAfterDur(err error, dur time.Duration) error

WithRetryAfterDur wraps err such that when queried with InspectRetryAfter, it will return a RetryAfter header based on dur.

func WithStack

func WithStack(err error) error

WithStack annotates err with a stack trace at the point WithStack was called. If err is nil, WithStack returns nil.

func WithStackN

func WithStackN(err error, skip int) error

WithStackN annotates err with a stack trace at the point WithStackN was called, minus skip frames. If err is nil, WithStack returns nil.

func WithoutRetryAfter

func WithoutRetryAfter(err error) error

WithoutRetryAfter will wrap err with an error that returns an empty string for a RetryAfter query.

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

type Frame = pkgerrors.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 (unless
	// NoStack() has been called).
	Wrap(error) error
	// Errorf returns a new error annotated with the annotations. Equivalent to
	// Wrap(fmt.Errorf(format, args...)).
	Errorf(format string, args ...interface{}) error
	// NoStack returns a new Notes instance which will not include a stack
	// trace when Wrap() is called.
	NoStack() Notes
	// RetryAfter returns a new Notes instance which wraps the original and
	// adds the provided RetryAfter value based on t.
	RetryAfter(time.Time) Notes
	// RetryAfterDur returns a new Notes instance which wraps the original and
	// adds the provided RetryAfter value based on dur.
	RetryAfterDur(time.Duration) Notes
	// NoRetryAfter returns a new Notes instance which wraps the original and
	// adds a blank RetryAfter value.
	NoRetryAfter() Notes
	// StackN instructs the Wrap function to attach a stack trace with s frames
	// skipped.
	StackN(s uint) Notes
}

Notes is a collection of zero or more error annotations, which can be attached to an error.

func NewNotes

func NewNotes() Notes

NewNotes returns an empty Notes collection.

type StackTrace

type StackTrace = pkgerrors.StackTrace

StackTrace is stack of Frames from innermost (newest) to outermost (oldest).

func Callers

func Callers(n int) StackTrace

Callers generates a StackTrace. If n > 0, n frames are skipped.

func InspectDeepStackTrace

func InspectDeepStackTrace(err error) StackTrace

InspectDeepStackTrace returns the last (inner-most) stacktrace in error, or nil if none is found

func InspectStackTrace

func InspectStackTrace(err error) StackTrace

InspectStackTrace returns the first (outter-most) stacktrace in err, or nil if none is found.

type Standard

type Standard int

Standard converts a standard HTTP status code into a useable error

func (Standard) Error

func (e Standard) Error() string

func (Standard) HTTPStatus

func (e Standard) HTTPStatus() int

HTTPStatus returns the HTTP status associated with the error.