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 ¶
- func Delay(cfg Config, attempt int, err error) time.Duration
- func IsTerminal(err error) bool
- func IsTransient(err error) bool
- func Notify(ctx context.Context, a Attempt)
- func ServerDelay(err error) (time.Duration, bool)
- func WithNotifier(ctx context.Context, fn Notifier) context.Context
- type Attempt
- type Config
- type Notifier
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Delay ¶
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 ¶
IsTerminal reports whether err describes a failure that will recur identically however long the caller waits.
func IsTransient ¶
IsTransient reports whether err is worth retrying.
func Notify ¶ added in v0.0.76
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 ¶
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
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.
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.