errors

Documentation

Overview

Package errors provides error and error wrapping facilities that allow for the easy reporting of call stacks and structured error annotations.

Index

• func Cause(err error) (stack CallStack, wraps []*Base, cause error)
• func HTTPStatus(err error) (status int, ok bool)
• func New(text string) error
• type Base
  • func NewBase(skip int, text string) *Base
  • func (e *Base) AddFields(fields Fields)
  • func (e *Base) Error() string
  • func (e *Base) Location() *Location
  • func (e *Base) MarshalJSON() ([]byte, error)
  • func (e *Base) Stack() CallStack
  • func (e *Base) String() string
• type Call
  • func (c Call) Location() *Location
  • func (c Call) MarshalJSON() ([]byte, error)
  • func (c Call) String() string
• type CallStack
  • func CurrentCallStack(skip int) CallStack
• type Fields
• type HTTPError
  • func BadRequest(fields Fields, text string) *HTTPError
  • func Conflict(fields Fields, text string) *HTTPError
  • func Forbidden(fields Fields, text string) *HTTPError
  • func InternalError(fields Fields, text string) *HTTPError
  • func NewHTTPError(status int, text string) *HTTPError
  • func NotFound(fields Fields, text string) *HTTPError
  • func PaymentRequired(fields Fields, text string) *HTTPError
  • func (e *HTTPError) HTTPStatus() int
  • func (e *HTTPError) With(fields Fields) *HTTPError
  • func (e *HTTPError) WithStatus(status int) *HTTPError
• type Location
• type Wrapped
  • func WithMessage(err error, text string) *Wrapped
  • func WithStack(err error) *Wrapped
  • func Wrap(err error, fields Fields) *Wrapped
  • func Wrapf(err error, fields Fields, format string, args ...interface{}) *Wrapped
  • func (w *Wrapped) Error() string
  • func (w *Wrapped) Unwrap() (wraps []*Base, cause error)
  • func (w *Wrapped) With(fields Fields) *Wrapped

Functions

func Cause

func Cause(err error) (stack CallStack, wraps []*Base, cause error)

Cause checks if the passed in error is a Wrapped. If so, it will extract & return information about all the wrapped errors inside. It will return the CallStack of cause, if it supports the errors.Stack() interface, or the innermost wrap (which should be the closest wrap to cause.) If error is not a wrapped, cause is same as input err.

func HTTPStatus

func HTTPStatus(err error) (status int, ok bool)

HTTPStatus is a convenience checker for a (possibly wrapped) HTTPStatus interface error. If err doesn't support the HTTPStatus interface, it will default to either StatusOK or StatusInternalServerError as appropriate.

func New

func New(text string) error

New returns a base error that captures the call stack.

Types

type Base

type Base struct {
	Text      string
	Fields    Fields
	CallStack CallStack
}

Base is an error type that supports capturing the call stack at creation time, and storing separate text & data to allow structured logging. While it could be used directly, it may make more sense as an anonymous inside a package/application specific error struct.

func NewBase

func NewBase(skip int, text string) *Base

NewBase creates a new Base, capturing a call trace starting at "skip" calls above.

func (*Base) AddFields

func (e *Base) AddFields(fields Fields)

AddFields allows a Error message to be further annotated with a set of key,values, to add more context when inspecting Error messages.

func (*Base) Error

func (e *Base) Error() string

func (*Base) Location

func (e *Base) Location() *Location

Location returns the location info (file, line, ...) for the place where this Error error was created.

func (*Base) MarshalJSON

func (e *Base) MarshalJSON() ([]byte, error)

MarshalJSON creates a JSON representation of a Error.

func (*Base) Stack

func (e *Base) Stack() CallStack

Stack returns the call stack from where this Error was created.

func (*Base) String

func (e *Base) String() string

type Call

type Call runtime.Frame

Call holds a call frame

func (Call) Location

func (c Call) Location() *Location

Location uses the gostack package to construct file, line, and other info about this call.

func (Call) MarshalJSON

func (c Call) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON representation.

func (Call) String

func (c Call) String() string

type CallStack

type CallStack []Call

CallStack is a convenience alias for a call stack.

func CurrentCallStack

func CurrentCallStack(skip int) CallStack

CurrentCallStack returns the call stack, skipping the specified depth of calls.

type Fields

type Fields map[string]interface{}

Fields holds the annotations for an error.

type HTTPError

type HTTPError struct {
	*Base
	Status int
}

HTTPError provides an easy way to specify the http status code equivalent for an error at error creation time, as well as inheriting the useful features from Base (call stacks, structured text & data).

func BadRequest

func BadRequest(fields Fields, text string) *HTTPError

BadRequest is returned when a request did not pass validation, or is in appropriate for the state of the resource it would affect.

func Conflict

func Conflict(fields Fields, text string) *HTTPError

Conflict is returned when request could not be completed due to a conflict with the current state of the resource.

func Forbidden

func Forbidden(fields Fields, text string) *HTTPError

Forbidden is returned if the requesting user does not have the required permissions for a request.

func InternalError

func InternalError(fields Fields, text string) *HTTPError

InternalError should only be returned if no other specific error applies.

func NewHTTPError

func NewHTTPError(status int, text string) *HTTPError

NewHTTPError constructs an error with the given http status.

func NotFound

func NotFound(fields Fields, text string) *HTTPError

NotFound is returned when a resource was not found.

func PaymentRequired

func PaymentRequired(fields Fields, text string) *HTTPError

PaymentRequired is returned if the requested resource must be purchased.

func (*HTTPError) HTTPStatus

func (e *HTTPError) HTTPStatus() int

HTTPStatus returns the appropriate http status code for this error.

func (*HTTPError) With

func (e *HTTPError) With(fields Fields) *HTTPError

With allows additional structured data fields to be added to this HTTPError.

func (*HTTPError) WithStatus

func (e *HTTPError) WithStatus(status int) *HTTPError

WithStatus allows setting the http status.

type Location

type Location struct {
	File string
	Line int
	Func string
}

Location is the parsed file, line, and other info we can determine from a specific gostack.Call.

type Wrapped

type Wrapped struct {
	*Base
	// contains filtered or unexported fields
}

Wrapped provides a way to add additional context when passing back an error to a caller. It inherits the useful features from Base (call stacks, structured text & data).

func WithMessage

func WithMessage(err error, text string) *Wrapped

WithMessage takes an originating cause and text description, returning a wrapped error with the text and stack.

func WithStack

func WithStack(err error) *Wrapped

WithStack takes an originating cause and returns a wrapped error that just records the stack.

func Wrap

func Wrap(err error, fields Fields) *Wrapped

Wrap takes an originating "cause" error and annotates it just with the source file & line of the wrap point.

func Wrapf

func Wrapf(err error, fields Fields, format string, args ...interface{}) *Wrapped

Wrapf takes an originating "cause" error and annotates it with text and the source file & line of the wrap point.

func (*Wrapped) Error

func (w *Wrapped) Error() string

func (*Wrapped) Unwrap

func (w *Wrapped) Unwrap() (wraps []*Base, cause error)

Unwrap extracts any layered Wrapped errors inside of this one, returning the first non-Wrapped error found as the original cause.

func (*Wrapped) With

func (w *Wrapped) With(fields Fields) *Wrapped

With allows adding additional structured data fields.