failure

package module
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: MIT Imports: 10 Imported by: 17

README

failure

Structured, typed errors for Go. Errors carry a stable type code, human-readable message, key/value payload, and optional stack trace. They serialize to JSON and survive API boundaries with type identity intact.

Installation

go get gitlab.com/gorib/failure

Concepts

Concept Description
Type code Stable slug derived from the format string ("resource not found" → "resource_not_found"). Used for errors.Is matching and JSON wire format.
Message Human-readable string with values substituted in.
Payload map[string]any of named values extracted from the message template.
Stack Call-site frames captured by Wrap (not New).
Transport The status of the one hop the error crossed — an HTTP response, a gRPC status. Reachable, but not part of the error's identity, and removable before the error is raised onward.

Usage

Sentinel errors

Declare typed sentinels at package level with New:

var (
    ErrNotFound   = failure.New("resource not found")
    ErrForbidden  = failure.New("forbidden")
)

The format string becomes the type code. Two calls with the same format string share the same type code, so errors.Is works across package boundaries.

Call-site errors

Use Wrap at the point of failure. It captures a stack trace and associates causes:

func fetchUser(id string) error {
    return failure.Wrap("%w: id={id}", ErrNotFound, id)
}

Wrap captures the stack at the call site. New does not — it is for sentinels only.

Message templates

Two substitution forms are supported:

Syntax Substitutes Stored in payload
%w Wrapped error's message (standard library) No
{key} Next non-error argument Yes, under "key"
err := failure.Wrap("db error: table={table} op={op}", ErrDB, "users", "insert")
// err.Error() → "db error: table=users op=insert"

if e, ok := failure.FromError(err); ok {
    e.Payload() // map[string]any{"table": "users", "op": "insert"}
}

You can combine both:

err := failure.Wrap("%w: user={user}", cause, username)
Checking error types
if errors.Is(err, ErrNotFound) {
    // type codes match
}

if e, ok := failure.FromError(err); ok {
    fmt.Println(e.Type())    // "resource_not_found"
    fmt.Println(e.Payload()) // map[string]any{...}
}

Matching compares type codes, never pointers. Against a target that is not a failure — a stdlib sentinel, one from somebody else's library — the target's own message is slugified and compared the same way, so errors.Is(err, errors.New("resource not found")) matches too.

Slugify is exported because that rule has to be applied outside as well, and it is what turns a message into a type code: %w is removed, {placeholder} names are dropped along with their braces, letters and digits are kept, everything else collapses into single underscores, and the result is lowercased and trimmed. A slug slugifies to itself.

failure.Slugify("db error: table={table} op={op}") // "db_error_table_op"
Stack traces
if e, ok := failure.FromError(err); ok {
    for _, f := range e.Stack() {
        fmt.Printf("%s\n\t%s:%d\n", f.Function, f.File, f.Line)
    }
}

Frames come newest first, with the runtime's own and failure's own left out. A sink that wants them oldest first — Sentry does — reverses the slice itself.

type Frame struct {
    Function string
    File     string
    Line     int
}
Panics
defer func() {
    if r := recover(); r != nil {
        err = failure.Panic(r)
        // errors.Is(err, failure.ErrPanic) == true
    }
}()

A recovered value that is already a *failure.Error is returned as it is, without ErrPanic.

Catch is the same thing around a call, which is what a middleware wants:

err := failure.Catch(func() error { return handler(ctx) })

An error the function returned itself wins — Catch only fills in the panic when the call came back nil.

JSON serialization

*Error implements json.Marshaler / json.Unmarshaler.

Wire format:

{
  "kind":    "gorib_app_error_v1",
  "type":    "resource_not_found",
  "types":   ["resource_not_found"],
  "message": "resource not found: id=42",
  "payload": {"id": "42"}
}

kind is the discriminator, exported as failure.Kind. Decoding refuses a document carrying any other kind, so an unrelated JSON body that happens to have a type and a message is not taken for one of these. gRPC carries the same constant as the ErrorInfo domain, which is how an interceptor recognises the detail as ours.

Decoding on the receiving side:

// From raw bytes
e, ok := failure.FromBytes(responseBody)

// From any error (tries type assertion → JSON → wrap)
err = failure.Parse(err)

After decoding, errors.Is(e, ErrNotFound) works provided the sentinel was registered in the current process (i.e. failure.New("resource not found") was called). If the type is unrecognized, the type code string is used for matching.

Transport

An error read off a neighbour's answer arrives with the status of the hop it crossed. That status is the neighbour's answer, not yours: fold it into the cause chain and it travels onward, until some service down the line renders a neighbour's 404 as its own.

