ferrors

Documentation

Overview

Package ferrors provides simple error handling primitives.

The traditional error handling idiom in Go is roughly akin to

if err != nil {
        return err
}

which when applied recursively up the call stack results in error reports without context or debugging information. The ferrors package allows programmers to add context to the failure path in their code in a way that does not destroy the original value of the error.

It also provides some useful error primitives to reduce unnecessary burden and duplicacy from code.

Index

• func Cause(err error) error
• func Wrap(err error, msg string) error
• type ErrorCode
  • func Code(err error) ErrorCode
  • func (e ErrorCode) String() string
• type ErrorDetail
  • func (*ErrorDetail) ProtoMessage()
  • func (e *ErrorDetail) ProtoReflect() protoreflect.Message
  • func (e *ErrorDetail) Reset()
  • func (e *ErrorDetail) String() string
• type Ferror
  • func New(message string) Ferror
  • func NewAlreadyExistsError(msg string, fields ...Field) Ferror
  • func NewInternalError(msg string) Ferror
  • func NewInvalidArgumentError(msg string, fields ...Field) Ferror
  • func NewNotFoundError(msg string) Ferror
  • func NewOutOfRangeError(msg string, fields ...Field) Ferror
  • func NewPermissionDeniedError(msg string) Ferror
  • func NewUnauthenticatedError(msg string) Ferror
  • func Newf(format string, args ...interface{}) Ferror
  • func WithCode(code ErrorCode, message string, detail ...*ErrorDetail) Ferror
  • func WithStack(err error) Ferror
  • func Wrapf(err error, format string, args ...interface{}) Ferror
• type Field
• type Frame
  • func (f Frame) Format(s fmt.State, verb rune)
  • func (f Frame) MarshalText() ([]byte, error)
• type StackTrace
  • func (st StackTrace) Format(s fmt.State, verb rune)

Functions

func Cause

func Cause(err error) error

Cause returns the underlying cause of the error, if possible. An error value has a cause if it implements the following interface:

type causer interface {
       Cause() error
}

If the error does not implement Cause, the original error will be returned. If the error is nil, nil will be returned without further investigation.

func Wrap

func Wrap(err error, msg string) error

Wrap wraps an error with custom message. It also records the stack trace at the point it was called.

Types

type ErrorCode

type ErrorCode uint32

ErrorCode is internal domain error codes

const (
	// Unknown error. Default error type if no error type is provided
	Unknown ErrorCode = ErrorCode(codes.Unknown)

	// InvalidArgument indicates client specified an invalid argument.
	// It indicates arguments that are problematic regardless of the state of the
	// system
	// (e.g., a malformed file name).
	InvalidArgument ErrorCode = ErrorCode(codes.InvalidArgument)

	// NotFound means some requested entity (e.g., file or directory) was
	// not found.
	NotFound ErrorCode = ErrorCode(codes.NotFound)

	// AlreadyExists means an attempt to create an entity failed because one
	// already exists.
	AlreadyExists ErrorCode = ErrorCode(codes.AlreadyExists)

	// PermissionDenied indicates the caller does not have permission to
	// execute the specified operation.
	PermissionDenied ErrorCode = ErrorCode(codes.PermissionDenied)

	// FailedPrecondition indicates operation was rejected because the
	// system is not in a state required for the operation's execution.
	// For example, directory to be deleted may be non-empty, an rmdir
	// operation is applied to a non-directory, etc.
	FailedPrecondition ErrorCode = ErrorCode(codes.FailedPrecondition)

	// OutOfRange means operation was attempted past the valid range.
	// E.g., seeking or reading past end of file.
	//
	// Unlike InvalidArgument, this error indicates a problem that may
	// be fixed if the system state changes. For example, a 32-bit file
	// system will generate InvalidArgument if asked to read at an
	// offset that is not in the range [0,2^32-1], but it will generate
	// OutOfRange if asked to read from an offset past the current
	// file size.
	OutOfRange ErrorCode = ErrorCode(codes.OutOfRange)

	// Unimplemented indicates operation is not implemented or not
	// supported/enabled in this service.
	Unimplemented ErrorCode = ErrorCode(codes.Unimplemented)

	// Internal errors. Means some invariants expected by underlying
	// system has been broken. If you see one of these errors,
	// something is very broken.
	Internal ErrorCode = ErrorCode(codes.Internal)

	// Unavailable indicates the service is currently unavailable.
	// This is a most likely a transient condition and may be corrected
	// by retrying with a backoff. Note that it is not always safe to retry
	// non-idempotent operations.
	Unavailable ErrorCode = ErrorCode(codes.Unavailable)

	// Unauthenticated indicates the request does not have valid
	// authentication credentials for the operation.
	Unauthenticated ErrorCode = ErrorCode(codes.Unauthenticated)
)

