failure

failure

failure provides typed, HTTP-aware errors with optional metadata (code, description, payload) and helpers for attaching the name of the operation that produced an error — all built on top of the standard errors package, so errors.Is, errors.As and %w keep working.

Install

go get git.appkode.ru/pub/go/failure

To import this private module, create an access token in the Gitlab User Settings page and write it to ~/.netrc:

machine git.appkode.ru
  login oauth2
  password your-access-token

You also need to remove the section with url.insteadOf=https://git.appkode.ru/ from .gitconfig (if any). Background:

• gitlab-foss#37832
• gitlab-foss#65681

Typed errors

Every typed error is an Error[K] of a kind K. Build one with the generic New, or with the equivalent New<Kind>Error helper; Is / As report and extract the category anywhere in the chain:

err := failure.New[failure.NotFound]("user not found")

failure.Is[failure.NotFound](err) // true
err.Error()                       // "not found: user not found"

// The named helpers are thin wrappers over the generic form:
failure.NewNotFoundError("user not found") // == failure.New[failure.NotFound](...)
failure.IsNotFoundError(err)               // == failure.Is[failure.NotFound](err)

// As returns the concrete typed error:
if e, ok := failure.As[failure.NotFound](err); ok {
    _ = e.HTTPStatus() // 404
}

Available kinds and the status HTTPStatus maps them to:

failure.HTTPStatus(failure.New[failure.Forbidden]("nope")) // 403
failure.HTTPStatus(errors.New("boom"))                     // 500

The set of kinds is closed: Kind's methods are unexported, so external packages cannot define new categories.

Metadata: code, description, payload

Constructors accept options:

err := failure.NewInvalidArgumentError(
    "validation failed",
    failure.WithCode(failure.NewErrorCode("E_VALIDATION")),
    failure.WithDescription("email is required"),
    failure.WithPayload(map[string]string{"field": "email"}),
)

failure.Code(err)                                  // "E_VALIDATION"
failure.HasCode(err, failure.NewErrorCode("E_VALIDATION")) // true
failure.Description(err)                            // "email is required"
failure.Payload(err)                               // map[field:email]

Code, Description and Payload traverse the chain, so they keep working after the error is wrapped further up the stack.

Attaching a cause

WithCause attaches an underlying error. It stays reachable through errors.Is, errors.As and Cause, and is appended to the message. A nil cause is a no-op:

err := failure.NewNotFoundError("user not found", failure.WithCause(sql.ErrNoRows))

err.Error()                   // "not found: user not found: sql: no rows in result set"
errors.Is(err, sql.ErrNoRows) // true
failure.IsNotFoundError(err)  // true
failure.Cause(err)            // sql.ErrNoRows

Cause returns a single root by following the first branch of a multi-error. To inspect every branch of an errors.Join / MultiWrap node, use Causes, which returns the root cause of each branch:

failure.Causes(breadcrumb.MultiWrap(errA, errB)) // []error{rootA, rootB}

Stack traces

WithStack records the call stack at the point the error is created — an automatic alternative to threading Breadcrumb names through every function. The stack is captured once, survives wrapping, and is read back with StackTrace. It never appears in Error(), so logs stay terse unless you ask for it:

err := failure.NewNotFoundError("user 42", failure.WithStack())

for _, f := range failure.StackTrace(err) {
    fmt.Printf("%s\n\t%s:%d\n", f.Function, f.File, f.Line)
}
// myapp/repo.(*Users).Find    repo.go:17
// myapp/service.(*Users).Get  service.go:21
// myapp/api.getUser           api.go:25
// ...

The trace starts at the caller that built the error; the library's own frames are trimmed. StackTrace returns nil when no error in the chain captured a stack.

Breadcrumbs

Breadcrumb wraps errors with the name of the function that returned them, building a readable call trail without losing the underlying chain. The name nods to the trail Hansel and Gretel dropped to find their way home — see breadcrumb navigation:

func GetUser(id string) error {
    const breadcrumb failure.Breadcrumb = "GetUser"

    if err := repo.Find(id); err != nil {
        return breadcrumb.Wrap(err) // "GetUser: <err>"; nil stays nil
    }

    return nil
}

MultiWrap joins several errors under one breadcrumb on a single line (; -separated, so the message stays readable inside one-line log fields like a JSON message — unlike errors.Join, which separates with newlines). nil and all-nil inputs collapse to a nil error, and every branch stays reachable through errors.Is / errors.As / Causes:

return breadcrumb.MultiWrap(validateName(), validateEmail(), validateAge())

Development

make format   # gofumpt + gci
make lint     # golangci-lint
make test     # race tests + coverage report

License

Apache-2.0