go-retry

To perform a retry operation, use one of the provided backoff functions (like retry.Fibonacci, retry.Exponential, or retry.Constant) and pass a context and a function that returns an error. To signal that an error should trigger a retry, wrap it with retry.RetryableError(err). If the function returns a non-retryable error, the retry loop terminates immediately.

package main

import (
  "context"
  "database/sql"
  "log"
  "time"

  "github.com/sethvargo/go-retry"
)

func main() {
  db, err := sql.Open("mysql", "...")
  if err != nil {
    log.Fatal(err)
  }

  ctx := context.Background()
  if err := retry.Fibonacci(ctx, 1*time.Second, func(ctx context.Context) error {
    if err := db.PingContext(ctx); err != nil {
      // This marks the error as retryable
      return retry.RetryableError(err)
    }
    return nil
  }); err != nil {
    log.Fatal(err)
  }
}

The order in which you wrap your backoff with modifiers matters significantly:

1. CappedDuration vs WithMaxDuration: Always add WithCappedDuration before WithMaxDuration. If added after, the total duration limit might trigger prematurely.
2. Jitter placement: You can add Jitter before or after CappedDuration depending on whether you want the jitter to be subject to the cap or applied to the capped value.

The library provides several base backoff algorithms. These algorithms, by default, never terminate and have no limits. They are used as the foundation for middleware composition.

• Constant: Returns the same duration every time.
  • Usage: retry.NewConstant(duration)
• Exponential: Doubles the duration with each step (e.g., 1s, 2s, 4s, 8s).
  • Usage: retry.NewExponential(duration)
• Fibonacci: Uses the Fibonacci sequence (e.g., 1s, 1s, 2s, 3s, 5s). Ideal for network-type issues.
  • Usage: retry.NewFibonacci(duration)

// Examples of base backoff creation
b := retry.NewConstant(1 * time.Second)
b := retry.NewExponential(1 * time.Second)
b := retry.NewFibonacci(1 * time.Second)

To instruct the retry mechanism to attempt the operation again, you must wrap the error using RetryableError(err). If an error is returned that is not wrapped with RetryableError, the retry loop will terminate immediately and return that error. This allows you to distinguish between transient errors that should be retried and permanent errors that should fail fast.

err := retry.RetryableError(fmt.Errorf("temporary failure"))

Use NewExponential(base time.Duration) to create a Backoff instance that implements an exponential growth strategy.

• Behavior: The delay doubles on each failure (1, 2, 4, 8, 16, 32, 64...).
• Concurrency: The returned Backoff is safe for concurrent use.
• Overflow: Once the duration overflows, it returns math.MaxInt64 and false (indicating no further valid increments).
• Panic: The function will panic if the provided base is less than or equal to zero.

backoff := retry.NewExponential(100 * time.Millisecond)
// Use backoff with retry.Do()...

Use WithMaxRetries(max uint64, next Backoff) to wrap a backoff strategy so that it stops after a specific number of attempts. Once the max number of attempts is reached, Next() will return 0, true.

// Example: Stop after 5 attempts
// backoff := retry.WithMaxRetries(5, retry.Exponential(time.Second, 2.0))

Use DoValue when the function being retried returns both a value and an error. It follows the same retry logic as Do: it will continue retrying as long as the error returned by the function is wrapped with RetryableError and the Backoff strategy allows more attempts. If the function succeeds, it returns the value and a nil error. If the backoff is exhausted or the context is canceled, it returns the zero value of the type and the error.

type result struct {
    Data string
}

val, err := retry.DoValue(ctx, backoff, func(ctx context.Context) (result, error) {
    res, err := fetchData(ctx)
    if err != nil {
        return result{}, retry.RetryableError(err)
    }
    return res, nil
})

The Exponential function is a convenience wrapper that executes a RetryFunc using an exponential backoff strategy. It starts with the provided base duration and doubles the delay on each subsequent failure (e.g., 1, 2, 4, 8...).

It uses Do(ctx, NewExponential(base), f) internally. If the calculated delay overflows the 64-bit integer limit, it returns math.MaxInt64.

err := retry.Exponential(ctx, 100*time.Millisecond, func(ctx context.Context) error {
    // Your retryable logic here
    return nil
})

Jitter helps prevent 'thundering herd' problems by adding randomness to retry intervals. The library provides three ways to apply jitter:

1. WithJitter(j time.Duration, next Backoff): Adds a fixed range of +/- j to the returned duration. The result is clamped to a minimum of 0.
2. WithJitterPercent(j uint64, next Backoff): Adds a percentage-based jitter of +/- j%. For example, if j is 5 and the backoff returns 20s, the result will be between 19s and 21s.
3. WithFullJitter(next Backoff): Returns a random value in the range [0, next_duration). This is highly effective for spreading out retrying clients across the entire interval.

// Example of applying jitter
// backoff := retry.WithFullJitter(retry.Constant(time.Second))
// backoff := retry.WithJitter(5*time.Second, retry.Constant(20*time.Second))

The NewConstant function returns a Backoff implementation that always returns the same duration t for every retry attempt. This is useful when you want to pass a specific backoff strategy into the Do function or other retry orchestrators.

Note: This function will panic if the provided duration t is less than or equal to zero.

backoff := retry.NewConstant(500 * time.Millisecond)
// Use the backoff with retry.Do(ctx, backoff, retryFunc)

The Fibonacci function is a convenience wrapper that executes a RetryFunc using a Fibonacci backoff strategy. It takes a context.Context, a base duration (the starting value for the sequence), and the function to retry. The wait time follows the Fibonacci sequence (e.g., 1, 1, 2, 3, 5, 8, 13...) based on the provided base.

err := retry.Fibonacci(ctx, 100*time.Millisecond, func(ctx context.Context) error {
    // Your retryable logic here
    return nil
})