func Code

func Code(err error) ErrorCode

Code returns error code

func (ErrorCode) String

func (e ErrorCode) String() string

String returns the string representation of the error code

type ErrorDetail

type ErrorDetail errdetails.ErrorInfo

ErrorDetail describes the cause of the error with structured details.

Example of an error when creating an account with email, when email already exists. is not enabled:

{ "reason": "EMAIL_ALREADY_EXISTS"
  "metadata": {
    "email": "email is already in use"
  }
}

This response indicates that the pubsub.googleapis.com API is not enabled.

Example of an error that is returned when attempting to create a Spanner instance in a region that is out of stock:

{ "reason": "MARKET_CLOSED"
  "metadata": {
    "info": "Market is closed."
  }
}

func (*ErrorDetail) ProtoMessage

func (*ErrorDetail) ProtoMessage()

ProtoMessage implements proto Message interface.

func (*ErrorDetail) ProtoReflect

func (e *ErrorDetail) ProtoReflect() protoreflect.Message

ProtoReflect returns a reflective view of message.

func (*ErrorDetail) Reset

func (e *ErrorDetail) Reset()

Reset resets the ErrorDetail.

func (*ErrorDetail) String

func (e *ErrorDetail) String() string

String implements the fmt.Stringer interface.

type Ferror

type Ferror interface {
	// Code returns the error code.
	Code() ErrorCode
	// WithDetail attaches an error detail to Ferror.
	WithDetail(*ErrorDetail) Ferror

	error
}

Ferror is an error that contains error code, details, and stack traces.

func New

func New(message string) Ferror

New returns an error with the supplied message. It also records the stack trace at the point it was called.

func NewAlreadyExistsError

func NewAlreadyExistsError(msg string, fields ...Field) Ferror

NewAlreadyExistsError returns an already exists error It also records the stack trace at the point it was called.

func NewInternalError

func NewInternalError(msg string) Ferror

NewInternalError returns an internal error. It also records the stack trace at the point it was called.

func NewInvalidArgumentError

func NewInvalidArgumentError(msg string, fields ...Field) Ferror

NewInvalidArgumentError return an invalid argument error. It also records the stack trace at the point it was called.

func NewNotFoundError

func NewNotFoundError(msg string) Ferror

NewNotFoundError returns an not found error. It also records the stack trace at the point it was called.

func NewOutOfRangeError

func NewOutOfRangeError(msg string, fields ...Field) Ferror

NewOutOfRangeError returns an out of range error. It also records the stack trace at the point it was called.

func NewPermissionDeniedError

func NewPermissionDeniedError(msg string) Ferror

NewPermissionDeniedError returns permission denied error It also records the stack trace at the point it was called.

func NewUnauthenticatedError

func NewUnauthenticatedError(msg string) Ferror

NewUnauthenticatedError returns an unauthenticated error. It also records the stack trace at the point it was called.

func Newf

func Newf(format string, args ...interface{}) Ferror

Newf formats according to a format specifier and returns the string as a value that satisfies error. It also records the stack trace at the point it was called.

func WithCode

func WithCode(code ErrorCode, message string, detail ...*ErrorDetail) Ferror

WithCode returns an error with the supplied message and error code It also records the stack trace at the point it was called.

func WithStack

func WithStack(err error) Ferror

WithStack add stack trace to an error

func Wrapf

func Wrapf(err error, format string, args ...interface{}) Ferror

Wrapf wraps an error with custom formatted message. It also records the stack trace at the point it was called.

type Field

type Field struct {
	Name        string
	Description string
}

Field is the field that caused the error

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 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.