recovererr

package module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2022 License: MIT Imports: 6 Imported by: 0

README

go-recovererr Go Reference Go Report Card

Installation

go get -u github.com/sermojohn/go-recovererr

Naming

The package name was conceived by merging recover and error and can be pronounced as recoverer.

Usage

  1. Wrap recoverable errors with an error value implementing Recover() bool:
type customError struct {
	recoverable bool
	message     string
}

func (ce *customError) Recover() bool {
	return ce.recoverable
}
func (ce *customError) Error() string {
	return fmt.Sprintf("recoverable:%t, message:%s", ce.recoverable, ce.message)
}
  1. Retry action of recoverable error per 1sec forever:
action := func() error {
    return &customError{recoverable: true}
}

backoff := NewConstantBackoff(time.Second, 0)

_ = Retry(context.Background(), action, backoff, RetryRecoverablePolicy)
  1. Retry action of recoverable error using exponential backoff starting with 1sec until 5sec elapse:
action := func() error {
    return &customError{recoverable: true}
}
backoff := NewExponentialBackoff(
    WithInitialInterval(time.Second), 
    WithMaxElapsedTime(5*time.Second),
)

_ = Retry(context.Background(), action, backoff, RetryRecoverablePolicy)
  1. Retry action of non unrecoverable error:
action := func() error {
    return errors.New("any error")
}
backoff := NewConstantBackoff(time.Second, 0)

_ = Retry(context.Background(), action, backoff, RetryNonUnrecoverablePolicy)

Description

Error recovery context

The package provides Recoverable and Unrecoverable public functions to wrap the given error with recovery context. Also provides DoRecover function to check the recovery context of any error.

Retry

The package provides function Retry that receives a function that optionally returns an error. The RetryPolicy is provided to Retry, to check the error recovery context on failure and define if the function should be retried. The BackoffStrategy is provided to defind the delay applied before each retry performing either constant or exponential backoff. If context.Context gets cancelled no extra retry will be performed, but the original error will be wrapped to the timeout error.

Documentation

Overview

This package provides utilities to add recovery context to errors. Error chain is traversable by unwrapping the given error.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Do added in v0.4.0

func Do(ctx context.Context, f func() error, newBackoffStrategy func() BackoffStrategy, retryPolicy RetryPolicy) error

Do will run a funtion and initiate retries if it fails.

The call to `Retry` is postponed until an error is returned by the function.

func DoRecover

func DoRecover(err error) (bool, bool)

DoRecover can be used by user to validate if error should be recovered. When no recovery context is found in the given error, it returns false in both values. When recovery context is found in the given error, it returns true in the first value and the recovery context of the error.

func Recoverable

func Recoverable(err error) error

Recoverable wraps an error as recoverable.

func Retry

func Retry(ctx context.Context, f func() error, backoffStrategy BackoffStrategy, retryPolicy RetryPolicy) error

Retry will run the provided function.

If the function fails, retryPolicy is used to extract the recovery context. Retry will be performed on intervals provided by a time channel until the context is cancelled.

func RetryForever added in v0.5.0

func RetryForever(err error) bool

RetryForever is a retry policy that defines that whatever the input to be evaluated, retry should be performed.

func RetryNonUnrecoverablePolicy

func RetryNonUnrecoverablePolicy(err error) bool

RetryNonUnrecoverablePolicy defines if retry should be performed after receiving the provided error by the retry mechanism.

Returns: 1. true if error is not unrecoverable 2. true for errors with no recovery context 3. false when no err was provided

func RetryRecoverablePolicy

func RetryRecoverablePolicy(err error) bool

RetryRecoverablePolicy defines if retry should be performed after receiving the provided error by the retry mechanism.

Returns: 1. true if error is recoverable 2. false for errors with no recovery context 3. false when no err was provided

func Unrecoverable

func Unrecoverable(err error) error

Unrecoverable wraps an error as unrecoverable.

Types

type BackoffStrategy added in v0.2.0

type BackoffStrategy interface {
	Next() (time.Duration, bool)
}

BackoffStrategy provides different backoff methods for the retry mechanism.

type Clock added in v0.2.0

type Clock interface {
	After(time.Duration) <-chan time.Time
}

Clock replaces time package to provide mock replacements.

type ConstantBackoff added in v0.2.0

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

ConstantBackoff implements backoff strategy using constant delay and max attempts.

func NewConstantBackoff added in v0.2.0

func NewConstantBackoff(opts ...ConstantBackoffOption) *ConstantBackoff

NewConstantBackoff creates new constant backoff using provided parameters.

func (*ConstantBackoff) Next added in v0.2.0

func (cb *ConstantBackoff) Next() (time.Duration, bool)

Next implements the BackoffStrategy.Next method.

type ConstantBackoffOption added in v0.3.0

type ConstantBackoffOption func(*ConstantBackoff)

ConstantBackoffOption configures constant backoff parameters.

func WithInterval added in v0.3.0

func WithInterval(d time.Duration) ConstantBackoffOption

WithInterval configure constant backoff with specified backoff interval.

func WithMaxAttempts added in v0.3.0

func WithMaxAttempts(n int) ConstantBackoffOption

WithMaxAttempts configure constant backoff with specified max backoff attempts.

type ExponentialBackoff added in v0.2.0

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

ConstantBackoff implements backoff strategy using using exponentially increased delays.

func NewExponentialBackoff added in v0.2.0

func NewExponentialBackoff(opts ...ExponentialBackoffOption) *ExponentialBackoff

NewExponentialBackoff creates new exponential backoff using provided options.

func (*ExponentialBackoff) Next added in v0.2.0

func (eb *ExponentialBackoff) Next() (time.Duration, bool)

Next implements the BackoffStrategy.Next method.

type ExponentialBackoffOption added in v0.3.0

type ExponentialBackoffOption func(*ExponentialBackoff)

ExponentialBackoffOption configures exponential backoff parameters.

func WithClock added in v0.2.0

func WithClock(clock backoff.Clock) ExponentialBackoffOption

WithClock sets clock implementation to exponential backoff.

func WithInitialInterval added in v0.2.0

func WithInitialInterval(initialInterval time.Duration) ExponentialBackoffOption

WithInitialInterval sets initial interval to exponential backoff.

func WithMaxElapsedTime added in v0.2.0

func WithMaxElapsedTime(maxElapsedTime time.Duration) ExponentialBackoffOption

WithMaxElapsedTime sets max elapsed time to exponential backoff.

func WithMaxInterval added in v0.2.0

func WithMaxInterval(maxInterval time.Duration) ExponentialBackoffOption

WithMaxInterval sets max interval to exponential backoff.

func WithMultiplier added in v0.2.0

func WithMultiplier(multiplier float64) ExponentialBackoffOption

WithMultiplier sets multiplier to exponential backoff.

func WithRandomisationFactory added in v0.2.0

func WithRandomisationFactory(randomisationFactor float64) ExponentialBackoffOption

WithRandomisationFactory sets randomisation factor to exponential backoff.

type RetryPolicy

type RetryPolicy func(error) bool

RetryPolicy function implements the policy for performing a retry.

type SystemClock added in v0.2.0

type SystemClock struct{}

SystemClock provides time package dependency.

func (*SystemClock) After added in v0.2.0

func (sc *SystemClock) After(d time.Duration) <-chan time.Time

After implement the Clock.After method.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL