Skip to main content

docsrs_cli/
retry.rs

1//! Explicit HTTP retry policy for crates.io / docs.rs (Rules Rust — retry/backoff).
2//!
3//! # Workload and policy scope
4//!
5//! - **Dependency:** public HTTPS hosts only (`crates.io`, `docs.rs`,
6//!   `static.docs.rs`, `doc.rust-lang.org`).
7//! - **Operations:** product surface is **GET-only** (idempotent by HTTP
8//!   semantics). No POST/PUT/DELETE; no Idempotency-Key required.
9//! - **Default:** retries **on** for transient failures (agent reliability).
10//!   Kill switch: `--disable-retry` / TOML `disable_retry = true` / `max_retries = 0`.
11//! - **Layer:** single retry loop inside [`crate::http::HttpClient`] only —
12//!   no middleware stack, no nested client retries, no agent-level auto-retry
13//!   of permanent kinds.
14//!
15//! # Delay formula
16//!
17//! ```text
18//! cap(n)  = min(base_ms * 2^min(n, 16), max_delay_ms)
19//! delay   = uniform(0..=cap)   // full jitter (AWS architecture blog)
20//! ```
21//!
22//! Relógio monotônico: sleeps usam `tokio::time::sleep` (não `SystemTime`).
23//! `Retry-After` delta-seconds overrides the formula for 429/503 when present.
24//! HTTP-date `Retry-After` is not parsed (no chrono dep); falls back to formula.
25//!
26//! # Out of scope (one-shot agent CLI)
27//!
28//! Circuit breaker, retry budget token-bucket, hedged requests, gRPC,
29//! OAuth refresh, outbox/saga, multi-host sticky sessions.
30
31use std::collections::hash_map::DefaultHasher;
32use std::hash::{Hash, Hasher};
33use std::time::{Duration, Instant};
34
35use reqwest::header::HeaderMap;
36use reqwest::StatusCode;
37
38use crate::config::Config;
39
40/// Default maximum retries after the first attempt (total attempts = N+1).
41pub const DEFAULT_MAX_RETRIES: u32 = 3;
42/// Default base backoff in milliseconds (also minimum floor for formula).
43pub const DEFAULT_RETRY_BASE_MS: u64 = 200;
44/// Default ceiling for a single backoff sleep (milliseconds).
45pub const DEFAULT_RETRY_MAX_DELAY_MS: u64 = 30_000;
46/// Hard cap on configured retries (prevents accidental retry storms).
47pub const HARD_MAX_RETRIES: u32 = 10;
48/// Hard ceiling for a single delay (milliseconds).
49pub const HARD_MAX_DELAY_MS: u64 = 60_000;
50
51/// Named retry policy for the product HTTP client (one dependency class).
52///
53/// Built from [`Config`] so CLI / TOML / env share one struct. Clone is cheap
54/// (`Copy`).
55#[derive(Debug, Clone, Copy, PartialEq, Eq)]
56pub struct RetryConfig {
57    /// Retries after the first attempt (`0` = single try).
58    pub max_retries: u32,
59    /// Exponential base delay in milliseconds.
60    pub base_ms: u64,
61    /// Maximum single sleep in milliseconds.
62    pub max_delay_ms: u64,
63    /// Kill switch: when false, never retries.
64    pub enabled: bool,
65}
66
67impl RetryConfig {
68    /// Resolve policy from runtime config (clamped).
69    pub fn from_config(cfg: &Config) -> Self {
70        let max_retries = cfg.max_retries.min(HARD_MAX_RETRIES);
71        let base_ms = if cfg.retry_base_ms == 0 {
72            DEFAULT_RETRY_BASE_MS
73        } else {
74            cfg.retry_base_ms
75        };
76        let max_delay_ms = cfg
77            .retry_max_delay_ms
78            .min(HARD_MAX_DELAY_MS)
79            .max(base_ms);
80        let enabled = !cfg.disable_retry && max_retries > 0;
81        Self {
82            max_retries,
83            base_ms,
84            max_delay_ms,
85            enabled,
86        }
87    }
88
89    /// Total attempts including the first try.
90    pub fn max_attempts(self) -> u32 {
91        if !self.enabled {
92            1
93        } else {
94            self.max_retries.saturating_add(1)
95        }
96    }
97
98    /// Whether another attempt is allowed after `attempt` (1-based completed count).
99    pub fn may_retry(self, attempt: u32) -> bool {
100        self.enabled && attempt < self.max_attempts()
101    }
102
103    /// Full-jitter delay for this attempt number (1-based).
104    pub fn delay_for_attempt(self, attempt: u32) -> Duration {
105        backoff_full_jitter(self.base_ms, attempt, self.max_delay_ms)
106    }
107}
108
109impl Default for RetryConfig {
110    fn default() -> Self {
111        Self {
112            max_retries: DEFAULT_MAX_RETRIES,
113            base_ms: DEFAULT_RETRY_BASE_MS,
114            max_delay_ms: DEFAULT_RETRY_MAX_DELAY_MS,
115            enabled: true,
116        }
117    }
118}
119
120/// Classification of an HTTP status for the retry gate.
121#[derive(Debug, Clone, Copy, PartialEq, Eq)]
122pub enum RetryClass {
123    /// Do not retry (4xx client errors, success, unknown permanent).
124    Permanent,
125    /// Retry with exponential full-jitter backoff (5xx).
126    Transient,
127    /// Retry respecting optional `Retry-After` (429, and 503 with header).
128    RateLimited {
129        /// Parsed `Retry-After` delta-seconds when present.
130        retry_after: Option<Duration>,
131    },
132}
133
134/// Classify HTTP status for in-process retry (GET-only product).
135pub fn classify_http_status(status: StatusCode, retry_after: Option<Duration>) -> RetryClass {
136    match status.as_u16() {
137        429 => RetryClass::RateLimited { retry_after },
138        500 | 502 | 504 => RetryClass::Transient,
139        // 503: prefer Retry-After when present (same as many CDNs).
140        503 => {
141            if retry_after.is_some() {
142                RetryClass::RateLimited { retry_after }
143            } else {
144                RetryClass::Transient
145            }
146        }
147        // Success and permanent client / other statuses: never retry.
148        _ => RetryClass::Permanent,
149    }
150}
151
152/// Parse `Retry-After` as **delta-seconds** only.
153///
154/// HTTP-date form is intentionally unsupported (no `chrono`/`httpdate` dep).
155/// Callers fall back to exponential backoff when this returns `None`.
156pub fn parse_retry_after(headers: &HeaderMap) -> Option<Duration> {
157    let raw = headers
158        .get(reqwest::header::RETRY_AFTER)
159        .and_then(|v| v.to_str().ok())?
160        .trim();
161    // Reject HTTP-date and empty: only pure non-negative integer seconds.
162    if raw.is_empty() || !raw.bytes().all(|b| b.is_ascii_digit()) {
163        return None;
164    }
165    let secs: u64 = raw.parse().ok()?;
166    // Cap pathological values (e.g. years) to hard max delay.
167    Some(Duration::from_secs(secs.min(HARD_MAX_DELAY_MS / 1000)))
168}
169
170/// Full jitter: `uniform(0..=min(base*2^attempt, max_delay))`.
171///
172/// Entropy from monotonic `Instant` + stack address (no `rand` dependency).
173/// Not cryptographic; sufficient to desynchronize multi-agent thundering herds.
174pub fn backoff_full_jitter(base_ms: u64, attempt: u32, max_delay_ms: u64) -> Duration {
175    let base = base_ms.max(1);
176    let max_delay = max_delay_ms.max(base);
177    // Saturating shift: attempt capped so 2^n fits in u64 comfortably.
178    let exp = base.saturating_mul(1u64 << attempt.min(16));
179    let cap = exp.min(max_delay);
180    let pick = mix_u64(attempt) % (cap.saturating_add(1));
181    Duration::from_millis(pick)
182}
183
184/// Per-host politeness delay with additive jitter (never below the configured floor).
185///
186/// ```text
187/// effective = base + uniform(0..=base/5)   // up to +20% jitter
188/// ```
189///
190/// Keeps the operator-configured minimum interval (crawl-delay style floor) while
191/// avoiding synchronized multi-process hits that a fixed sleep would create.
192/// Zero base stays zero (tests / `--rate-limit-delay-ms 0`).
193pub fn politeness_delay(base: Duration) -> Duration {
194    let base_ms = base.as_millis() as u64;
195    if base_ms == 0 {
196        return Duration::ZERO;
197    }
198    let span = (base_ms / 5).max(1);
199    let extra = mix_u64(base_ms as u32) % (span.saturating_add(1));
200    Duration::from_millis(base_ms.saturating_add(extra))
201}
202
203/// Prefer server `Retry-After` when present; otherwise full-jitter formula.
204pub fn wait_for_retry(
205    policy: RetryConfig,
206    attempt: u32,
207    retry_after: Option<Duration>,
208) -> Duration {
209    if let Some(d) = retry_after {
210        // Respect server hint but never sleep longer than hard ceiling.
211        return d.min(Duration::from_millis(policy.max_delay_ms));
212    }
213    policy.delay_for_attempt(attempt)
214}
215
216fn mix_u64(attempt: u32) -> u64 {
217    let mut h = DefaultHasher::new();
218    Instant::now().hash(&mut h);
219    attempt.hash(&mut h);
220    std::thread::current().id().hash(&mut h);
221    // Stack address mixes per-call entropy without a global RNG.
222    let marker = &h as *const DefaultHasher as usize;
223    marker.hash(&mut h);
224    h.finish()
225}
226
227#[cfg(test)]
228mod tests {
229    use super::*;
230    use reqwest::header::{HeaderValue, RETRY_AFTER};
231
232    #[test]
233    fn max_attempts_respects_kill_switch() {
234        let mut p = RetryConfig::default();
235        assert_eq!(p.max_attempts(), 4);
236        p.enabled = false;
237        assert_eq!(p.max_attempts(), 1);
238        assert!(!p.may_retry(1));
239    }
240
241    #[test]
242    fn from_config_disable_and_clamp() {
243        let cfg = Config {
244            disable_retry: true,
245            max_retries: 99,
246            retry_max_delay_ms: 999_999,
247            ..Config::default()
248        };
249        let p = RetryConfig::from_config(&cfg);
250        assert!(!p.enabled);
251        assert_eq!(p.max_retries, HARD_MAX_RETRIES);
252        assert_eq!(p.max_delay_ms, HARD_MAX_DELAY_MS);
253        assert_eq!(p.max_attempts(), 1);
254    }
255
256    #[test]
257    fn backoff_respects_cap() {
258        let d = backoff_full_jitter(200, 20, 1_000);
259        assert!(d.as_millis() <= 1_000);
260    }
261
262    #[test]
263    fn politeness_delay_zero_stays_zero() {
264        assert_eq!(politeness_delay(Duration::ZERO), Duration::ZERO);
265    }
266
267    #[test]
268    fn politeness_delay_never_below_floor() {
269        let base = Duration::from_millis(1000);
270        for _ in 0..32 {
271            let d = politeness_delay(base);
272            assert!(d >= base, "delay {d:?} below floor {base:?}");
273            // Floor + up to 20% (span = base/5).
274            assert!(
275                d <= base + Duration::from_millis(200),
276                "delay {d:?} above floor+20%"
277            );
278        }
279    }
280
281    #[test]
282    fn classify_matrix() {
283        assert_eq!(
284            classify_http_status(StatusCode::OK, None),
285            RetryClass::Permanent
286        );
287        assert_eq!(
288            classify_http_status(StatusCode::NOT_FOUND, None),
289            RetryClass::Permanent
290        );
291        assert_eq!(
292            classify_http_status(StatusCode::BAD_REQUEST, None),
293            RetryClass::Permanent
294        );
295        assert_eq!(
296            classify_http_status(StatusCode::INTERNAL_SERVER_ERROR, None),
297            RetryClass::Transient
298        );
299        assert_eq!(
300            classify_http_status(StatusCode::TOO_MANY_REQUESTS, Some(Duration::from_secs(2))),
301            RetryClass::RateLimited {
302                retry_after: Some(Duration::from_secs(2))
303            }
304        );
305        assert_eq!(
306            classify_http_status(StatusCode::SERVICE_UNAVAILABLE, Some(Duration::from_secs(1))),
307            RetryClass::RateLimited {
308                retry_after: Some(Duration::from_secs(1))
309            }
310        );
311        assert_eq!(
312            classify_http_status(StatusCode::SERVICE_UNAVAILABLE, None),
313            RetryClass::Transient
314        );
315    }
316
317    #[test]
318    fn parse_retry_after_seconds_only() {
319        let mut h = HeaderMap::new();
320        h.insert(RETRY_AFTER, HeaderValue::from_static("7"));
321        assert_eq!(parse_retry_after(&h), Some(Duration::from_secs(7)));
322
323        h.insert(RETRY_AFTER, HeaderValue::from_static("Wed, 21 Oct 2015 07:28:00 GMT"));
324        assert_eq!(parse_retry_after(&h), None);
325
326        h.insert(RETRY_AFTER, HeaderValue::from_static(""));
327        assert_eq!(parse_retry_after(&h), None);
328    }
329
330    #[test]
331    fn wait_prefers_retry_after() {
332        let p = RetryConfig::default();
333        let w = wait_for_retry(p, 1, Some(Duration::from_secs(3)));
334        assert_eq!(w, Duration::from_secs(3));
335    }
336}