faults

README

errors

The library errors provides type safe constructs to annotate Golang errors with the context and handle opaque errors without the boilerplate.

Inspiration

The library is inspired by the post -- Assert Golang Errors For Behavior: Everything You Need To Know Before Making Robust and Scalable Error Handling and its recommendation to deal with opaque errors -- failure does not have global catastrophic impacts but local functionality is impaired, execution of current control flow is terminated and incorrect results are returned.

Opaque errors is a classical scenario of error handling in Golang, which is advertised by the majority of online publications. The code block knows that an error occurred. It does not have the ability to inspect error details, it only knows about the successful or unsuccessful completion of the called function. This error bubbles along the call stack until it is handler by the application.

func foo() (*Bar, error) {
  val, err := db.dynamo.GetItem(ctx, req)
  if err != nil {
    return nil, err
  }
  // continue happy path
}

The debugging of opaque error handling becomes a difficult job because it violates annotate errors with the context recommendation. The Go Programming Language recommends inclusion of the context to the error path using fmt.Errorf.

func foo() (*Bar, error) {
  val, err := db.dynamo.GetItem(ctx, req)
  if err != nil {
    return nil, fmt.Errorf("[foo] dynamodb i/o failed: %w", err)
  }
  // continue happy path
}

In the context of a large application, fmt.Errorf("[foo] dynamodb i/o failed: %w", err) would be repeated a gazillion times for each service call to dynamo, any refactoring of the error text or context structure becomes a tedious job - the type system would not help at all because fmt.Errorf is not type safe.

Usage of this library to define a type safe wrapping of errors is the better approach to annotate error context:

// produces an error message
// [foo] dynamodb i/o failed: original error
const errDynamoIO = faults.Type("dynamodb i/o failed")

func foo() (*Bar, error) {
  val, err := db.dynamo.GetItem(ctx, req)
  if err != nil {
    return nil, errDynamoIO.New(err)
  }
  // continue happy path
}

Getting started

The latest version of the library is available at main branch of this repository. All development, including new features and bug fixes, take place on the main branch using forking and pull requests as described in contribution guidelines. The stable version is available via Golang modules.

import "github.com/fogfish/faults"

const (
  // create basic error context
  errSomeA = faults.Type("something is failed")
  // create error context with arguments
  errSomeB = faults.Type("something is failed %s")
  // create "fast" error context, would not annotate error with call stack
  errSomeC = faults.Fast("something is failed")
  // create error context with type safe arguments
  errSomeD = faults.Safe1[int]("something %d is failed")
  errSomeE = faults.Safe2[int, string]("something %d is failed %s")
)

Gotchas

The library uses the runtime package to discover function context and inject it into the error. If you are developing a highly loaded system, usage of runtime package might cause about 75% of the loss of the error path capacity. Therefore, the library support a "fast" variant of the type faults.Fast, which omits usage of runtime package internally.

How To Contribute

The library is MIT licensed and accepts contributions via GitHub pull requests:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

The build and testing process requires Go version 1.18 or later.

build and test library.

git clone https://github.com/fogfish/faults
cd errors
go test
go test -run=^$ -bench=. -cpu 1 -benchtime=1s

commit message

The commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter Contributing to a Project of Git book.

bugs

If you experience any issues with the library, please let us know via GitHub issues. We appreciate detailed and accurate reports that help us to identity and replicate the issue.

License

Documentation

Overview

Package errors provides type safe constructs to annotate Golang errors with the context and handle opaque errors without boilerplate https://tech.fog.fish/2022/07/05/assert-golang-errors-for-behavior.html#opaque-errors

It solves a problem of annotate errors with the context so that consequent debugging of opaque error handling becomes an easy job. Instead of using `fmt.Errorf` to include the execution context to the error, it defines a type safe wrapping of errors.

Index

