Documentation
¶
Overview ¶
Package retry provides jittered exponential backoff for decorrelated retries. Inspired by Hermes Agent's retry_utils, this prevents thundering-herd retry spikes when multiple sessions hit the same rate-limited provider concurrently.
Package retry provides intelligent error classification and recovery strategies for long-running agent tasks. Inspired by Hermes Agent's error_classifier.
Index ¶
- func DecorrelatedJitter(attempt int, config ...BackoffConfig) time.Duration
- func FixedBackoff(delay time.Duration) time.Duration
- func JitteredBackoff(attempt int, config ...BackoffConfig) time.Duration
- func JitteredBackoffSeconds(attempt int, config ...BackoffConfig) float64
- func LinearBackoff(attempt int, baseDelay time.Duration, maxDelay time.Duration) time.Duration
- func RetryFunc(fn func() error, maxAttempts int, config ...BackoffConfig) error
- func RetryFuncWithResult[T any](fn func() (T, error), maxAttempts int, config ...BackoffConfig) (T, error)
- func RetryWithClassifier(fn func() error, classifier *Classifier, maxAttempts int, ...) error
- func SleepJittered(attempt int, config ...BackoffConfig)
- type BackoffConfig
- type BackoffStrategy
- type ClassifiedError
- type Classifier
- type ExponentialBackoff
- type FailoverReason
- type RecoveryStrategy
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecorrelatedJitter ¶ added in v0.4.11
func DecorrelatedJitter(attempt int, config ...BackoffConfig) time.Duration
DecorrelatedJitter provides an alternative jitter strategy that increases the jitter range with each attempt for better decorrelation.
func FixedBackoff ¶
FixedBackoff provides a fixed delay regardless of attempt number.
func JitteredBackoff ¶ added in v0.4.11
func JitteredBackoff(attempt int, config ...BackoffConfig) time.Duration
JitteredBackoff computes a jittered exponential backoff delay.
Args:
- attempt: 1-based retry attempt number.
- baseDelay: Base delay for attempt 1.
- maxDelay: Maximum delay cap.
- jitterRatio: Fraction of computed delay to use as random jitter range.
Returns:
- Delay in seconds: min(base * 2^(attempt-1), maxDelay) + jitter.
The jitter decorrelates concurrent retries so multiple sessions hitting the same provider don't all retry at the same instant.
func JitteredBackoffSeconds ¶ added in v0.4.11
func JitteredBackoffSeconds(attempt int, config ...BackoffConfig) float64
JitteredBackoffSeconds returns the backoff delay in seconds as a float64.
func LinearBackoff ¶
LinearBackoff provides a simple linear backoff without jitter. Useful when jitter is not desired.
func RetryFunc ¶ added in v0.4.11
func RetryFunc(fn func() error, maxAttempts int, config ...BackoffConfig) error
RetryFunc executes a function with jittered backoff retries. Returns the last error if all retries are exhausted.
func RetryFuncWithResult ¶ added in v0.4.11
func RetryFuncWithResult[T any](fn func() (T, error), maxAttempts int, config ...BackoffConfig) (T, error)
RetryFuncWithResult executes a function that returns a result with jittered backoff retries.
func RetryWithClassifier ¶ added in v0.4.11
func RetryWithClassifier(fn func() error, classifier *Classifier, maxAttempts int, config ...BackoffConfig) error
RetryWithClassifier executes a function with intelligent error classification and backoff. Uses the error classifier to determine if retries should continue.
func SleepJittered ¶ added in v0.4.11
func SleepJittered(attempt int, config ...BackoffConfig)
SleepJittered sleeps for the jittered backoff duration.
Types ¶
type BackoffConfig ¶ added in v0.4.11
type BackoffConfig struct {
BaseDelay time.Duration // Base delay for attempt 1 (default 5s)
MaxDelay time.Duration // Maximum delay cap (default 120s)
JitterRatio float64 // Fraction of delay for random jitter range (default 0.5)
MaxAttempts int // Maximum retry attempts (default 5)
ExponentialBase float64 // Exponential base (default 2.0)
}
BackoffConfig configures the backoff behavior.
func DefaultBackoffConfig ¶ added in v0.4.11
func DefaultBackoffConfig() BackoffConfig
DefaultBackoffConfig returns the default backoff configuration.
type BackoffStrategy ¶
type BackoffStrategy interface {
Backoff(attempt int) time.Duration
NextDelay(attempt int) time.Duration
}
BackoffStrategy defines the interface for backoff strategies. Used by internal/provider for retry configuration.
type ClassifiedError ¶ added in v0.4.11
type ClassifiedError struct {
Reason FailoverReason
StatusCode int
Provider string
Model string
Message string
ErrorContext map[string]interface{}
// Recovery action hints
Retryable bool
ShouldCompress bool
ShouldRotateCredential bool
ShouldFallback bool
ShouldAbort bool
}
ClassifiedError contains structured error classification with recovery hints.
func ClassifyError ¶ added in v0.4.11
func ClassifyError(err error, statusCode int, provider, model string) *ClassifiedError
ClassifyError analyzes an error and returns a structured classification.
func ClassifyWithContext ¶ added in v0.4.11
func ClassifyWithContext(ctx context.Context, err error, statusCode int, provider, model string) *ClassifiedError
Context-aware classification
func (*ClassifiedError) IsAuth ¶ added in v0.4.11
func (ce *ClassifiedError) IsAuth() bool
IsAuth returns true if this is an authentication error.
func (*ClassifiedError) IsRetryable ¶ added in v0.4.11
func (ce *ClassifiedError) IsRetryable() bool
IsRetryable returns true if this error is retryable.
func (*ClassifiedError) String ¶ added in v0.4.11
func (ce *ClassifiedError) String() string
String returns a human-readable description.
type Classifier ¶ added in v0.4.11
type Classifier struct {
// contains filtered or unexported fields
}
Classifier is a reusable error classifier with custom rules.
func NewClassifier ¶ added in v0.4.11
func NewClassifier() *Classifier
NewClassifier creates a new classifier.
func (*Classifier) AddRule ¶ added in v0.4.11
func (c *Classifier) AddRule(rule func(error, int, string, string) *ClassifiedError)
AddRule adds a custom classification rule.
func (*Classifier) Classify ¶ added in v0.4.11
func (c *Classifier) Classify(err error, statusCode int, provider, model string) *ClassifiedError
Classify runs all rules and returns the first match, or falls back to default.
type ExponentialBackoff ¶
type ExponentialBackoff struct {
Base time.Duration // Base delay for first retry
Max time.Duration // Maximum delay cap
}
ExponentialBackoff implements a simple exponential backoff strategy.
type FailoverReason ¶ added in v0.4.11
type FailoverReason string
FailoverReason categorizes why an API call or tool execution failed. This determines the recovery strategy.
const ( // Authentication / authorization FailoverAuth FailoverReason = "auth" // Transient auth (401/403) — refresh/rotate FailoverAuthPermanent FailoverReason = "auth_permanent" // Auth failed after refresh — abort // Billing / quota FailoverBilling FailoverReason = "billing" // 402 or credit exhaustion — rotate immediately FailoverRateLimit FailoverReason = "rate_limit" // 429 or throttling — backoff then rotate // Server-side FailoverOverloaded FailoverReason = "overloaded" // 503/529 — provider overloaded, backoff FailoverServerError FailoverReason = "server_error" // 500/502 — internal error, retry // Transport FailoverTimeout FailoverReason = "timeout" // Connection/read timeout — rebuild + retry // Context / payload FailoverContextOverflow FailoverReason = "context_overflow" // Context too large — compress FailoverPayloadTooLarge FailoverReason = "payload_too_large" // 413 — compress payload FailoverImageTooLarge FailoverReason = "image_too_large" // Image exceeds limit — shrink // Model / provider policy FailoverModelNotFound FailoverReason = "model_not_found" // 404 or invalid model FailoverProviderPolicyBlocked FailoverReason = "provider_policy_blocked" // Policy blocked FailoverContentPolicyBlocked FailoverReason = "content_policy_blocked" // Safety filter // Request format FailoverFormatError FailoverReason = "format_error" // 400 bad request FailoverInvalidEncryptedContent FailoverReason = "invalid_encrypted_content" // Replay blob rejected // Catch-all FailoverUnknown FailoverReason = "unknown" // Unclassifiable — retry with backoff )
type RecoveryStrategy ¶ added in v0.4.11
type RecoveryStrategy struct {
Action string
Delay time.Duration
MaxRetries int
FallbackModel string
Compress bool
Abort bool
}
RecoveryStrategy defines how to recover from a classified error.
func GetRecoveryStrategy ¶ added in v0.4.11
func GetRecoveryStrategy(ce *ClassifiedError, attempt int) RecoveryStrategy
GetRecoveryStrategy returns the recommended recovery strategy for a classified error.
Source Files