go.bigb.es/auxilia

v0.2.0
Doc Versions Source

Documentation

Package culpa provides structured error handling with typed details, stacktrace capture, and chain traversal.

Index

Functions

f func AllDetails

src 
func AllDetails(err error) []any

AllDetails returns all details from the error tree as a flat list.

f func As

src 
func As(err error, target any) bool

As finds the first error in err's tree that matches target and sets target to that error value. It is a convenience re-export of errors.As.

f func AsType

src 
func AsType[E error](err error) (E, bool)

AsType finds the first error in err's tree that matches type E. It is a convenience re-export of errors.AsType.

f func Cause

src 
func Cause(err error) error

Cause returns the innermost (root-cause) error by following the first unwrap path. For joined errors, it follows the first child.

f func Errorf

src 
func Errorf(format string, args ...any) error

Errorf creates a new error with a formatted message.

f func Find

src 
func Find(err error, fn func(err error) bool) error

Find returns the first error in the tree for which fn returns true (pre-order, depth-first). Returns nil if no error matches.

f func FindDetail

src 
func FindDetail(err error, dst any) bool

FindDetail finds the first detail of type T in the error tree (pre-order, depth-first) and writes it into dst. dst must be a non-nil pointer. Returns true if found.

f func FindDetails

src 
func FindDetails[T any](err error) []T

FindDetails finds all details of type T in the error tree.

f func Is

src 
func Is(err, target error) bool

Is reports whether any error in err's tree matches target. It is a convenience re-export of errors.Is.

f func IsCanceled

src 
func IsCanceled(err error) bool

IsCanceled reports whether the error is marked as canceled.

f func IsDeadline

src 
func IsDeadline(err error) bool

IsDeadline reports whether the error is marked as deadline exceeded.

f func IsTemporary

src 
func IsTemporary(err error) bool

IsTemporary reports whether the error is marked as temporary.

f func IsTimeout

src 
func IsTimeout(err error) bool

IsTimeout reports whether the error is marked as a timeout.

f func Join

src 
func Join(errs ...error) error

Join combines multiple errors into one. Nil errors are filtered out. Returns nil if no non-nil errors are provided. Unlike errors.Join, the returned error supports culpa formatting (fmt.Formatter, slog.LogValuer) and detail traversal.

f func New

src 
func New(msg string) error

New creates a new error with a message.

f func NewIllegalState

src 
func NewIllegalState() error

NewIllegalState creates an IllegalState error with a captured stacktrace.

f func NewIllegalValue

src 
func NewIllegalValue() error

NewIllegalValue creates an IllegalValue error with a captured stacktrace.

f func NewImpossible

src 
func NewImpossible() error

NewImpossible creates an Impossible error with a captured stacktrace.

f func NewNotImplemented

src 
func NewNotImplemented() error

NewNotImplemented creates a NotImplemented error with a captured stacktrace.

f func NewUnsupported

src 
func NewUnsupported() error

NewUnsupported creates an Unsupported error with a captured stacktrace.

f func Unwrap

src 
func Unwrap(err error) error

Unwrap returns the result of calling the Unwrap method on err, if err's type implements Unwrap. It is a convenience re-export of errors.Unwrap.

f func Walk

src 
func Walk(err error, fn func(err error) bool)

Walk calls fn for each error in the tree (pre-order, depth-first). Handles both single-unwrap and multi-unwrap (joined) errors. Stops early if fn returns false.

f func WithCancel

src 
func WithCancel(err error) error

WithCancel marks the error as a cancellation.

f func WithCode

src 
func WithCode(err error, code any) error

WithCode attaches a CodeDetail.

f func WithContext

src 
func WithContext(err error, ctx context.Context, keys ...any) error

WithContext attaches a ContextDetail with values extracted from ctx for the given keys.

f func WithDeadline

src 
func WithDeadline(err error) error

WithDeadline marks the error as a deadline exceeded.

