Categorygithub.com/go-pkgz/repeater/v2
modulepackage
2.0.1
Repository: https://github.com/go-pkgz/repeater.git
Documentation: pkg.go.dev

# README

Repeater

Build Status Go Report Card Coverage Status

Package repeater implements a functional mechanism to repeat operations with different retry strategies.

Install and update

go get -u github.com/go-pkgz/repeater

Usage

Basic Example with Exponential Backoff

// create repeater with exponential backoff
r := repeater.NewBackoff(5, time.Second) // 5 attempts starting with 1s delay

err := r.Do(ctx, func() error {
// do something that may fail
return nil
})

Fixed Delay with Critical Error

// create repeater with fixed delay
r := repeater.NewFixed(3, 100*time.Millisecond)

criticalErr := errors.New("critical error")

err := r.Do(ctx, func() error {
// do something that may fail
return fmt.Errorf("temp error")
}, criticalErr) // will stop immediately if criticalErr returned

Custom Backoff Strategy

r := repeater.NewBackoff(5, time.Second,
repeater.WithMaxDelay(10*time.Second),
repeater.WithBackoffType(repeater.BackoffLinear),
repeater.WithJitter(0.1),
)

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

err := r.Do(ctx, func() error {
// do something that may fail
return nil
})

Stop on Any Error

r := repeater.NewFixed(3, time.Millisecond)

err := r.Do(ctx, func() error {
return errors.New("some error")
}, repeater.ErrAny)  // will stop on any error

Strategies

The package provides several retry strategies:

  1. Fixed Delay - each retry happens after a fixed time interval
  2. Backoff - delay between retries increases according to the chosen algorithm:
    • Constant - same delay between attempts
    • Linear - delay increases linearly
    • Exponential - delay doubles with each attempt

Backoff strategy can be customized with:

  • Maximum delay cap
  • Jitter to prevent thundering herd
  • Different backoff types (constant/linear/exponential)

Custom Strategies

You can implement your own retry strategy by implementing the Strategy interface:

type Strategy interface {
    // NextDelay returns delay for the next attempt
    // attempt starts from 1
    NextDelay(attempt int) time.Duration
}

Example of a custom strategy that increases delay by a custom factor:

// CustomStrategy implements Strategy with custom factor-based delays
type CustomStrategy struct {
    Initial time.Duration
    Factor  float64
}

func (s CustomStrategy) NextDelay(attempt int) time.Duration {
    if attempt <= 0 {
        return 0
    }
    delay := time.Duration(float64(s.Initial) * math.Pow(s.Factor, float64(attempt-1)))
    return delay
}

// Usage
strategy := &CustomStrategy{Initial: time.Second, Factor: 1.5}
r := repeater.NewWithStrategy(5, strategy)
err := r.Do(ctx, func() error {
    // attempts will be delayed by: 1s, 1.5s, 2.25s, 3.37s, 5.06s
    return nil
})

Options

For backoff strategy, several options are available:

WithMaxDelay(time.Duration)   // set maximum delay between retries
WithBackoffType(BackoffType)  // set backoff type (constant/linear/exponential)
WithJitter(float64)           // add randomness to delays (0-1.0)

Error Handling

  • Stops on context cancellation
  • Can stop on specific errors (pass them as additional parameters to Do)
  • Special ErrAny to stop on any error
  • Returns last error if all attempts fail

# Functions

NewBackoff creates a repeater with backoff strategy Default settings (can be overridden with options): - 30s max delay - exponential backoff - 10% jitter.
NewFixed creates a repeater with fixed delay strategy.
NewFixedDelay creates a new FixedDelay strategy.
NewWithStrategy creates a repeater with a custom retry strategy.
WithBackoffType sets backoff type for the strategy.
WithJitter sets jitter factor for the backoff strategy.
WithMaxDelay sets maximum delay for the backoff strategy.

# Constants

BackoffConstant keeps delays the same between attempts.
BackoffExponential increases delays exponentially between attempts.
BackoffLinear increases delays linearly between attempts.

# Variables

ErrAny is a special sentinel error that, when passed as a critical error to Do, makes it fail on any error from the function.

# Structs

FixedDelay implements fixed time delay between attempts.
Repeater holds configuration for retry operations.

# Interfaces

Strategy defines how to calculate delays between retries.

# Type aliases

BackoffType represents the backoff strategy type.