retry

README

package retry

This package implements a configurable retry mechanism that can be embedded in any class needing a retry-on-error system.

It's flexible enough to support any process that exposes a func() error method, and can be extended for other retry strategies than we default ones.

Supported strategies:

• OneTry (default): don't retry, fail on the first error
• RetryCount: retry for a set number of attempts when TriggerRetry is called (returning a FailWillRetry error), then fail with a PermaFail
• Backoff: retry with a duration between two consecutive retries that double at each new try up to a maximum

How to embed the Retrier

Your class needs to:

• provide a function returning an error (nil on success)
• embed a Retrier object as an anonymous struct field (like a sync.Mutex)
• call self.SetupRetrier() with a valid Config struct

Have a look at retrier_test.go for an example.

How to use a class embedding Retrier

Assuming the class is properly initialised, you can use any of the public methods from retrier.go on that class:

• RetryStatus() will return the current status (defined in types.go)
• TriggerRetry() will either return nil if everything is OK, or an error (real type Retry.Error) if the attempt was unsuccessful.
• passing the error to Retry.IsErrWillRetry() and Retry.IsErrPermaFail() will tell you whether it's necessary to retry again, or just give up initialising this object
• retry throtling is implemented in case several users try to use a class. Calling NextRetry() will tell you when the next retry is possible. Before that time, all calls to TriggerRetry() will return a FailWillRetry error. The retry will not automatically run when that time is reached, you have to schedule a call to TriggerRetry.

Documentation

Index

• func IsErrPermaFail(err error) bool
• func IsErrWillRetry(err error) bool
• type Config
• type Error
  • func IsRetryError(e error) (bool, *Error)
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type Retrier
  • func (r *Retrier) LastError() *Error
  • func (r *Retrier) NextRetry() time.Time
  • func (r *Retrier) RetryStatus() Status
  • func (r *Retrier) SetupRetrier(cfg *Config) error
  • func (r *Retrier) TriggerRetry() *Error
• type Status
• type Strategy

Functions

func IsErrPermaFail

func IsErrPermaFail(err error) bool

IsErrPermaFail checks whether an `error` is a Retrier permanent fail

func IsErrWillRetry

func IsErrWillRetry(err error) bool

IsErrWillRetry checks whether an `error` is a Retrier temporary fail

Types

type Config

type Config struct {
	Name              string
	AttemptMethod     func() error
	Strategy          Strategy
	RetryCount        uint
	RetryDelay        time.Duration
	InitialRetryDelay time.Duration
	MaxRetryDelay     time.Duration
	// contains filtered or unexported fields
}

Config contains all the required parameters for Retrier

type Error

type Error struct {
	LogicError    error
	LastTryError  error
	RessourceName string
	RetryStatus   Status
}

Error is a custom error type that is returned by the Retrier you can get its Status with IsRetryError()

func IsRetryError

func IsRetryError(e error) (bool, *Error)

IsRetryError checks an `error` object to tell if it's a Retry.Error

func (*Error) Error

func (e *Error) Error() string

Error implements the `error` interface

func (*Error) Unwrap

func (e *Error) Unwrap() error

Unwrap implements the Go 1.13 unwrap convention

type Retrier

type Retrier struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

Retrier implements a configurable retry mechanism than can be embedded in any class providing attempt logic as a `func() error` method. See the unit test for an example.

func (*Retrier) LastError

func (r *Retrier) LastError() *Error

LastError allows users to know what the last retry failure error was

func (*Retrier) NextRetry

func (r *Retrier) NextRetry() time.Time

NextRetry allows users to know when the next retry can happened

func (*Retrier) RetryStatus

func (r *Retrier) RetryStatus() Status

RetryStatus allows users to query the status

func (*Retrier) SetupRetrier

func (r *Retrier) SetupRetrier(cfg *Config) error

SetupRetrier must be called before calling other methods

func (*Retrier) TriggerRetry

func (r *Retrier) TriggerRetry() *Error

TriggerRetry triggers a new retry and returns the result

type Status

type Status int

Status is returned by Retrier object to inform user classes

const (
	// NeedSetup is the default value: SetupRetrier must be called
	NeedSetup Status = iota // Default zero value
	// Idle means the Retrier is ready for Try to be called
	Idle
	// OK means the object is available
	OK
	// FailWillRetry informs users the object is not available yet,
	// but they should retry later
	FailWillRetry
	// PermaFail informs the user the object will not be available.
	PermaFail
)

type Strategy

type Strategy int

Strategy sets how the Retrier should handle failure

const (
	// OneTry is the default value: only try one, then permafail
	OneTry Strategy = iota // Default zero value
	// RetryCount sets the Retrier to try a fixed number of times
	RetryCount
	// Backoff retries often at the beginning and then, less often
	Backoff

	// JustTesting forces an OK status for unit tests that require a
	// non-functional object but no failure on init (eg. docker)
	JustTesting
)