errclass

Documentation

Overview

Package errclass provides error classification by severity level. It wraps errors with a Class using xerrors.Extend, enabling downstream callers to inspect and act on error severity.

Index

• func WrapAs(err error, class Class, opts ...WrapOption) error
• type Class
  • func GetClass(err error) Class
  • func (c Class) LogValue() slog.Value
  • func (c Class) String() string
• type WrapOption
  • func WithOnlyMoreSevere() WrapOption
  • func WithOnlyUnknown() WrapOption
  • func WithUnrestricted() WrapOption

Functions

func WrapAs

func WrapAs(err error, class Class, opts ...WrapOption) error

WrapAs wraps err with the given Class. If err is nil, it returns nil. By default the class is applied unconditionally. Use WrapOption values such as WithOnlyUnknown or WithOnlyMoreSevere to restrict when wrapping occurs.

Types

type Class

type Class int

Class represents the severity classification of an error. Higher values indicate more severe errors.

const (
	// Nil indicates a nil error (no error). It has value -1.
	Nil Class = iota - 1
	// Unknown is the zero value, used for errors that have not been classified.
	Unknown
	// Transient indicates a temporary error that may succeed on retry.
	Transient
	// Persistent indicates a permanent error that will not resolve on retry.
	Persistent
	// Panic indicates an error resulting from a recovered panic.
	Panic
)

func GetClass

func GetClass(err error) Class

GetClass extracts the Class from err. It returns Nil if err is nil, and Unknown if err does not carry a class.

func (Class) LogValue

func (c Class) LogValue() slog.Value

LogValue implements slog.LogValuer, returning the class name as a grouped slog value.

func (Class) String

func (c Class) String() string

String returns the lowercase name of the Class. Unrecognized values return "unknown".

type WrapOption

type WrapOption func(opt *wrapOptions)

WrapOption configures the behavior of WrapAs.

func WithOnlyMoreSevere

func WithOnlyMoreSevere() WrapOption

WithOnlyMoreSevere restricts WrapAs to only wrap errors when the provided class is strictly more severe than the error's current class. Otherwise the error is returned unchanged.

func WithOnlyUnknown

func WithOnlyUnknown() WrapOption

WithOnlyUnknown restricts WrapAs to only wrap errors whose current class is Unknown. Errors that already have a class are returned unchanged.

func WithUnrestricted

func WithUnrestricted() WrapOption

WithUnrestricted allows WrapAs to wrap the error unconditionally. This is the default behavior when no option is provided.