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 IsTemporary(err error) bool
• func IsTimeout(err error) bool
• func New(msg string, errCtx ...interface{}) error
• func WithCtx(err error, errCtx ...interface{}) error
• func Wrap(msg, cause error, errCtx ...interface{}) error
• func WrapStr(msg string, cause error, errCtx ...interface{}) error
• type Frame
  • func (f Frame) Format(s fmt.State, verb rune)
  • func (f Frame) MarshalText() ([]byte, error)
• type List
  • func (e List) Error() string
  • func (e List) MarshalLogArray(ae zapcore.ArrayEncoder) error
  • func (e List) ToError() error
• type StackTrace
  • func (st StackTrace) Format(s fmt.State, verb rune)

Examples

• New
• WithCtx
• Wrap
• WrapStr

Functions

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, errCtx ...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, errCtx ...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. Deprecated: use WrapStr or New instead.

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, errCtx ...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. Deprecated: use WrapStr instead.

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, errCtx ...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 Frame

type Frame uintptr

Frame represents a program counter inside a stack frame. For historical reasons if Frame is interpreted as a uintptr its value represents the program counter + 1.

func (Frame) Format

func (f Frame) Format(s fmt.State, verb rune)

Format formats the frame according to the fmt.Formatter interface.

%s    source file
%d    source line
%n    function name
%v    equivalent to %s:%d

Format accepts flags that alter the printing of some verbs, as follows:

%+s   function name and path of source file relative to the compile time
      GOPATH separated by \n\t (<funcname>\n\t<path>)
%+v   equivalent to %+s:%d

func (Frame) MarshalText

func (f Frame) MarshalText() ([]byte, error)

MarshalText formats a stacktrace Frame as a text string. The output is the same as that of fmt.Sprintf("%+v", f), but without newlines or tabs.

type List

type List []error

List is a slice of errors.

func (List) Error

func (e List) Error() string

Error implements the error interface.

func (List) MarshalLogArray

func (e List) MarshalLogArray(ae zapcore.ArrayEncoder) error

MarshalLogArray implements zapcore.ArrayMarshaller for nicer logging format of error lists.

func (List) ToError

func (e List) ToError() error

ToError returns the object as error interface implementation.

type StackTrace

type StackTrace []Frame

StackTrace is stack of Frames from innermost (newest) to outermost (oldest).

func (StackTrace) Format

func (st StackTrace) Format(s fmt.State, verb rune)

Format formats the stack of Frames according to the fmt.Formatter interface.

%s	lists source files for each Frame in the stack
%v	lists the source file and line number for each Frame in the stack

Format accepts flags that alter the printing of some verbs, as follows:

%+v   Prints filename, function, and line number for each Frame in the stack.