retry

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package retry classifies provider failures as retryable or terminal and paces the re-attempts.

It exists because "is this worth retrying?" has to be answered identically in two places that cannot import each other: internal/provider, which retries a single failed HTTP request, and internal/agent, which retries a whole run.

The classification is deliberately message-based. Providers hand pi-go their failures as opaque strings — an SSE stream error is a JSON body, not a typed error — so pattern matching on the text is the only signal available at both layers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Delay

func Delay(cfg Config, attempt int, err error) time.Duration

Delay returns how long to wait before the given retry attempt (0-based).

A server-supplied hint wins over the configured schedule, since the server knows when its window reopens and we do not. An explicit cfg.Delays schedule wins over the exponential backoff. All three are clamped to cfg.MaxDelay so a provider cannot park a turn indefinitely.

func IsTerminal

func IsTerminal(err error) bool

IsTerminal reports whether err describes a failure that will recur identically however long the caller waits.

func IsTransient

func IsTransient(err error) bool

IsTransient reports whether err is worth retrying.

func Notify added in v0.0.76

func Notify(ctx context.Context, a Attempt)

Notify reports an imminent retry to the Notifier on ctx, if any. A nil ctx or a ctx without a notifier is a no-op, so retry loops can call this unconditionally.

func ServerDelay

func ServerDelay(err error) (time.Duration, bool)

ServerDelay extracts the wait the provider asked for, if it named one.

A rate-limit body usually carries the exact figure ("Please try again in 9.422s" from OpenAI, "Please retry in 59.440629838s" or a "retryDelay:59s" detail from Gemini), and honoring it is the difference between one well-timed retry and a backoff schedule that keeps landing inside the same exhausted window.

func WithNotifier added in v0.0.76

func WithNotifier(ctx context.Context, fn Notifier) context.Context

WithNotifier returns a context that carries fn to every retry loop run under it. Contexts are the only thing that travels from a front-end through the ADK runner down to the provider's HTTP call, which is why the hook rides on one rather than on a config struct.

Types

type Attempt added in v0.0.76

type Attempt struct {
	// Attempt is the 1-based number of the retry about to run.
	Attempt int
	// MaxRetries is the total retry budget, for "1/3"-style reporting.
	MaxRetries int
	// Delay is the pause before the retry is sent.
	Delay time.Duration
	// Err is the transient failure being retried.
	Err error
}

Attempt describes a retry that is about to be made: the failure that triggered it, which retry this is, and how long the caller will wait first.

func (Attempt) String added in v0.0.76

func (a Attempt) String() string

String renders the attempt as a one-line notice suitable for a status line or a transcript warning, e.g.

Retrying in 3s (1/3): read tcp 10.5.50.62:58742->104.18.2.115:443: read: can't assign requested address

type Config

type Config struct {
	// MaxRetries is the number of retries after the initial attempt.
	MaxRetries int

	// InitialDelay is the pause before the first retry.
	InitialDelay time.Duration

	// MaxDelay caps the exponential backoff, and also caps any delay the
	// server itself asked for.
	MaxDelay time.Duration

	// Delays, when set, is an explicit pause schedule that replaces the
	// exponential backoff: retry attempt n waits Delays[n], and attempts past
	// the end of the slice reuse its last entry. A server-supplied hint still
	// wins, and MaxDelay still caps the result.
	Delays []time.Duration
}

Config controls how many times a failed attempt is repeated and how long the pauses between attempts grow.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the shared defaults.

MaxDelay is a minute because the limits that produce a retryable 429 are per-minute windows: a shorter cap would guarantee the retry lands inside the same exhausted window it is waiting out.

type Notifier added in v0.0.76

type Notifier func(Attempt)

Notifier is told about each retry before the pause that precedes it. It is how a front-end shows "retrying…" while the provider re-sends a request that died underneath it; without one, retries are silent and a stalled stream is indistinguishable from a slow model.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL