README
¶
go-recovererr 
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
- 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)
}
- 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)
- 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)
- 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 ¶
- func Do(ctx context.Context, f func() error, newBackoffStrategy func() BackoffStrategy, ...) error
- func DoRecover(err error) (bool, bool)
- func Recoverable(err error) error
- func Retry(ctx context.Context, f func() error, backoffStrategy BackoffStrategy, ...) error
- func RetryForever(err error) bool
- func RetryNonUnrecoverablePolicy(err error) bool
- func RetryRecoverablePolicy(err error) bool
- func Unrecoverable(err error) error
- type BackoffStrategy
- type Clock
- type ConstantBackoff
- type ConstantBackoffOption
- type ExponentialBackoff
- type ExponentialBackoffOption
- func WithClock(clock backoff.Clock) ExponentialBackoffOption
- func WithInitialInterval(initialInterval time.Duration) ExponentialBackoffOption
- func WithMaxElapsedTime(maxElapsedTime time.Duration) ExponentialBackoffOption
- func WithMaxInterval(maxInterval time.Duration) ExponentialBackoffOption
- func WithMultiplier(multiplier float64) ExponentialBackoffOption
- func WithRandomisationFactory(randomisationFactor float64) ExponentialBackoffOption
- type RetryPolicy
- type SystemClock
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 ¶
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 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
RetryForever is a retry policy that defines that whatever the input to be evaluated, retry should be performed.
func RetryNonUnrecoverablePolicy ¶
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 ¶
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 ¶
Unrecoverable wraps an error as unrecoverable.
Types ¶
type BackoffStrategy ¶ added in v0.2.0
BackoffStrategy provides different backoff methods for the retry mechanism.
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.
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.
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 ¶
RetryPolicy function implements the policy for performing a retry.
type SystemClock ¶ added in v0.2.0
type SystemClock struct{}
SystemClock provides time package dependency.
Source Files