retry

Documentation

Overview

Package retry is an internal exponential-backoff helper used by provider clients (currently llm/openrouter) at stream-start. It is intentionally internal — see ADR-022. The shape is small on purpose: a single Do function driven by a Policy struct, with a RetryAfterError escape hatch for honoring HTTP 429 Retry-After headers.

Index

• func Do(ctx context.Context, policy Policy, fn func(attempt int) error) error
• type Policy
  • func DefaultPolicy() Policy
• type RetryAfterError
  • func (e *RetryAfterError) Error() string
  • func (e *RetryAfterError) Unwrap() error

Functions

func Do

func Do(ctx context.Context, policy Policy, fn func(attempt int) error) error

Do invokes fn until it returns nil, ctx cancels, MaxAttempts is reached, or fn returns an error policy.ShouldRetry deems non-retryable. Returns the final error (the last fn return value, or ctx.Err() if context cancelled during a sleep).

The attempt argument passed to fn is 1-based.

Types

type Policy

type Policy struct {
	// MaxAttempts is the total number of attempts (>= 1). MaxAttempts == 1 is
	// "no retry, just call once."
	MaxAttempts int

	// BaseDelay is the initial backoff delay before the second attempt.
	BaseDelay time.Duration

	// MaxDelay caps any single backoff sleep.
	MaxDelay time.Duration

	// Multiplier is the exponential growth factor between attempts (>= 1.0).
	Multiplier float64

	// Jitter, in the [0, 1] range, is the proportional jitter applied to each
	// computed sleep. Jitter == 0 means no randomization. Jitter == 0.2 means
	// the actual sleep is uniformly random in [d*(1-0.2), d*(1+0.2)].
	Jitter float64

	// ShouldRetry decides whether err is retryable. Required (non-nil).
	ShouldRetry func(err error) bool
}

Policy configures Do.

func DefaultPolicy

func DefaultPolicy() Policy

DefaultPolicy returns the project-wide default retry policy: 3 attempts, 500ms base, 30s cap, 2x multiplier, 20% jitter. The default ShouldRetry retries every error — provider clients should override with a typed-error predicate.

type RetryAfterError

type RetryAfterError struct {
	Cause error
	After time.Duration
}

RetryAfterError is an error that overrides the policy's computed backoff with an explicit duration. Provider clients wrap their 429-with-Retry-After failures in RetryAfterError so this package honors the server's hint.

func (*RetryAfterError) Error

func (e *RetryAfterError) Error() string

func (*RetryAfterError) Unwrap

func (e *RetryAfterError) Unwrap() error