AttachTransport puts it in a slot of its own instead. A client attaches what it just crossed:

answer, ok := failure.FromBytes(respBody)
if !ok {
    return failure.AttachTransport(failure.New(resp.Status), httpErr)
}
return failure.AttachTransport(answer, httpErr)

Whoever answers for the error strips it; whoever forwards it leaves it alone:

failure.Transport(err)       // the status it crossed, or nil
failure.DetachTransport(err) // the same error, with every hop's status removed
  • Identity is untouched: Type() and errors.Is answer the error's own code, never the transport's.
  • errors.As still reaches it — Unwrap yields the transport — so a caller that forwards can read the status.
  • DetachTransport is recursive: a status an earlier hop left behind goes with it.
  • Attaching twice replaces. One hop, one status.
  • Attaching to a plain error turns it into a failure, typed by the slug of its message.
  • Attaching captures a stack if the error has none — a sentinel from New, or one decoded off the wire.
  • Transport is not serialized. The wire format above has no field for it, so each hop attaches its own.
Answering for a neighbour

An adapter that answers for its neighbour turns the neighbour's refusal into one of its own:

var priceErrors = failure.NewTranslation(model.ErrInfrastructure, map[error]error{
    failure.New("promo code is not valid"):     model.ErrPromoNotApplicable,
    failure.New("payment method is not found"): nil,
})

resp, err := client.Quote(ctx, req)
if err != nil {
    return 0, priceErrors.Translate(err)
}
  • The table is matched against the error's own type, by slug. The neighbour's status code is not the contract, and neither is a code wrapped under its type.
  • A named code becomes the mapped error, anything else the fallback. Either way the neighbour's message and payload are kept for whoever reads the log, but its type and transport are not: errors.Is answers the caller's error only, and the caller's own status answers.
  • A nil value means the answer is not an error: Translate returns nil and the caller returns its zero value.
  • A nil fallback forwards anything the table does not name: the error comes back as it came, transport included.
  • Two keys with one slug are one key, and which of their values wins is not defined.

API reference

// Creation
func New(format string, args ...any) error
func Wrap(format string, args ...any) error
func Panic(r any) error
func Catch(fn func() error) error

// Inspection
func FromError(err error) (*Error, bool)
func FromBytes(b []byte) (*Error, bool)
func Parse(err error) error

// Transport
func AttachTransport(err error, transport error) error
func Transport(err error) error
func DetachTransport(err error) error

// Translation
func NewTranslation(fallback error, known map[error]error) Translation
func (t Translation) Translate(err error) error

// Error methods
func (e *Error) Type() string
func (e *Error) Payload() map[string]any
func (e *Error) Stack() []Frame
func (e *Error) Error() string
func (e *Error) Unwrap() []error
func (e *Error) Is(target error) bool

// Type codes
func Slugify(s string) string
const Kind = "gorib_app_error_v1"

// Sentinels
var ErrPanic = errors.New("panic")

Documentation

Index

Constants

View Source
const (
	Kind      = "gorib_app_error_v1"
	PanicType = "gorib_panic_v1"
)

Variables

View Source
var (
	ErrPanic = errors.New("panic")
)

Functions

func AttachTransport

func AttachTransport(err error, transport error) error

func Catch

func Catch(fn func() error) (err error)

func DetachTransport

func DetachTransport(err error) error

the transport is the single hop it crossed, and nothing to whoever reads the error next

func New

func New(format string, args ...any) error

func Panic

func Panic(r any) error

func Parse

func Parse(err error) error

func Slugify

func Slugify(s string) string

func Transport

func Transport(err error) error

func Wrap

func Wrap(format string, args ...any) error

Types

type Error

type Error struct {
	// contains filtered or unexported fields
}

func FromBytes

func FromBytes(b []byte) (*Error, bool)

func FromError

func FromError(err error) (*Error, bool)

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

func (e *Error) Is(target error) bool

func (*Error) MarshalJSON

func (e *Error) MarshalJSON() ([]byte, error)

func (*Error) Payload

func (e *Error) Payload() map[string]any

func (*Error) Stack

func (e *Error) Stack() []Frame

func (*Error) Type

func (e *Error) Type() string

func (*Error) UnmarshalJSON

func (e *Error) UnmarshalJSON(data []byte) error

func (*Error) Unwrap

func (e *Error) Unwrap() []error

type Frame

type Frame struct {
	Function string
	File     string
	Line     int
}

type Translation added in v1.4.0

type Translation struct {
	// contains filtered or unexported fields
}

func NewTranslation added in v1.4.0

func NewTranslation(fallback error, known map[error]error) Translation

func (Translation) Translate added in v1.4.0

func (t Translation) Translate(err error) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL