retry

Documentation

Overview

Package retry provides configurable retry logic with backoff strategies.

Package retry provides configurable retry utilities with exponential backoff for operations that may fail transiently.

Key features:

• Exponential and linear backoff strategies
• Configurable max attempts, delays, and jitter
• Context-aware cancellation
• Exit code filtering for selective retries

Example usage:

cfg := retry.Config{
    MaxAttempts:  3,
    InitialDelay: time.Second,
    Strategy:     retry.StrategyExponential,
    Multiplier:   2.0,
}
retryer := retry.New(cfg, logger)
result, err := retryer.Execute(ctx, func() (int, error) {
    return runCommand()
})

Index

• func ApplyJitter(delay time.Duration, jitter float64, rng *rand.Rand) time.Duration
• func CalculateDelay(strategy Strategy, attempt int, initialDelay, maxDelay time.Duration, ...) time.Duration
• type Config
• type Logger
• type Retryer
  • func NewRetryer(config *Config, logger Logger, seed int64) *Retryer
  • func (r *Retryer) IsRetryableExitCode(exitCode int) bool
  • func (r *Retryer) NextDelay(attempt int) time.Duration
  • func (r *Retryer) ShouldRetry(exitCode, attempt int) bool
  • func (r *Retryer) Wait(ctx context.Context, attempt int) error
• type Strategy
  • func (s Strategy) Valid() bool

Functions

func ApplyJitter

func ApplyJitter(delay time.Duration, jitter float64, rng *rand.Rand) time.Duration

ApplyJitter adds randomness to a delay within ±(delay * jitter). jitter should be in range [0.0, 1.0]. Uses the provided random source for deterministic testing.

func CalculateDelay

func CalculateDelay(strategy Strategy, attempt int, initialDelay, maxDelay time.Duration, multiplier float64) time.Duration

CalculateDelay computes the delay for a given attempt using the specified strategy. attempt is 1-indexed (first retry is attempt 2). The result is capped at maxDelay.

Types

type Config

type Config struct {
	MaxAttempts        int           // max retry attempts (1 = no retry)
	InitialDelay       time.Duration // base delay between attempts
	MaxDelay           time.Duration // maximum delay cap
	Strategy           Strategy      // backoff strategy
	Multiplier         float64       // multiplier for exponential backoff
	Jitter             float64       // randomness factor [0.0, 1.0]
	RetryableExitCodes []int         // exit codes that trigger retry (empty = any non-zero)
}

Config holds retry behavior configuration.

type Logger

type Logger interface {
	Debug(msg string, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
}

Logger defines the logging interface for retry operations.

type Retryer

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

Retryer handles retry logic with configurable backoff.

func NewRetryer

func NewRetryer(config *Config, logger Logger, seed int64) *Retryer

NewRetryer uses a seeded random source for jitter; pass a fixed seed for deterministic tests.

func (*Retryer) IsRetryableExitCode

func (r *Retryer) IsRetryableExitCode(exitCode int) bool

IsRetryableExitCode checks if the given exit code should trigger a retry.

func (*Retryer) NextDelay

func (r *Retryer) NextDelay(attempt int) time.Duration

NextDelay returns the delay to wait before the next attempt.

func (*Retryer) ShouldRetry

func (r *Retryer) ShouldRetry(exitCode, attempt int) bool

ShouldRetry returns true if the operation should be retried.

func (*Retryer) Wait

func (r *Retryer) Wait(ctx context.Context, attempt int) error

Wait sleeps for the calculated delay, respecting context cancellation.

type Strategy

type Strategy string

Strategy defines the backoff algorithm to use between retry attempts.

const (
	// StrategyConstant always waits the initial delay between attempts.
	StrategyConstant Strategy = "constant"
	// StrategyLinear increases delay linearly: initialDelay * attempt.
	StrategyLinear Strategy = "linear"
	// StrategyExponential increases delay exponentially: initialDelay * multiplier^(attempt-1).
	StrategyExponential Strategy = "exponential"
)

func (Strategy) Valid

func (s Strategy) Valid() bool

Valid returns true if the strategy is recognized.