f func WithDetail

src 
func WithDetail(err error, detail any) error

WithDetail attaches a single detail to the error. Returns nil if err is nil.

f func WithDetails

src 
func WithDetails(err error, details ...any) error

WithDetails attaches multiple details to the error in a single layer. Returns nil if err is nil.

f func WithHint

src 
func WithHint(err error, hint string) error

WithHint attaches a HintDetail.

f func WithIn

src 
func WithIn(err error, category string) error

WithIn attaches an InDetail.

f func WithOwner

src 
func WithOwner(err error, owner string) error

WithOwner attaches an OwnerDetail.

f func WithPublic

src 
func WithPublic(err error, msg string) error

WithPublic attaches a PublicDetail.

f func WithRequest

src 
func WithRequest(err error, req *http.Request, withBody bool) error

WithRequest attaches a RequestDetail from an HTTP request.

f func WithResponse

src 
func WithResponse(err error, res *http.Response, withBody bool) error

WithResponse attaches a ResponseDetail from an HTTP response.

f func WithTags

src 
func WithTags(err error, tags ...string) error

WithTags attaches a TagsDetail.

f func WithTemporary

src 
func WithTemporary(err error) error

WithTemporary marks the error as temporary.

f func WithTime

src 
func WithTime(err error, t time.Time) error

WithTime attaches a TimeDetail.

f func WithTimeout

src 
func WithTimeout(err error) error

WithTimeout marks the error as a timeout.

f func WithTrace

src 
func WithTrace(err error, traceID string) error

WithTrace attaches a TraceDetail (distributed trace ID).

f func Wrap

src 
func Wrap(err error, msg string) error

Wrap wraps an existing error with a message and captures a stacktrace. Returns nil if err is nil.

f func WrapContext

src 
func WrapContext(ctx context.Context, msg string) error

WrapContext wraps ctx.Err() with a message, auto-applying the appropriate marker (CancelDetail or DeadlineDetail). If context.Cause returns a different error than ctx.Err(), it is included in the chain. Returns nil if ctx.Err() is nil.

f func Wrapf

src 
func Wrapf(err error, format string, args ...any) error

Wrapf wraps an existing error with a formatted message and captures a stacktrace. Returns nil if err is nil.

Types

T type CancelDetail

src 
type CancelDetail struct{}

CancelDetail marks an error as a cancellation.

m func (CancelDetail) LogValue

