retry

Documentation

Overview

Package retry provides function execution with retry, exponential backoff, and random jitter: Backoff runs a call until it succeeds, its attempt budget is spent, or its context ends, sleeping between attempts with exponentially growing, jittered, hard-capped delays.

The delay before retry i (counting from 1) starts at Policy.BaseDelay and doubles each retry, capped at Policy.MaxDelay; Policy.Jitter then spreads it uniformly over ±Jitter of its value (still never above MaxDelay), so simultaneous failers do not retry in lockstep. Backoff is a pure function with no shared state — it owns no goroutines and is safe for concurrent use. Design decisions are recorded in ADR-0011.

Index

• func Backoff(ctx context.Context, policy Policy, fn func(context.Context) error) error
• type Policy

Functions

func Backoff

func Backoff(ctx context.Context, policy Policy, fn func(context.Context) error) error

Backoff runs fn under policy until it returns nil, the attempt budget is spent, or ctx ends. It returns nil on the first success; the last error fn returned, verbatim, when MaxAttempts calls all failed (wrap fn to classify errors — Backoff never inspects them); or ctx.Err() when ctx ends before the first call or during a between-attempt sleep. fn receives ctx unchanged. A nil fn or an invalid policy panics — both are programming errors, not runtime conditions.

Types

type Policy

type Policy struct {
	// MaxAttempts is the total number of times fn may run, counting the
	// first call: 1 means no retry. Must be > 0.
	MaxAttempts int

	// BaseDelay is the pre-jitter delay before the first retry; each further
	// retry doubles it. Zero means immediate retries. Must be >= 0.
	BaseDelay time.Duration

	// MaxDelay is the hard cap: no sleep, jittered or not, ever exceeds it.
	// Must be >= BaseDelay.
	MaxDelay time.Duration

	// Jitter is the fraction of each delay used as the jitter half-range: a
	// delay d becomes uniform in [d*(1-Jitter), d*(1+Jitter)], then is
	// re-capped at MaxDelay. Zero disables jitter. Must be in [0, 1].
	Jitter float64
	// contains filtered or unexported fields
}

Policy configures Backoff. The zero value is not usable: MaxAttempts must be at least 1.