errors

Documentation

Overview

Package errors provides error creation and matching for all wallet systems. It is imported as errors and takes over the roll of the standard library errors package.

Index

• Variables
• func As(err error, target any) bool
• func E(args ...any) error
• func Errorf(format string, args ...any) error
• func Is(err, target error) bool
• func Join(errs ...error) error
• func New(text string) error
• func Stacks(err error) [][]byte
• func WithStack(args ...any) error
• type Error
  • func (e *Error) As(target any) bool
  • func (e *Error) Error() string
  • func (e *Error) Is(target error) bool
  • func (e *Error) Unwrap() error
• type Kind
  • func (k Kind) As(target any) bool
  • func (k Kind) Error() string
  • func (k Kind) String() string
• type Op
  • func Opf(format string, a ...any) Op

Variables

var Separator = ":\n\t"

Separator is inserted between nested errors when formatting as strings. The default separator produces easily readable multiline errors. Separator may be modified at init time to create error strings appropriate for logging errors on a single line.

Functions

func As

func As(err error, target any) bool

As attempts to assign the error pointed to by target with the first error in err's error chain with a compatible type. Returns true if target is assigned.

func E

func E(args ...any) error

E creates an *Error from one or more arguments.

Each argument type is inspected when constructing the error. If multiple args of similar type are passed, the final arg is recorded. The following types are recognized:

errors.Op
    The operation, method, or RPC which was invoked.
errors.Kind
    The class of error.
string
    Description of the error condition.  String types populate the
    Err field and overwrite, and are overwritten by, other arguments
    which implement the error interface.
error
    The underlying error.  If the error is an *Error, the Op and Kind
    will be promoted to the newly created error if not set to another
    value in the args.

If another *Error is passed as an argument and no other arguments differ from the wrapped error, instead of wrapping the error, the errors are collapsed and fields of the passed *Error are promoted to the returned error.

Panics if no arguments are passed.

func Errorf

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

Errorf wraps fmt.Errorf as a convenience for creating formatted error strings.

func Is

func Is(err, target error) bool

Is returns whether err equals or wraps target.

func Join

func Join(errs ...error) error

Join calls the standard library's errors.Join.

func New

func New(text string) error

New creates a simple error from a string. New is identical to "errors".New from the standard library.

func Stacks

func Stacks(err error) [][]byte

Stacks extracts all stacktraces from err, sorted from top-most to bottom-most error.

func WithStack

func WithStack(args ...any) error

WithStack is identical to E but includes a stacktrace with the error. Stack traces do not appear in formatted error strings and are not compared when matching errors. Stack traces are extracted from errors using Stacks.

Types

type Error

type Error struct {
	Op   Op
	Kind Kind
	Err  error
	// contains filtered or unexported fields
}

Error describes an error condition raised within the wallet process. Errors may optionally provide details regarding the operation and class of error for assistance in debugging and runtime matching of errors.

func (*Error) As

func (e *Error) As(target any) bool

As implements the interface to work with the standard library's errors.As. If target points to an *Error (i.e. target has type **Error), target is assigned e and As returns true. If target points to a Kind and e's Kind is not Other, target is assigned the kind and As returns true. Else, target is not assinged and As returns false.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Is

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

Is implements the interface to work with the standard library's errors.Is. If target is an *Error, Is returns true if every top-level and wrapped non-zero fields of target are equal to the same fields of e. If target is a Kind, Is returns true if the Kinds match and are nonzero. Else, Is returns false.

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap returns the underlying wrapped error if it is not nil. Otherwise, if the Kind is not Other, Unwrap returns the Kind. Else, it returns nil.

type Kind

type Kind int

Kind describes the class of error.

const (
	Other               Kind = iota // Unclassified error -- does not appear in error strings
	Bug                             // Error is known to be a result of our bug
	Invalid                         // Invalid operation
	Permission                      // Permission denied
	IO                              // I/O error
	Exist                           // Item already exists
	NotExist                        // Item does not exist
	Encoding                        // Invalid encoding
	Crypto                          // Encryption or decryption error
	Locked                          // Wallet is locked
	Passphrase                      // Invalid passphrase
	Seed                            // Invalid seed
	WatchingOnly                    // Missing private keys
	InsufficientBalance             // Insufficient balance to create transaction (perhaps due to UTXO selection requirements)
	ScriptFailure                   // Transaction scripts do not execute (usually due to missing sigs)
	Policy                          // Transaction rejected by wallet policy
	Consensus                       // Consensus violation
	DoubleSpend                     // Transaction is a double spend
	Protocol                        // Protocol violation
	NoPeers                         // Decred network is unreachable due to lack of peers or dcrd RPC connections
	Deployment                      // Inactive consensus deployment
)

Error kinds.

func (Kind) As

func (k Kind) As(target any) bool

As implements the interface to work with the standard library's errors.As. If k is Other, this always returns false and target is not assigned. If target points to an *Error (i.e. target has type **Error), target is assigned an *Error using k as its Kind. If target points to a Kind, target is assigned the kind and As returns true. Else, target is not assinged and As returns false.

func (Kind) Error

func (k Kind) Error() string

func (Kind) String

func (k Kind) String() string

type Op

type Op string

Op describes the operation, method, or RPC in which an error condition was raised.

func Opf

func Opf(format string, a ...any) Op

Opf returns a formatted Op.