serrors

Documentation

Overview

Package serrors provides enhanced errors. Errors created with serrors can have additional log context in form of key value pairs. The package provides wrapping methods. The returned errors support new Is and As error functionality. For any returned error err, errors.Is(err, err) is always true, for any err which wraps err2 or has err2 as msg, errors.Is(err, err2) is always true, for any other combination of errors errors.Is(x,y) can be assumed to return false.

Index

• func FmtError(e error) string
• func IsTemporary(err error) bool
• func IsTimeout(err error) bool
• func New(msg string, logCtx ...interface{}) error
• func WithCtx(err error, logCtx ...interface{}) error
• func Wrap(msg, cause error, logCtx ...interface{}) error
• func WrapStr(msg string, cause error, logCtx ...interface{}) error
• type List
  • func (e List) ToError() error
• type Wrapper

Examples

• New
• WithCtx
• Wrap
• WrapStr

Functions

func FmtError

func FmtError(e error) string

FmtError formats the error for logging. It walks through all wrapped errors, putting each on a new line, and indenting multi-line errors.

func IsTemporary

func IsTemporary(err error) bool

IsTemporary returns whether err is or is caused by a temporary error.

func IsTimeout

func IsTimeout(err error) bool

IsTimeout returns whether err is or is caused by a timeout error.

func New

func New(msg string, logCtx ...interface{}) error

New creates a new error with the given message and context.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/scionproto/scion/go/lib/serrors"
)

func main() {
	err1 := serrors.New("errtxt")
	err2 := serrors.New("errtxt")

	// Self equality always works:
	fmt.Println(errors.Is(err1, err1))
	fmt.Println(errors.Is(err2, err2))
	// On the other hand different errors with same text should not be "equal".
	// That is to prevent that errors with same message in different packages
	// with same text are seen as the same thing:
	fmt.Println(errors.Is(err1, err2))
}

Output:

true
true
false

func WithCtx

func WithCtx(err error, logCtx ...interface{}) error

WithCtx returns an error that is the same as the given error but contains the additional context. The additional context is printed in the Error method. The returned error implements Is and Is(err) returns true.

Example

package main

import (
	"fmt"

	"github.com/scionproto/scion/go/lib/serrors"
)

func main() {
	// ErrBadL4 is an error defined at package scope.
	var ErrBadL4 = serrors.New("Unsupported L4 protocol")
	addedCtx := serrors.WithCtx(ErrBadL4, "type", "SCTP")

	fmt.Println(addedCtx)
}

Output:

Unsupported L4 protocol type="SCTP"

func Wrap

func Wrap(msg, cause error, logCtx ...interface{}) error

Wrap wraps the cause with the msg error and adds context to the resulting error. The returned error implements Is and Is(msg) and Is(cause) returns true.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/scionproto/scion/go/lib/serrors"
)

func main() {
	// ErrNoSpace is an error defined at package scope.
	var ErrNoSpace = serrors.New("no space")
	// ErrDB is an error defined at package scope.
	var ErrDB = serrors.New("db")
	wrapped := serrors.Wrap(ErrDB, ErrNoSpace, "ctx", 1)

	// Now we can identify specific errors:
	fmt.Println(errors.Is(wrapped, ErrNoSpace))
	// But we can also identify the broader error class ErrDB:
	fmt.Println(errors.Is(wrapped, ErrDB))

	fmt.Printf("\n%v", wrapped)
}

Output:

true
true

db ctx="1"
    no space

func WrapStr

func WrapStr(msg string, cause error, logCtx ...interface{}) error

WrapStr wraps the cause with an error that has msg in the error message and adds the additional context. The returned error implements Is and Is(cause) returns true.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/scionproto/scion/go/lib/serrors"
)

func main() {
	// ErrNoSpace is an error defined at package scope.
	var ErrNoSpace = serrors.New("no space")
	wrappedErr := serrors.WrapStr("wrap with more context", ErrNoSpace, "ctx", 1)

	fmt.Println(errors.Is(wrappedErr, ErrNoSpace))
	fmt.Printf("\n%v", wrappedErr)
}

Output:

true

wrap with more context ctx="1"
    no space

Types

type List

type List []error

List is a slice of errors

func (List) ToError

func (e List) ToError() error

ToError returns the object as error interface implementation.

type Wrapper

type Wrapper interface {
	error
	Unwrap() error
	// TopError should return the top level error without the wrapped ones.
	TopError() string
}

Wrapper allows recursing into nested errrors.