errz

Documentation

Overview

Package errz provides errors and error codes.

Index

• Variables
• func As(err error, target any) bool
• func Is(err error, targets ...error) bool
• func Join(errs ...error) error
• func NewFactory() *factory
• func ReplaceGlobal(f *factory) error
• func Unwrap(err error) error
• type Code
  • func CodeOf(err error) Code
  • func (c *Code) MarshalText() ([]byte, error)
  • func (c *Code) String() string
  • func (c *Code) UnmarshalText(data []byte) error
• type Error
  • func E(args ...any) *Error
  • func F(format string, args ...any) *Error
  • func If(err error, args ...any) *Error
  • func Of(err error) (*Error, bool)
  • func (e *Error) Code() Code
  • func (e *Error) Error() string
  • func (e *Error) IsEmpty() bool
  • func (e *Error) Location() *location
  • func (e *Error) Message() string
  • func (e *Error) Meta() Metadata
  • func (e *Error) StackTrace() []runtime.Frame
  • func (e *Error) String() string
  • func (e *Error) Timestamp() *time.Time
  • func (e *Error) Unwrap() []error
  • func (e *Error) With(key string, value any) *Error
  • func (e *Error) WithLocation() *Error
  • func (e *Error) WithMany(pairs ...any) *Error
  • func (e *Error) WithTime() *Error
  • func (e *Error) WithTrace(skip int) *Error
  • func (e *Error) Wrap(err error) *Error
• type Metadata
  • func (m Metadata) Add(key string, value any) Metadata
  • func (m Metadata) Get(key string) []any
  • func (m Metadata) Has(key string) bool
  • func (m Metadata) String() string

Variables

var (
	// ErrCanceled indicates the operation was canceled.
	ErrCanceled = E(Canceled)
	// ErrUnknown indicates the operation failed for an unknown reason.
	ErrUnknown = E(Unknown)
	// ErrInvalidArgument indicates client supplied an invalid argument.
	ErrInvalidArgument = E(InvalidArgument)
	// ErrDeadlineExceeded indicates deadline expired before operation could complete.
	ErrDeadlineExceeded = E(DeadlineExceeded)
	// ErrNotFound indicates requested entity was not found.
	ErrNotFound = E(NotFound)
	// ErrAlreadyExists indicates client attempted to create an entity that already exists.
	ErrAlreadyExists = E(AlreadyExists)
	// ErrPermissionDenied indicates caller does not have permission.
	ErrPermissionDenied = E(PermissionDenied)
	// ErrResourceExhausted indicates some resource has been exhausted.
	ErrResourceExhausted = E(ResourceExhausted)
	// ErrFailedPrecondition indicates system is not in state required for operation.
	ErrFailedPrecondition = E(FailedPrecondition)
	// ErrAborted indicates operation was aborted by the system.
	ErrAborted = E(Aborted)
	// ErrOutOfRange indicates operation was attempted past the valid range.
	ErrOutOfRange = E(OutOfRange)
	// ErrUnimplemented indicates operation is not implemented.
	ErrUnimplemented = E(Unimplemented)
	// ErrInternal indicates some invariants expected by underlying system have been broken.
	ErrInternal = E(Internal)
	// ErrUnavailable indicates service is currently unavailable.
	ErrUnavailable = E(Unavailable)
	// ErrDataLoss indicates operation resulted in unrecoverable data loss.
	ErrDataLoss = E(DataLoss)
	// ErrUnauthenticated indicates request does not have valid authentication.
	ErrUnauthenticated = E(Unauthenticated)
)

Functions

func As

func As(err error, target any) bool

As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true. Otherwise, it returns false.

func Is

func Is(err error, targets ...error) bool

Is reports whether any error in err's chain matches any of the targets.

func Join

func Join(errs ...error) error

Join returns an error that wraps the given errors. Any nil error values are discarded.

func NewFactory

func NewFactory() *factory

NewFactory creates a new error factory.

func ReplaceGlobal

func ReplaceGlobal(f *factory) error

ReplaceGlobal changes the global error factory.

func Unwrap

func Unwrap(err error) error

Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.

Types

type Code

type Code uint32

Code represents an error code.