src 
func (CancelDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type CodeDetail

src 
type CodeDetail struct{ Code any }

CodeDetail carries a machine-readable error code or slug.

m func (CodeDetail) LogValue

src 
func (d CodeDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type ContextDetail

src 
type ContextDetail struct{ Values map[any]any }

ContextDetail carries key-value pairs extracted from context.

m func (ContextDetail) LogValue

src 
func (d ContextDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type DeadlineDetail

src 
type DeadlineDetail struct{}

DeadlineDetail marks an error as a deadline exceeded.

m func (DeadlineDetail) LogValue

src 
func (DeadlineDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type HintDetail

src 
type HintDetail struct{ Hint string }

HintDetail carries a debugging hint.

m func (HintDetail) LogValue

src 
func (d HintDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type IllegalState

src 
type IllegalState struct{}

IllegalState signals an operation invoked in a wrong state.

m func (IllegalState) Error

src 
func (IllegalState) Error() string

m func (IllegalState) LogValue

src 
func (IllegalState) LogValue() slog.Value

T type IllegalValue

src 
type IllegalValue struct{}

IllegalValue signals a value that failed a precondition or invariant.

m func (IllegalValue) Error

src 
func (IllegalValue) Error() string

m func (IllegalValue) LogValue

src 
func (IllegalValue) LogValue() slog.Value

T type Impossible

src 
type Impossible struct{}

Impossible signals a code path that should never be reached (bug).

m func (Impossible) Error

src 
func (Impossible) Error() string

m func (Impossible) LogValue

src 
func (Impossible) LogValue() slog.Value

T type InDetail

src 
type InDetail struct{ Category string }

InDetail carries a feature category or domain.

m func (InDetail) LogValue

src 
func (d InDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type MergeStrategy

src 
type MergeStrategy int

MergeStrategy defines how duplicate detail types are resolved when the same type appears in multiple layers of the error chain. 

const (
	// MergeOverwrite — outermost (latest) value wins. Default.
	MergeOverwrite MergeStrategy = iota
	// MergeCombine — values from all layers are collected into a slice.
	MergeCombine
)

T type MergeStrategyProvider

src 
type MergeStrategyProvider interface {
	MergeStrategy() MergeStrategy
}

MergeStrategyProvider is implemented by detail types that declare a non-default merge strategy.

T type NotImplemented

src 
type NotImplemented struct{}

NotImplemented signals an operation that exists but has no implementation yet.

m func (NotImplemented) Error

src 
func (NotImplemented) Error() string

m func (NotImplemented) LogValue

src 
func (NotImplemented) LogValue() slog.Value

T type OwnerDetail

src 
type OwnerDetail struct{ Owner string }

OwnerDetail carries the name or email of the responsible team.

m func (OwnerDetail) LogValue

src 
func (d OwnerDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type PublicDetail

src 
type PublicDetail struct{ Message string }

PublicDetail carries a message safe to show to end users.

m func (PublicDetail) LogValue

src 
func (d PublicDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type RequestDetail

src 
type RequestDetail struct {
	Method string
	URL    string
	Header http.Header
	Body   []byte
}

RequestDetail carries an HTTP request snapshot.

m func (RequestDetail) LogValue

src 
func (d RequestDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type ResponseDetail

src 
type ResponseDetail struct {
	StatusCode int
	Header     http.Header
	Body       []byte
}

ResponseDetail carries an HTTP response snapshot.

m func (ResponseDetail) LogValue

src 
func (d ResponseDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type StacktraceDetail

src 
type StacktraceDetail struct{ Trace stacktrace.Trace }

StacktraceDetail carries a captured stack trace. It uses MergeCombine so that traces from multiple wrap layers accumulate.

m func (StacktraceDetail) MergeStrategy

src 
func (StacktraceDetail) MergeStrategy() MergeStrategy

MergeStrategy implements MergeStrategyProvider.

T type TagsDetail

src 
type TagsDetail struct{ Tags []string }

TagsDetail carries freeform string tags. Uses MergeCombine so tags accumulate across layers.

m func (TagsDetail) LogValue

src 
func (d TagsDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

m func (TagsDetail) MergeStrategy

src 
func (TagsDetail) MergeStrategy() MergeStrategy

MergeStrategy implements MergeStrategyProvider.

T type TemporaryDetail

src 
type TemporaryDetail struct{}

TemporaryDetail marks an error as temporary (retryable).

m func (TemporaryDetail) LogValue

src 
func (TemporaryDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type TimeDetail

src 
type TimeDetail struct{ Time time.Time }

TimeDetail carries a timestamp associated with the error.

m func (TimeDetail) LogValue

src 
func (d TimeDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type TimeoutDetail

src 
type TimeoutDetail struct{}

TimeoutDetail marks an error as a timeout.

m func (TimeoutDetail) LogValue

src 
func (TimeoutDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type TraceDetail

src 
type TraceDetail struct{ TraceID string }

TraceDetail carries a distributed trace ID for correlation.

m func (TraceDetail) LogValue

src 
func (d TraceDetail) LogValue() slog.Value

LogValue implements slog.LogValuer.

T type Unsupported

src 
type Unsupported struct{}

Unsupported signals an operation intentionally not supported.

m func (Unsupported) Error

src 
func (Unsupported) Error() string

m func (Unsupported) LogValue

src 
func (Unsupported) LogValue() slog.Value

Source Files