orerr

Documentation

Overview

Package orerr implements outreach specific error utilities.

Index

• func CancelWithError(ctx context.Context) (c context.Context, cancel func(err error))
• func ExtractErrorMetadata(err error) map[string]string
• func ExtractErrorStatusCategory(err error) statuscodes.StatusCategory
• func ExtractErrorStatusCode(err error) statuscodes.StatusCode
• func Info(err error, info ...log.Marshaler) error
• func IsErrorStatusCategory(err error, category statuscodes.StatusCategory) bool
• func IsErrorStatusCode(err error, code statuscodes.StatusCode) bool
• func IsOneOf(err error, errs ...error) bool
• func IsRetryable(err error) bool
• func Meta(err error, meta map[string]string) error
• func New(err error, opts ...ErrOption) error
• func NewErrorStatus(errToWrap error, errCode statuscodes.StatusCode) error
• func Retryable(err error) *retryable
• type ErrOption
  • func WithInfo(info ...log.Marshaler) ErrOption
  • func WithMeta(meta map[string]string) ErrOption
  • func WithRetry() ErrOption
  • func WithStatus(code statuscodes.StatusCode) ErrOption
• type LimitExceededError
  • func (e LimitExceededError) Error() string
  • func (e LimitExceededError) Unwrap() error
• type SentinelError
  • func (s SentinelError) Error() string
• type ShutdownError
  • func (e ShutdownError) Error() string
  • func (e ShutdownError) Unwrap() error
• type StatusCodeWrapper
  • func (w *StatusCodeWrapper) Error() string
  • func (w *StatusCodeWrapper) StatusCategory() statuscodes.StatusCategory
  • func (w *StatusCodeWrapper) StatusCode() statuscodes.StatusCode
  • func (w *StatusCodeWrapper) Unwrap() error

Examples

• CancelWithError
• IsOneOf
• New
• Retryable
• SentinelError

Functions

func CancelWithError

func CancelWithError(ctx context.Context) (c context.Context, cancel func(err error))

CancelWithError returns a context and a cancel function where the cancel function can override the error reported by the context.

This function is similar to context.WithCancel except that the cancel function can specify an error. Note that the cancel function can be called with nil args to make it behave exactly like context.WithCancel.

Example

package main

import (
	"context"
	"fmt"

	"github.com/pkg/errors"

	"github.com/getoutreach/gobox/pkg/orerr"
)

func main() {
	origErr := errors.New("something went wrong")
	shutdownErr := &orerr.ShutdownError{Err: origErr}
	ctx, cancel := orerr.CancelWithError(context.Background())
	cancel(shutdownErr)

	fmt.Println("Err", ctx.Err())

}

Output:

Err process has shutdown

func ExtractErrorMetadata

func ExtractErrorMetadata(err error) map[string]string

ExtractErrorMetadata returns any embedded grpc metadata in

func ExtractErrorStatusCategory

func ExtractErrorStatusCategory(err error) statuscodes.StatusCategory

func ExtractErrorStatusCode

func ExtractErrorStatusCode(err error) statuscodes.StatusCode

func Info

func Info(err error, info ...log.Marshaler) error

Info adds extra logging info to an error.

func IsErrorStatusCategory

func IsErrorStatusCategory(err error, category statuscodes.StatusCategory) bool

func IsErrorStatusCode

func IsErrorStatusCode(err error, code statuscodes.StatusCode) bool

func IsOneOf

func IsOneOf(err error, errs ...error) bool

IsOneOf returns true if the supplied error is identical to an error supplied in the remaining function error arguments

Example

package main

import (
	"context"
	"fmt"
	"io"

	"github.com/getoutreach/gobox/pkg/orerr"
)

func main() {
	errList := []error{io.EOF, context.Canceled, context.DeadlineExceeded}

	if orerr.IsOneOf(io.EOF, errList...) {
		fmt.Println("io.EOF is part of the error list")
	}

}

Output:

io.EOF is part of the error list

func IsRetryable

func IsRetryable(err error) bool

IsRetryable returns whether or not err is retryable.

func Meta

func Meta(err error, meta map[string]string) error

Meta adds grpc metadata to an error.

