errors

README

errors

This errors package is designed based on Failure is your Domain blog:

The tricky part about errors is that they need to be different things to different consumers of them. 
In any given system, we have at least 3 consumer roles — the application, the end user, & the operator.

Features

• Allows specifying Logical Operation that caused the failure. helps the operator
• Allows specifying Machine-readable error code. helps the application
• Allows specifying Human-readable message. helps the end user
• Allows specifying nested error.
• Support gRPC styles errors with Details

ErrorCode helps to categorize errors into:

1. System Errors - Only recoverable after fixing system failures. e.g., disk fill, database down., certs expaired.
2. Temporary Errors - Recoverable immediately after retry with exponential backoff
3. Data Errors - Input validation errors which need to be reprocessed after fixing the data issues

Each feature can be added to the previous wrapped or leaf error, using available wrapper constructors
While using wrapped errors, you can reveal each character/trait by unwrapping like an Onion 🧅.
using Unwrap() / As() / Is() or helpers functions GetAllDetails, FlattenDetails, HasAssertionFailure, GetCategory, GetCode, GetOperation etc.

Interface

type ErrorOperation interface {
	error
	Operation() string
}

type ErrorCoder interface {
	error
	Code() codes.Code
	Category() categories.Category
}

TODO

• make this package generic (use int instead fo codes.Code?) and move it to toolkit
• codes.Code should be in consuming application
• Explore implementation of kratos errors and connect errors

Reference

• Failure is your Domain

• Creating domain specific error helpers in Go with errors.As

• advanced gRPC Error Usage

• cockroachdb errors

• atlas-app-toolkit errors

• go-multierror

Documentation

Index

• func GetCategory(err error) categories.Category
• func GetCode(err error) codes.Code
• func GetOperation(err error) string
• func New(c codes.Code, operation string, msg string) error
• func Newf(c codes.Code, operation string, format string, a ...interface{}) error
• func WithCode(err error, code codes.Code) error
• func WithCodeAndOperation(err error, code codes.Code, operation string) error
• func WithOperation(err error, operation string) error
• type ErrorCoder
• type ErrorOperation

Examples

• Newf

Functions

func GetCategory

func GetCategory(err error) categories.Category

func GetCode

func GetCode(err error) codes.Code

func GetOperation

func GetOperation(err error) string

func New

func New(c codes.Code, operation string, msg string) error

New constructors are for creating Leaf errors

func Newf

func Newf(c codes.Code, operation string, format string, a ...interface{}) error

Example

coErr := Newf(codes.DataSchemaNotFound, "test", "hello %s", "world")

coErrWithHint := errors.WithHint(coErr, "sumo hint")
// fmt.Printf("%+v", coErrWithHint)

fmt.Println(errors.FlattenHints(coErrWithHint))
fmt.Println(GetOperation(coErrWithHint))
fmt.Println(GetCode(coErrWithHint))
fmt.Println(GetCategory(coErrWithHint))
fmt.Println(errors.GetAllHints(coErrWithHint))

Output:


sumo hint
test
DataSchemaNotFound
Data
[sumo hint]

func WithCode

func WithCode(err error, code codes.Code) error

Wrapper constructors are for wrapping additional traits to previous error WithCode adds code to an existing error.

func WithCodeAndOperation

func WithCodeAndOperation(err error, code codes.Code, operation string) error

WithCodeAndOperation adds code and operation to an existing error.

func WithOperation

func WithOperation(err error, operation string) error

WithOperation adds operation to an existing error.

Types

type ErrorCoder

type ErrorCoder interface {
	error
	Code() codes.Code
	Category() categories.Category
}

ErrorHinter is implemented by types that can provide Machine-readable error code.

type ErrorOperation

type ErrorOperation interface {
	error
	Operation() string
}

ErrorOperation is implemented by types that can provide Logical Operation that caused the failure