extenderr

README

extenderr

extend/wrap errors with: tags, error codes, http status, and human message. Plays nice with pkg/errors and go1.13 Unwrap.

// Example:

err := errors.New("user not found")
err = extenderr.WithHttpStatus(err, http.StatusNotFound)
err = extenderr.WithErrorCode(err, UserNotFoundErrorCode) // an enum
err = extenderr.WithTags(err, "user_id", 1234)
err = extenderr.WithHumanMessage(err, "Oh Darn, Looks like that user could not be found.")

// Later down the road, return the error code, human message, and http status to the client
message := extenderr.HumanMessage(err)
errorCode := extenderr.ErrorCode(err)
httpStatus := extenderr.HttpStatus(err))

// log the full error, and tags. Works well with structured loggers that accept ...interface{}
logger.Error(err.Error(), extenderr.Tags())

// If you are using pkg/errors, then the stack trace is still available:
stackTrace := fmt.Sprintf("%+v", err)

Documentation

Overview

package extenderr is an error utility aimed at application servers. It's purpose is to supply the outter most caller (http handler, middleware, etc) eith useful info about the error, and communicate accurate and helpful status to clients and human end users.

Gives errors additional annotations and retrivial of:

• a description that is safe to expose to humans (humanMessage interface)
• an enum error code that can be checked (errorCoder interface)
• an HTTP status code that can be returned (httpStatuser interface)
• key/value pairs that have been attached (tagger interface)

All of the interfaces are private, but considered stable, such that if your use case deviates from this package, one should be able to implement the interface in a similar way that this package implements "Error", "Format", Cause", and "Unwrap".

This package is safe to use on any error (and nil), it will return "zero" values for any unused fields, or any unimplimented interfaces when retrieving annotations.

Index

• func ErrorCode(errToWalk error) int
• func HttpStatus(errToWalk error) int
• func HumanMessage(errToWalk error) string
• func TagMap(errToWalk error) map[interface{}]interface{}
• func Tags(errToWalk error) []interface{}
• func WithErrorCode(err error, errorCode int) error
• func WithHttpStatus(err error, status int) error
• func WithHumanMessage(err error, message string) error
• func WithTags(err error, keysAndValues ...interface{}) error

Functions

func ErrorCode

func ErrorCode(errToWalk error) int

ErrorCode returns the first (outter most) error code encountered in the error chain. An int enum error code is intended for signaling a specific error state to clients of an API.

func HttpStatus

func HttpStatus(errToWalk error) int

HttpStatus returns the first (outter most) http status code encountered in the error chain.

func HumanMessage

func HumanMessage(errToWalk error) string

HumanMessage returns the first (outter most) message encountered in the error chain. The message is intended to be exposed to human. If not message exists or the error is nil it returns empty string.

func TagMap

func TagMap(errToWalk error) map[interface{}]interface{}

TagMap will return a map of all tags in the error chain. This is a best effort, unblanced key pairs will be made even, and duplicate tags overwritten (the inner most tag wins).

func Tags

func Tags(errToWalk error) []interface{}

Tags returns all of the tags encountered in the error chain.

func WithErrorCode

func WithErrorCode(err error, errorCode int) error

WithErrorCode wraps the error with an error code for machines.

func WithHttpStatus

func WithHttpStatus(err error, status int) error

WithHttpStatus wraps the error with an http status code.

func WithHumanMessage

func WithHumanMessage(err error, message string) error

WithHumanMessage wraps the error with a message intended for end users.

func WithTags

func WithTags(err error, keysAndValues ...interface{}) error

WithTags wraps an error with a set of key/value tags attached.