const (
	// OK is returned on success.
	OK Code = 0

	// Canceled indicates that the operation was Canceled, typically by the caller.
	Canceled Code = 1

	// Unknown indicates that the operation failed for an Unknown reason.
	Unknown Code = 2

	// InvalidArgument indicates that client supplied an invalid argument.
	InvalidArgument Code = 3

	// DeadlineExceeded indicates that deadline expired before the operation could complete.
	DeadlineExceeded Code = 4

	// NotFound indicates that some requested entity (for example, a file or directory) was not found.
	NotFound Code = 5

	// AlreadyExists indicates that client attempted to create an entity (e.g, a file or directory) that already exists.
	AlreadyExists Code = 6

	// PermissionDenied indicates that the caller doesn't have permission to execute the specified operation.
	PermissionDenied Code = 7

	// ResourceExhausted indicates that some resource has been exhausted.
	// For example, a per-user quota may be exhausted or the entire file system may be full.
	ResourceExhausted Code = 8

	// FailedPrecondition indicates that the system is not in a state required for the operation's execution.
	FailedPrecondition Code = 9

	// Aborted indicates that operation was Aborted by the system,
	// usually because of a concurrency issue such as a sequencer check failure or transaction abort.
	Aborted Code = 10

	// OutOfRange indicates that the operation was attempted past the valid range (for example, seeking past end-of-file).
	OutOfRange Code = 11

	// Unimplemented indicates that the operation isn't implemented, supported, or enabled in this service.
	Unimplemented Code = 12

	// Internal indicates that some invariants expected by the underlying system have been broken.
	// This code is reserved for serious errors.
	Internal Code = 13

	// Unavailable indicates that the service is currently Unavailable.
	// This is usually temporary, so clients can back off and retry idempotent operations.
	Unavailable Code = 14

	// DataLoss indicates that the operation has resulted in unrecoverable data loss or corruption.
	DataLoss Code = 15

	// Unauthenticated indicates that the request does not have valid authentication credentials for the operation.
	Unauthenticated Code = 16
)

func CodeOf

func CodeOf(err error) Code

CodeOf returns the error's status code if it is or wraps an *Error and Unknown otherwise.

func (*Code) MarshalText

func (c *Code) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (*Code) String

func (c *Code) String() string

func (*Code) UnmarshalText

func (c *Code) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type Error

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

Error represents a structured error.

func E

func E(args ...any) *Error

E creates an error from the given arguments.

func F

func F(format string, args ...any) *Error

F creates an error with a formatted message.

func If

func If(err error, args ...any) *Error

If creates an error from the given arguments if err is not nil.

func Of

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

Of returns the error as an *Error and whether the conversion succeeded.

func (*Error) Code

func (e *Error) Code() Code

Code returns the error's code.

func (*Error) Error

func (e *Error) Error() string

Error implements the error interface.

func (*Error) IsEmpty

func (e *Error) IsEmpty() bool

IsEmpty reports whether the error contains no information.

func (*Error) Location

func (e *Error) Location() *location

Location returns the caller's location when the error was created.

func (*Error) Message

func (e *Error) Message() string

Message returns the error's message.

func (*Error) Meta

func (e *Error) Meta() Metadata

Meta returns the error's metadata.

func (*Error) StackTrace

func (e *Error) StackTrace() []runtime.Frame

StackTrace returns the error's stack trace.

func (*Error) String

func (e *Error) String() string

String returns a string representation of the error.

func (*Error) Timestamp

func (e *Error) Timestamp() *time.Time

Timestamp returns the time the error was created.

func (*Error) Unwrap

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

Unwrap returns the underlying errors.

func (*Error) With

func (e *Error) With(key string, value any) *Error

With adds a metadata key-value pair to the error.

func (*Error) WithLocation

func (e *Error) WithLocation() *Error

WithLocation adds the caller's location to the error.

func (*Error) WithMany

func (e *Error) WithMany(pairs ...any) *Error

WithMany adds multiple metadata key-value pairs to the error.

func (*Error) WithTime

func (e *Error) WithTime() *Error

WithTime adds the current time to the error.

func (*Error) WithTrace

func (e *Error) WithTrace(skip int) *Error

WithTrace adds a stack trace to the error, skipping the specified number of frames.

func (*Error) Wrap

func (e *Error) Wrap(err error) *Error

Wrap appends an error to the error's chain.

type Metadata

type Metadata []detail

Metadata is a collection of metadata details.

func (Metadata) Add

func (m Metadata) Add(key string, value any) Metadata

Add adds a key-value pair to the metadata.

func (Metadata) Get

func (m Metadata) Get(key string) []any

Get returns all values associated with the given key.

func (Metadata) Has

func (m Metadata) Has(key string) bool

Has reports whether the metadata contains the given key.

func (Metadata) String

func (m Metadata) String() string

String returns a string representation of the metadata.