retry

Documentation

Overview

Package retry provides a per-instance decorator over model.Model that owns the per-attempt deadline for every dispatch shape and retries ONLY genuinely transient post-load errors (ADR-0031 Decisions 4 and 5). It is built so it never fires for the cold-load case (F6): a per-attempt deadline expiry is non-retryable. The decorator mirrors the brain.WithModelID pattern (wrap, delegate, delegate Name()).

Index

• Constants
• func New(inner model.Model, cfg Config, opts ...Option) model.Model
• type Clock
• type Config
• type Option
  • func WithClock(c Clock) Option
  • func WithMetrics(m metrics.Metrics) Option
  • func WithRand(next func() float64) Option

Constants

const (
	// BackoffBase is the first backoff step; each retry doubles it.
	BackoffBase = 200 * time.Millisecond
	// MaxBackoffPerWait caps a single backoff wait (the exponential is clamped
	// here). Full jitter draws uniformly in [0, min(cap, base·2ⁿ)).
	MaxBackoffPerWait = 2 * time.Second
	// RetryAfterCap caps how long a 429's Retry-After hint may push a wait, so a
	// hostile or erroneous Retry-After cannot blow the derived ceiling. The wait
	// is further bounded at runtime by the remaining parent budget (FR-A2).
	RetryAfterCap = 30 * time.Second
)

Backoff schedule constants (ADR-0031 Decision 4, FR-B1/FR-A1). Exported so the app's ceiling derivation can budget the worst-case backoff (backoffBudget_i = MaxRetries_i × MaxBackoffPerWait, FR-A3).

Functions

func New

func New(inner model.Model, cfg Config, opts ...Option) model.Model

New builds a retry decorator over inner. Defaults: a real clock and math/rand/v2's Float64 for jitter, overridable via options for deterministic tests.

Types

type Clock

type Clock interface {
	Sleep(ctx context.Context, d time.Duration) error
}

Clock abstracts the backoff sleep so tests never wait in wall-clock time. Sleep must honor ctx: a cancel during the wait returns promptly with a non-nil error.

type Config

type Config struct {
	PerAttempt time.Duration
	MaxRetries int
}

Config holds the per-instance retry parameters resolved from config. PerAttempt is the per-attempt deadline (Config.EffectiveRequestTimeout); MaxRetries is the extra-attempt budget (0 disables retry — the decorator then still applies the per-attempt deadline, SV3).

type Option

type Option func(*decorator)

Option configures the decorator's test seams.

func WithClock

func WithClock(c Clock) Option

WithClock overrides the backoff clock (default: a real time-backed clock).

func WithMetrics

func WithMetrics(m metrics.Metrics) Option

WithMetrics injects the observability backend the decorator emits retry counters through (ADR-0031 sub-phase 7). Default: metrics.Nop{} (no emission). A nil argument is ignored, keeping the Nop default.

func WithRand

func WithRand(next func() float64) Option

WithRand overrides the full-jitter source, a func returning a fraction in [0,1) (default: math/rand/v2's concurrent-safe Float64).