resilience

type BackoffStrategy interface {
	// NextDelay returns the delay before the next retry attempt.
	// attempt is 1-indexed (first retry is attempt 1).
	NextDelay(attempt int) time.Duration

	// Reset resets the backoff state for a new operation.
	Reset()
}

type ConstantBackoff struct {
	// Delay is the constant delay between retries.
	Delay time.Duration
}

type DefaultClassifier struct{}

type ErrorCategory string

type ErrorClassifier interface {
	// Classify analyzes an error and returns its metadata.
	Classify(err error) ErrorInfo
}

type ErrorInfo struct {
	// Category classifies the error for handling decisions.
	Category ErrorCategory

	// Retryable indicates if the operation can be safely retried.
	Retryable bool

	// Code is a machine-readable error code (e.g., "RATE_LIMITED").
	Code string

	// Message is a human-readable error description.
	Message string

	// Suggestion provides guidance for error recovery.
	Suggestion string

	// RetryAfter hints how long to wait before retrying.
	// Zero means use default backoff strategy.
	RetryAfter time.Duration
}

type ExponentialBackoff struct {
	// Initial is the delay for the first retry (default: 1s).
	Initial time.Duration

	// Max is the maximum delay (default: 30s).
	Max time.Duration

	// Multiplier is the factor by which delay increases (default: 2.0).
	Multiplier float64

	// Jitter is the random factor applied to delays (0-1, default: 0.1).
	// A jitter of 0.1 means ±10% randomization.
	Jitter float64
}

type HTTPStatusClassifier struct{}

type LinearBackoff struct {
	// Initial is the delay for the first retry (default: 1s).
	Initial time.Duration

	// Increment is added for each subsequent attempt (default: 1s).
	Increment time.Duration

	// Max is the maximum delay (default: 30s).
	Max time.Duration
}

type NoBackoff struct{}

type ProviderError struct {
	// Provider is the name of the provider (e.g., "elevenlabs").
	Provider string

	// Op is the operation that failed (e.g., "Synthesize").
	Op string

	// Err is the underlying error.
	Err error

	// Info contains AX metadata about the error.
	Info ErrorInfo
}

type RetryConfig struct {
	// MaxAttempts is the maximum number of attempts (including initial).
	// Default: 3 (1 initial + 2 retries).
	MaxAttempts int

	// Backoff is the strategy for computing delays between retries.
	// Default: ExponentialBackoff with sensible defaults.
	Backoff BackoffStrategy

	// Classifier categorizes errors to determine retryability.
	// Default: DefaultClassifier.
	Classifier ErrorClassifier

	// RetryIf is an optional predicate for custom retry decisions.
	// If set, overrides the classifier's retryability decision.
	// Return true to retry, false to stop.
	RetryIf func(err error) bool

	// OnRetry is called before each retry attempt.
	// Can be used for logging or metrics.
	OnRetry func(attempt int, err error, delay time.Duration)
}

type RetryError struct {
	// Attempts is the number of attempts made.
	Attempts int

	// Err is the last error encountered.
	Err error
}