Skip to main content

tea_kernel/
retry.rs

1use std::time::Duration;
2
3use tea_model::{ModelFailure, ModelFailureCode};
4use tea_protocol::RetryClass;
5
6use crate::{KernelError, KernelErrorCode};
7
8/// Maximum attempts a kernel run will retry a model request.
9pub const MAX_MODEL_RETRY_ATTEMPTS: u32 = 8;
10/// Maximum base delay for a model retry policy.
11pub const MAX_MODEL_RETRY_BASE_DELAY: Duration = Duration::from_secs(30);
12/// Maximum cap on model retry delays.
13pub const MAX_MODEL_RETRY_MAX_DELAY: Duration = Duration::from_mins(5);
14
15/// Deterministic provider-neutral model retry policy.
16///
17/// The policy is jitter-free for test determinism: `next_delay` is a pure
18/// exponential backoff `base * 2^(attempt-1)` capped at `max_delay`. Retries
19/// are bounded by `max_attempts`.
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub struct ModelRetryPolicy {
22    max_attempts: u32,
23    base_delay: Duration,
24    max_delay: Duration,
25}
26
27impl ModelRetryPolicy {
28    /// Creates a validated retry policy.
29    ///
30    /// # Errors
31    ///
32    /// Returns an error for zero attempts, zero base delay, a base greater than
33    /// max, or values above the supported bounds.
34    pub fn new(
35        max_attempts: u32,
36        base_delay: Duration,
37        max_delay: Duration,
38    ) -> Result<Self, KernelError> {
39        if max_attempts == 0
40            || max_attempts > MAX_MODEL_RETRY_ATTEMPTS
41            || base_delay.is_zero()
42            || base_delay > MAX_MODEL_RETRY_BASE_DELAY
43            || max_delay < base_delay
44            || max_delay > MAX_MODEL_RETRY_MAX_DELAY
45        {
46            return Err(KernelError::new(
47                KernelErrorCode::InvalidRequest,
48                "model retry policy is invalid",
49            ));
50        }
51        Ok(Self {
52            max_attempts,
53            base_delay,
54            max_delay,
55        })
56    }
57
58    /// Returns the maximum attempts including the first try.
59    #[must_use]
60    pub const fn max_attempts(self) -> u32 {
61        self.max_attempts
62    }
63    /// Returns the base backoff delay applied to the first retry.
64    #[must_use]
65    pub const fn base_delay(self) -> Duration {
66        self.base_delay
67    }
68    /// Returns the cap applied to every computed delay.
69    #[must_use]
70    pub const fn max_delay(self) -> Duration {
71        self.max_delay
72    }
73
74    /// Returns the deterministic delay to wait before the next attempt.
75    ///
76    /// `attempt` is 1-indexed: the first retry (attempt 1) waits `base_delay`.
77    #[must_use]
78    pub fn next_delay(self, attempt: u32) -> Duration {
79        if attempt == 0 {
80            return self.base_delay;
81        }
82        let exponent = attempt.min(20).saturating_sub(1);
83        let scaled = self
84            .base_delay
85            .checked_mul(2u32.saturating_pow(exponent))
86            .unwrap_or(self.max_delay);
87        scaled.min(self.max_delay)
88    }
89
90    /// Returns the bounded delay selected for one retryable failure.
91    ///
92    /// A provider-requested delay takes precedence over local exponential
93    /// backoff. Both sources are capped by `max_delay`.
94    #[must_use]
95    pub fn delay_for_failure(self, failure: &ModelFailure, attempt: u32) -> Duration {
96        failure
97            .retry_after()
98            .unwrap_or_else(|| self.next_delay(attempt))
99            .min(self.max_delay)
100    }
101
102    /// Returns the failure code when a retry is permitted, else `None`.
103    ///
104    /// `Never` failures (invalid request, auth, permission, malformed, or
105    /// cancellation) are never retried. `Immediate` and `AfterBackoff` failures
106    /// are retryable within the policy attempt bound; the caller checks the
107    /// attempt count separately.
108    #[must_use]
109    pub fn should_retry(self, failure: &ModelFailure) -> Option<ModelFailureCode> {
110        match failure.retry() {
111            RetryClass::Never => None,
112            RetryClass::Immediate | RetryClass::AfterBackoff => Some(failure.code()),
113        }
114    }
115}
116
117impl Default for ModelRetryPolicy {
118    fn default() -> Self {
119        Self {
120            max_attempts: 3,
121            base_delay: Duration::from_millis(500),
122            max_delay: Duration::from_secs(10),
123        }
124    }
125}