retry

Documentation

Overview

Package retry provides retry logic with exponential backoff for transient errors.

Index

• func Do[T any](ctx context.Context, cfg Config, fn func() (T, error)) (T, error)
• func DoStream[T any](ctx context.Context, cfg Config, fn func() (<-chan T, error)) (<-chan T, error)
• func DoStreamWithEvents[T any](ctx context.Context, cfg Config, events chan<- Event, ...) (<-chan T, error)
• func DoWithEvents[T any](ctx context.Context, cfg Config, events chan<- Event, fn func() (T, error)) (T, error)
• func IsTransient(err error) bool
• type Config
  • func DefaultConfig() Config
  • func Disabled() Config
  • func (c Config) Delay(attempt int) time.Duration
• type Event
• type EventType

Functions

func Do

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

Do executes the given function with retry logic. It respects context cancellation during backoff waits. Returns the result on success, or the last error if all attempts fail.

func DoStream

func DoStream[T any](ctx context.Context, cfg Config, fn func() (<-chan T, error)) (<-chan T, error)

DoStream is like Do but for functions that return a channel. It retries the stream connection establishment, not individual chunks.

func DoStreamWithEvents

func DoStreamWithEvents[T any](ctx context.Context, cfg Config, events chan<- Event, fn func() (<-chan T, error)) (<-chan T, error)

DoStreamWithEvents is like DoStream but emits events for observability. Events are sent non-blocking; if the channel is full, events are dropped. Pass nil for events to disable event emission (equivalent to DoStream).

func DoWithEvents

func DoWithEvents[T any](ctx context.Context, cfg Config, events chan<- Event, fn func() (T, error)) (T, error)

DoWithEvents is like Do but emits events for observability. Events are sent non-blocking; if the channel is full, events are dropped. Pass nil for events to disable event emission (equivalent to Do).

func IsTransient

func IsTransient(err error) bool

IsTransient determines if an error is transient and should be retried. It checks for: - Rate limits (HTTP 429) - Server errors (HTTP 5xx) - Network timeouts - Connection resets - DNS failures

Types

type Config

type Config struct {
	// MaxAttempts is the maximum number of attempts (default: 10).
	// The initial request counts as attempt 1.
	MaxAttempts int

	// InitialDelay is the base delay before the first retry (default: 1s).
	InitialDelay time.Duration

	// MaxDelay is the maximum delay between retries (default: 60s).
	MaxDelay time.Duration

	// Multiplier is the exponential backoff multiplier (default: 2.0).
	Multiplier float64

	// Jitter adds randomness to prevent thundering herd (default: 0.1 = 10%).
	// Delay is multiplied by (1 + random(-jitter, +jitter)).
	Jitter float64
}

Config holds retry configuration parameters.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the default retry configuration. - 10 max attempts - 1 second initial delay - 60 second max delay - 2x exponential multiplier - 10% jitter

func Disabled

func Disabled() Config

Disabled returns a configuration that disables retries (single attempt).

func (Config) Delay

func (c Config) Delay(attempt int) time.Duration

Delay calculates the delay for a given attempt number (0-indexed). Formula: min(maxDelay, initialDelay * multiplier^attempt) * (1 + jitter)

type Event

type Event struct {
	// Type identifies the kind of event.
	Type EventType

	// Attempt is the current attempt number (1-indexed).
	Attempt int

	// MaxAttempts is the total number of attempts allowed.
	MaxAttempts int

	// Error contains the error from a failed attempt.
	Error error

	// Delay is the duration before the next attempt (for EventRetrying).
	Delay time.Duration

	// Retryable indicates whether the error was classified as transient.
	Retryable bool

	// Timestamp is when the event occurred.
	Timestamp time.Time
}

Event represents an observable occurrence during retry execution.

type EventType

type EventType string

EventType identifies the kind of event occurring during retry execution.

const (
	// EventAttemptStart fires before each attempt.
	EventAttemptStart EventType = "attempt_start"

	// EventAttemptFailed fires after a failed attempt.
	EventAttemptFailed EventType = "attempt_failed"

	// EventRetrying fires before sleeping between attempts.
	EventRetrying EventType = "retrying"

	// EventSuccess fires when an attempt succeeds.
	EventSuccess EventType = "success"

	// EventExhausted fires when all retry attempts are exhausted.
	EventExhausted EventType = "exhausted"
)