werror

README

witchcraft-go-error

witchcraft-error-go defines the werror package, which provides an implementation of the error interface that stores safe and unsafe parameters and has the ability to specify another error as a cause.

Associating structured safe and unsafe parameters with an error allows other infrastructure such as logging to make decisions about what parameters should or should not be extricated.

TODO:

• Provide example usage and output in README

License

This project is made available under the Apache 2.0 License.

Documentation

Overview

Package werror defines an error type that can store safe and unsafe parameters and can wrap other errors.

Index

• func Convert(err error) error
• func Error(msg string, params ...Param) error
• func ErrorWithContextParams(ctx context.Context, msg string, params ...Param) error
• func Format(err Werror, safeParams map[string]interface{}, state fmt.State, verb rune)
• func GenerateErrorString(err error, outputEveryCallingStack bool) string
• func ParamFromError(err error, key string) (value interface{}, safe bool)
• func ParamsFromError(err error) (safeParams map[string]interface{}, unsafeParams map[string]interface{})
• func RootCause(err error) error
• func Wrap(err error, msg string, params ...Param) error
• func WrapWithContextParams(ctx context.Context, err error, msg string, params ...Param) error
• type Causer
• type Param
  • func Params(object wparams.ParamStorer) Param
  • func SafeAndUnsafeParams(safe, unsafe map[string]interface{}) Param
  • func SafeParam(key string, val interface{}) Param
  • func SafeParams(vals map[string]interface{}) Param
  • func UnsafeParam(key string, val interface{}) Param
  • func UnsafeParams(vals map[string]interface{}) Param
• type StackTrace
  • func NewStackTrace() StackTrace
  • func NewStackTraceWithSkip(skip int) StackTrace
• type StackTracer
• type Werror

Functions

func Convert

func Convert(err error) error

Convert err to werror error.

If err is not a werror-based error, then a new werror error is created using the message from err. Otherwise, returns unchanged err.

Example:

file, err := os.Open("file.txt")
if err != nil {
	return werror.Convert(err)
}

func Error

func Error(msg string, params ...Param) error

Error is identical to calling ErrorWithContext with a context that does not have any wparams parameters. DEPRECATED: Please use ErrorWithContextParams instead to ensure that all the wparams parameters that are set on the context are included in the error.

func ErrorWithContextParams

func ErrorWithContextParams(ctx context.Context, msg string, params ...Param) error

ErrorWithContextParams returns a new error with the provided message and parameters. The returned error also includes any wparams parameters that are stored in the context.

The message should not contain any formatted parameters -- instead, use the SafeParam* or UnsafeParam* functions to create error parameters.

Example:

password, ok := config["password"]
if !ok {
	return werror.ErrorWithContextParams(ctx, "configuration is missing password")
}

func Format

func Format(err Werror, safeParams map[string]interface{}, state fmt.State, verb rune)

Format formats a Werror using the provided format state. This is a utility method that can be used by other implementations of Werror. The safeParams argument is expected to include safe params for this error only, not for any underlying causes.

func GenerateErrorString

func GenerateErrorString(err error, outputEveryCallingStack bool) string

GenerateErrorString will attempt to pretty print an error depending on its underlying type If it is a werror then: 1) Each message and params will be groups together on a separate line 2) Only the deepest werror stacktrace will be printed 3) GenerateErrorString will be called recursively to pretty print underlying errors as well If the error implements the fmt.Formatter interface, then it will be printed verbosely Otherwise, the error's underlying Error() function will be called and returned

func ParamFromError

func ParamFromError(err error, key string) (value interface{}, safe bool)

ParamFromError returns the value of the parameter for the given key, or nil if no such key exists. Checks the parameters of the provided error and all of its causes. If the error and its causes contain multiple values for the same key, the most specific (deepest) value will be returned.

func ParamsFromError

func ParamsFromError(err error) (safeParams map[string]interface{}, unsafeParams map[string]interface{})

ParamsFromError returns all of the safe and unsafe parameters stored in the provided error.

If the error implements the Causer interface, then the returned parameters will include all of the parameters stored in the causes as well.

All of the keys and parameters of the map are flattened.

Parameters are added from the outermost error to the innermost error. This means that, if multiple errors declare different values for the same keys, the values for the most specific (deepest) error will be the ones in the returned maps.

func RootCause

func RootCause(err error) error

RootCause returns the initial cause of an error.

Traverses the cause hierarchy until it reaches an error which has no cause and returns that error.

func Wrap

func Wrap(err error, msg string, params ...Param) error

Wrap is identical to calling WrapWithContextParams with a context that does not have any wparams parameters. DEPRECATED: Please use WrapWithContextParams instead to ensure that all the wparams parameters that are set on the context are included in the error.

func WrapWithContextParams

func WrapWithContextParams(ctx context.Context, err error, msg string, params ...Param) error

WrapWithContextParams returns a new error with the provided message and stores the provided error as its cause. The returned error also includes any wparams parameters that are stored in the context.

The message should not contain any formatted parameters -- instead use the SafeParam* or UnsafeParam* functions to create error parameters.

Example:

users, err := getUser(userID)
if err != nil {
	return werror.WrapWithContextParams(ctx, err, "failed to get user", werror.SafeParam("userId", userID))
}

Types

type Causer

type Causer interface {
	Cause() error
}

Causer interface is compatible with the interface used by pkg/errors.

type Param

type Param interface {
	// contains filtered or unexported methods
}

func Params

func Params(object wparams.ParamStorer) Param

func SafeAndUnsafeParams

func SafeAndUnsafeParams(safe, unsafe map[string]interface{}) Param

func SafeParam

func SafeParam(key string, val interface{}) Param

func SafeParams

func SafeParams(vals map[string]interface{}) Param

func UnsafeParam

func UnsafeParam(key string, val interface{}) Param

func UnsafeParams

func UnsafeParams(vals map[string]interface{}) Param

type StackTrace

type StackTrace interface {
	fmt.Formatter
}

StackTrace provides formatting for an underlying stack trace.

func NewStackTrace

func NewStackTrace() StackTrace

NewStackTrace creates a new StackTrace, constructed by collecting program counters from runtime callers.

func NewStackTraceWithSkip

func NewStackTraceWithSkip(skip int) StackTrace

NewStackTraceWithSkip creates a new StackTrace that skips an additional `skip` stack frames.

type StackTracer

type StackTracer interface {
	StackTrace() StackTrace
}

StackTracer provides the behavior necessary to retrieve a StackTrace formatter.

type Werror

type Werror interface {
	error
	fmt.Formatter
	Causer
	StackTracer
	wparams.ParamStorer

	Message() string
}

Werror is an error type consisting of an underlying error, stacktrace, underlying causes, and safe and unsafe params associated with that error.