retry

README

Go library to handle retries

Retry the function, with 1 second between calls with jitter, until it succeeds:

cfg := retry.Config{Delay: time.Second}

err = retry.Do(ctx, cfg, func(ctx context.Context) error {
    ...
    return Retriable(err)
})

val, err = retry.Do1(ctx, cfg, func(ctx context.Context) (Foo, error) {
    ...
    return Foo{}, Retriable(err)
})

Retry is triggered by inner function returning retry.ErrRetry or retry.ErrRestart.

Other errors and nil stop the retries.

Exponential backoff

retry.Config{Delay: 1*time.Second, Scale: 1.5}

Capped exponential backoff

retry.Config{Delay: 1*time.Second, Scale: 1.5, MaxDelay: 10*time.Second}

Resetting backoff

If a function returns retry.ErrRestart then the delay is reset to Config.Delay.

Additional delay before first call

retry.Config{PreDelay: 200*time.Millisecond, Delay: 1*time.Second}

Jitter

# Default, ±12.5%
retry.Config{Delay: 1*time.Second}
# ±50%
retry.Config{Delay: 1*time.Second, Jitter: 0.5}
# Disabled
retry.Config{Delay: 1*time.Second, Jitter: retry.NoJitter}

Timeout

Cancel the inner context, wait for the called function to return and do not retry if a timeout is reached:

retry.Config{Delay: 1*time.Second, Timeout: 30*time.Second}

Resetting timeout

If a function returns retry.ErrRestart then the timeout is reset to Config.Timeout.

Legal

Copyright Mikhail Gusarov dottedmag@dottedmag.net.

Licensed under Apache 2.0 license.

Documentation

Index

• Constants
• Variables
• func Do(ctx context.Context, cfg Config, fn func(ctx context.Context) error) error
• func Do1[T any](ctx context.Context, cfg Config, fn func(ctx context.Context) (T, error)) (T, error)
• func Restartable(err error) error
• func Retriable(err error) error
• type Config
• type ErrRestart
  • func (e ErrRestart) Error() string
  • func (e ErrRestart) Unwrap() error
• type ErrRetry
  • func (e ErrRetry) Error() string
  • func (e ErrRetry) Unwrap() error

Constants

const NoJitter = -1

NoJitter is a jitter value that disables jitter

Variables

var NoLog = slog.New(discardHandler{})

NoLog is a logger that discards all log messages, to be removed once in stdlib

Functions

func Do

func Do(ctx context.Context, cfg Config, fn func(ctx context.Context) error) error

Do runs fn with retries controlled by config

fn triggers a retry by returning ErrRetry or ErrRestart. Any other return value ends the retry and is returned to the caller.

Context passed to fn is valid only during one attempt, and may or may not be canceled afterwards.

func Do1

func Do1[T any](ctx context.Context, cfg Config, fn func(ctx context.Context) (T, error)) (T, error)

Do1 is a version of Do with one return value

func Restartable

func Restartable(err error) error

Restartable wraps the error in ErrRestart if it is not nil

Typical usage is to wrap a potential error known to require a restart.

func Retriable

func Retriable(err error) error

Retriable wraps the error in ErrRetry if it is not nil

Typical usage is to wrap a potential error known to be retriable.

Types

type Config

type Config struct {
	// Delay is a delay between attempts. It is scaled by Scale for each
	// consecutive attempt until it reaches MaxDelay
	//
	// This field is required.
	Delay time.Duration

	// Scale is a exponential scale for delay.
	//
	// Defaults to 1 (no scaling, constant delay), can't be less than 1.
	Scale float64

	// Jitter is the amount of jitter to add to the delay.
	//
	// Defaults to 0.125 (12.5%), and has to be within [0,1].
	// To disable jitter, set this field to NoJitter.
	Jitter float64

	// PreDelay is optional delay before first try.
	//
	// Defaults to 0.
	PreDelay time.Duration

	// MaxDelay is a cap on delay scaling.
	//
	// Defaults to no maximum.
	MaxDelay time.Duration

	// Timeout is a maximum total time to retry.
	//
	// If timeout is reached then the context passed to the called function
	// will be called, and retry won't be attempted when the function returns.
	//
	// Note that if called function should handle context cancellation
	// for aborting the operation by timeout.
	//
	// Defaults to no timeout.
	Timeout time.Duration

	// Logger is a logger for retries
	//
	// This package logs retriable errors returned by an invoked function.
	// It omits logging identical subsequent errors.
	//
	// Defaults to slog.Default. Set to NoLog to disable logging.
	Logger *slog.Logger

	// LogLevel is a log level for retries
	//
	// Defaults to slog.Debug.
	LogLevel slog.Level
	// contains filtered or unexported fields
}

Config configures the retry

type ErrRestart

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

ErrRestart signals the restart of retry attempts, resetting both delay and timeout

func (ErrRestart) Error

func (e ErrRestart) Error() string

func (ErrRestart) Unwrap

func (e ErrRestart) Unwrap() error

type ErrRetry

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

ErrRetry signals the retry attempt

func (ErrRetry) Error

func (e ErrRetry) Error() string

func (ErrRetry) Unwrap

func (e ErrRetry) Unwrap() error