retry

Documentation

Overview

Package retry implements ADR-0010's bounded-retry policy: at most 3 retries with exponential backoff (1s/2s/4s + jitter) for failures the failure package marks retriable. Network failures and upstream 429/5xx responses are the canonical retriable classes; everything else fails fast.

The primitive is generic across return types so it can wrap both the executor seam and HTTP upstream calls. Callers supply a Policy, a clock.Clock, and an Op that returns either a value or a *failure.Failure. retry.Do handles the loop, the backoff scheduling, and the `details.retried = N` annotation on the final failure.

Index

• func Do[T any](ctx context.Context, p Policy, clk clock.Clock, op Op[T]) (T, *failure.Failure)
• type Op
• type Policy
  • func DefaultPolicy() Policy

Functions

func Do

func Do[T any](ctx context.Context, p Policy, clk clock.Clock, op Op[T]) (T, *failure.Failure)

Do runs op with the given retry policy. On a retriable failure it sleeps `BaseDelay << (attempt-1)` (with jitter), up to MaxRetries times, then returns the final failure with `details.retried = N` stamped on. Non-retriable failures return immediately. Successes return on the first non-failing attempt.

retriable predicate: only NetworkError or ExternalAPIError failures trip the retry path, and only when their Retriable() flag is true. Other classes — even ones marked retriable in their constructor — are left to the caller's policy. This keeps the retry surface narrow per ADR-0010's "the runtime retries `retriable` errors" language combined with the table that names the eligible classes.

Types

type Op

type Op[T any] func(ctx context.Context, attempt int) (T, *failure.Failure)

Op is the operation Do executes. attempt starts at 1 for the first call and increments per retry; useful for callers that want to observe the retry count for logging.

type Policy

type Policy struct {
	// MaxRetries is the upper bound on additional attempts after
	// the first one. ADR-0010 v1 default: 3.
	MaxRetries int

	// BaseDelay is the delay before the first retry. Subsequent
	// retries double from there.
	BaseDelay time.Duration

	// Jitter is the fractional jitter applied to each delay
	// (0.0 = none, 1.0 = up to 100% extra). Default: 0.2.
	Jitter float64
}

Policy controls how Do retries.

func DefaultPolicy

func DefaultPolicy() Policy

DefaultPolicy returns the v1 ADR-0010 default: 3 retries, 1s base delay, 20% jitter. Most callers should pass this; a few might tune jitter for deterministic tests.