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