retry

Documentation

Overview

Package retry exposes a 'Retryer' allowing conditionally retrying (with back-off) of functions.

Index

• func IsRetriesAborted(err error) bool
• func IsRetriesExhausted(err error) bool
• type Algorithm
• type CleanupFunc
• type Context
  • func NewContext(ctx context.Context) *Context
  • func (c *Context) Attempt() int
• type LogFunc
• type RetriesAbortedError
  • func (r *RetriesAbortedError) Error() string
  • func (r *RetriesAbortedError) Unwrap() error
• type RetriesExhaustedError
  • func (r *RetriesExhaustedError) Error() string
  • func (r *RetriesExhaustedError) Unwrap() error
• type RetryableFunc
• type Retryer
  • func NewRetryer(options RetryerOptions) Retryer
  • func (r Retryer) Do(fn RetryableFunc) (any, error)
  • func (r Retryer) DoWithContext(ctx context.Context, fn RetryableFunc) (any, error)
• type RetryerOptions
• type ShouldRetryFunc

Functions

func IsRetriesAborted

func IsRetriesAborted(err error) bool

IsRetriesAborted returns a boolean indicating whether the given error is a 'RetriesAbortedError'.

func IsRetriesExhausted

func IsRetriesExhausted(err error) bool

IsRetriesExhausted returns a boolean indicating whether the given error is a 'RetriesExhaustedError'.

Types

type Algorithm

type Algorithm int

Algorithm represents a retry algorithm used to determine backoff before retrying function execution.

const (
	// AlgorithmFibonacci backs off using the fibonacci sequence e.g. 50ms, 50ms, 100ms ... 128h9m33s
	AlgorithmFibonacci Algorithm = iota

	// AlgorithmExponential backs off exponentially e.g. 100ms, 200ms, 400ms ... 477218h35m18s
	AlgorithmExponential

	// AlgorithmLinear backs off linearly e.g. 50ms, 100ms, 150ms ... 1.75s
	AlgorithmLinear
)

type CleanupFunc

type CleanupFunc func(payload any)

CleanupFunc is a function which is run with the payload for all, but the last retry attempt.

NOTE: The final attempt is not cleaned up because the payload may want to be used/read to enhance returned errors.

type Context

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

Context wraps the 'context.Context' interface whilst allowing access to useful attributes such as the number of attempts made so far.

func NewContext

func NewContext(ctx context.Context) *Context

NewContext wraps the given context with a retry context.

func (*Context) Attempt

func (c *Context) Attempt() int

Attempt returns the current attempt number.

type LogFunc

type LogFunc func(ctx *Context, payload any, err error)

LogFunc is a function which is run before each retry attempt after failing to run the given 'RetryableFunc'.

type RetriesAbortedError

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

RetriesAbortedError is returned when retries have been aborted for some reason, likely due to a context cancellation.

func (*RetriesAbortedError) Error

func (r *RetriesAbortedError) Error() string

func (*RetriesAbortedError) Unwrap

func (r *RetriesAbortedError) Unwrap() error

type RetriesExhaustedError

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

RetriesExhaustedError is returned after exhausting the max number of retries, unwrapping the error will return the error from the last failure.

func (*RetriesExhaustedError) Error

func (r *RetriesExhaustedError) Error() string

func (*RetriesExhaustedError) Unwrap

func (r *RetriesExhaustedError) Unwrap() error

type RetryableFunc

type RetryableFunc func(ctx *Context) (any, error)

RetryableFunc represents a function which is retryable.

type Retryer

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

Retryer is a function retryer, which supports executing a given function a number of times until successful.

func NewRetryer

func NewRetryer(options RetryerOptions) Retryer

NewRetryer returns a new retryer with the given options.

func (Retryer) Do

func (r Retryer) Do(fn RetryableFunc) (any, error)

Do executes the given function until it's successful.

func (Retryer) DoWithContext

func (r Retryer) DoWithContext(ctx context.Context, fn RetryableFunc) (any, error)

DoWithContext executes the given function until it's successful, the provided context may be used for cancellation.

type RetryerOptions

type RetryerOptions struct {
	// Algorithm is the algorithm to use when calculating backoff.
	Algorithm Algorithm

	// MaxRetries is the maximum number of times to retry the function.
	MaxRetries int

	// MinDelay is the minimum delay to use for backoff.
	MinDelay time.Duration

	// MaxDelay is the maximum delay to use for backoff.
	MaxDelay time.Duration

	// ShouldRetry is a custom retry function, when not supplied, this will be defaulted to 'err != nil'.
	ShouldRetry ShouldRetryFunc

	// Log is a function which is run before each retry, when not supplied logging will be skipped.
	Log LogFunc

	// Cleanup is a cleanup function run for all but the last payloads prior to performing a retry.
	Cleanup CleanupFunc
}

RetryerOptions encapsulates the options available when creating a retryer.

type ShouldRetryFunc

type ShouldRetryFunc func(ctx *Context, payload any, err error) bool

ShouldRetryFunc is a function which may be supplied to the retry options which allows more control over which types of errors are retried.

NOTE: If not supplied, retries will take place if the given 'RetryableFunc' returns an error.