• func IsConflict(err error) bool
• func IsGone(err error) bool
• func IsNotFound(err error, key ...string) bool
• func IsPreConditionFailed(err error) bool
• func IsStatusCode(err error, code ...string) bool
• func IsTimeout(err error, deadline time.Duration) bool
• type Conflict
• type Fast
  • func (e Fast) New(err error, args ...any) error
• type Gone
• type Issue
• type NotFound
• type PreConditionFailed
• type Safe1
  • func (safe Safe1[A]) New(err error, a A) error
• type Safe2
  • func (safe Safe2[A, B]) New(err error, a A, b A) error
• type Safe3
  • func (safe Safe3[A, B, C]) New(err error, a A, b A, c C) error
• type Safe4
  • func (safe Safe4[A, B, C, D]) New(err error, a A, b A, c C, d D) error
• type Safe5
  • func (safe Safe5[A, B, C, D, E]) New(err error, a A, b A, c C, d D, e E) error
• type StatusCode
• type Timeout
• type Type
  • func (e Type) New(err error, args ...any) error

Functions

func IsConflict

func IsConflict(err error) bool

func IsGone

func IsGone(err error) bool

func IsNotFound

func IsNotFound(err error, key ...string) bool

func IsPreConditionFailed

func IsPreConditionFailed(err error) bool

func IsStatusCode

func IsStatusCode(err error, code ...string) bool

func IsTimeout

func IsTimeout(err error, deadline time.Duration) bool

Types

type Conflict

type Conflict interface{ Conflict() bool }

type Fast

type Fast string

Fast creates a basic context for the error but skips usage of runtime package.

const errSome = errors.Fast("something is failed")

func (Fast) New

func (e Fast) New(err error, args ...any) error

New wraps error into the context. The function expands the context with arguments.

if err := doSomething(); err != nil {
	return nil, errSome.New(err)
}

type Gone

type Gone interface{ Gone() bool }

type Issue

type Issue interface {
	ErrCode() string
	ErrType() string
	ErrInstance() string
	ErrTitle() string
	ErrDetail() string
}

type NotFound

type NotFound interface{ NotFound() string }

type PreConditionFailed

type PreConditionFailed interface{ PreConditionFailed() bool }

type Safe1

type Safe1[A any] string

Safe1 creates an error context with 1 argument

const errSome = errors.Safe1[string]("something is failed %s")

func (Safe1[A]) New

func (safe Safe1[A]) New(err error, a A) error

New wraps error into the context. The function expands the context with arguments.

if err := doSomething(); err != nil {
	return nil, errSome.New(err, "foo")
}

type Safe2

type Safe2[A, B any] string

Safe2 creates an error context with 2 argument

func (Safe2[A, B]) New

func (safe Safe2[A, B]) New(err error, a A, b A) error

New wraps error into the context.

type Safe3

type Safe3[A, B, C any] string

Safe3 creates an error context with 3 argument

func (Safe3[A, B, C]) New

func (safe Safe3[A, B, C]) New(err error, a A, b A, c C) error

New wraps error into the context.

type Safe4

type Safe4[A, B, C, D any] string

Safe4 creates an error context with 4 argument

func (Safe4[A, B, C, D]) New

func (safe Safe4[A, B, C, D]) New(err error, a A, b A, c C, d D) error

New wraps error into the context.

type Safe5

type Safe5[A, B, C, D, E any] string

Safe5 creates an error context with 5 argument

func (Safe5[A, B, C, D, E]) New

func (safe Safe5[A, B, C, D, E]) New(err error, a A, b A, c C, d D, e E) error

New wraps error into the context.

type StatusCode

type StatusCode interface{ StatusCode() string }

type Timeout

type Timeout interface{ Timeout() time.Duration }

type Type

type Type string

Type creates a basic context for the error. The context produces an error like `[function line] text defined by context: original error`

const errSome = errors.Type("something is failed")

func (Type) New

func (e Type) New(err error, args ...any) error

New wraps error into the context. The function expands the context with arguments.

if err := doSomething(); err != nil {
	return nil, errSome.New(err)
}