func New

func New(err error, opts ...ErrOption) error

New creates a new error wrapping all the error options onto it.

For convenience, if err is nil, this function returns nil.

Example

package main

import (
	"fmt"

	"github.com/pkg/errors"

	"github.com/getoutreach/gobox/pkg/log"
	"github.com/getoutreach/gobox/pkg/orerr"
)

func main() {
	origErr := errors.New("something went wrong")
	info := log.F{"hello": "world"}
	err := orerr.New(origErr, orerr.WithInfo(info), orerr.WithRetry())

	formatted := log.F{}
	err.(log.Marshaler).MarshalLog(formatted.Set)
	fmt.Println("Err", err, orerr.IsRetryable(err), formatted)

}

Output:

Err something went wrong true map[hello:world]

func NewErrorStatus

func NewErrorStatus(errToWrap error, errCode statuscodes.StatusCode) error

func Retryable

func Retryable(err error) *retryable

Retryable wraps err in a type which denotes that the originating process is retryable.

Example

process := func(attempt int) error {
	err := errors.New("something went wrong")
	if attempt < 2 {
		return Retryable(err)
	}

	return err
}

for i := 0; ; i++ {
	if err := process(i); err != nil {
		if IsRetryable(err) {
			fmt.Println("error is retryable")
			continue
		}

		fmt.Println("error is not retryable:", err)
		break
	}
}

Output:

error is retryable
error is retryable
error is not retryable: something went wrong

Types

type ErrOption

type ErrOption func(err error) error

ErrOption just wraps an error.

func WithInfo

func WithInfo(info ...log.Marshaler) ErrOption

WithInfo attaches the provided logs to the error.

It is a functional option for use with New.

func WithMeta

func WithMeta(meta map[string]string) ErrOption

WithMeta attaches the provided grpc metadata to the error.

It is a functional option for use with New.

func WithRetry

func WithRetry() ErrOption

WithRetry marks the error as retryable.

It is a functional option for use with New.

func WithStatus

func WithStatus(code statuscodes.StatusCode) ErrOption

WithStatus calls NewErrorStatus with the given code.

It is a functional option for use with New.

type LimitExceededError

type LimitExceededError struct {
	// Kind refers to the kind of rate whose limit has been exceeded.
	Kind string

	Err error
}

LimitExceededError indicates some limit has exceeded. The actual limit that has exceeded is indicated via the Kind field. An inner error may be provided via Err.

func (LimitExceededError) Error

func (e LimitExceededError) Error() string

Error implements the err interface.

func (LimitExceededError) Unwrap

func (e LimitExceededError) Unwrap() error

Unwrap returns the inner error.

type SentinelError

type SentinelError string

A SentinelError is a constant which ought to be compared using errors.Is.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/getoutreach/gobox/pkg/orerr"
)

const ErrUsernameTaken orerr.SentinelError = "username already taken"

func createUser(username string) error {
	return ErrUsernameTaken
}

func main() {
	if err := createUser("joe"); err != nil {
		if errors.Is(err, ErrUsernameTaken) {
			fmt.Println("User 'joe' already exists")
			return
		}

		panic(err)
	}

}

Output:

User 'joe' already exists

func (SentinelError) Error

func (s SentinelError) Error() string

Error returns s as a string.

type ShutdownError

type ShutdownError struct {
	Err error
}

ShutdownError incidates the process is shutting down. An inner error may be provided via Err.

func (ShutdownError) Error

func (e ShutdownError) Error() string

Error implements the err interface.

func (ShutdownError) Unwrap

func (e ShutdownError) Unwrap() error

Unwrap returns the inner error.

type StatusCodeWrapper

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

func (*StatusCodeWrapper) Error

func (w *StatusCodeWrapper) Error() string

func (*StatusCodeWrapper) StatusCategory

func (w *StatusCodeWrapper) StatusCategory() statuscodes.StatusCategory

func (*StatusCodeWrapper) StatusCode

func (w *StatusCodeWrapper) StatusCode() statuscodes.StatusCode

func (*StatusCodeWrapper) Unwrap

func (w *StatusCodeWrapper) Unwrap() error