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

Examples

• GetClass
• GetClass (Nil)
• WithOnlyMoreSevere
• WithOnlyUnknown
• WrapAs

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.

Example

package main

import (
	"errors"
	"log/slog"
	"os"

	"github.com/wood-jp/xerrors"
	"github.com/wood-jp/xerrors/errclass"
)

func newLogger() *slog.Logger {
	return slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			if a.Key == slog.TimeKey && len(groups) == 0 {
				return slog.Attr{}
			}
			return a
		},
	}))
}

func main() {
	err := errclass.WrapAs(errors.New("connection timed out"), errclass.Transient)
	newLogger().Error("operation failed", xerrors.Log(err))
}

Output:
{"level":"ERROR","msg":"operation failed","error":{"error":"connection timed out","error_detail":{"class":"transient"}}}

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.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/wood-jp/xerrors/errclass"
)

func main() {
	err := errors.New("disk full")
	err = errclass.WrapAs(err, errclass.Persistent)
	fmt.Println(errclass.GetClass(err))
}

Output:
persistent

Example (Nil)

package main

import (
	"fmt"

	"github.com/wood-jp/xerrors/errclass"
)

func main() {
	fmt.Println(errclass.GetClass(nil))
}

Output:
nil

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.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/wood-jp/xerrors/errclass"
)

func main() {
	err := errors.New("failure")
	err = errclass.WrapAs(err, errclass.Persistent)
	// Transient is less severe than Persistent, so the class is unchanged.
	err = errclass.WrapAs(err, errclass.Transient, errclass.WithOnlyMoreSevere())
	fmt.Println(errclass.GetClass(err))
}

Output:
persistent

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.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/wood-jp/xerrors/errclass"
)

func main() {
	err := errors.New("failure")
	err = errclass.WrapAs(err, errclass.Transient)
	// Error already has a class, so WithOnlyUnknown leaves it unchanged.
	err = errclass.WrapAs(err, errclass.Persistent, errclass.WithOnlyUnknown())
	fmt.Println(errclass.GetClass(err))
}

Output:
transient

func WithUnrestricted

func WithUnrestricted() WrapOption

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