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::StatusCode;
36use reqwest::header::HeaderMap;
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.retry_max_delay_ms.min(HARD_MAX_DELAY_MS).max(base_ms);
77        let enabled = !cfg.disable_retry && max_retries > 0;
78        Self {
79            max_retries,
80            base_ms,
81            max_delay_ms,
82            enabled,
83        }
84    }
85
86    /// Total attempts including the first try.
87    pub fn max_attempts(self) -> u32 {
88        if !self.enabled {
89            1
90        } else {
91            self.max_retries.saturating_add(1)
92        }
93    }
94
95    /// Whether another attempt is allowed after `attempt` (1-based completed count).
96    pub fn may_retry(self, attempt: u32) -> bool {
97        self.enabled && attempt < self.max_attempts()
98    }
99
100    /// Full-jitter delay for this attempt number (1-based).
101    pub fn delay_for_attempt(self, attempt: u32) -> Duration {
102        backoff_full_jitter(self.base_ms, attempt, self.max_delay_ms)
103    }
104}
105
106impl Default for RetryConfig {
107    fn default() -> Self {
108        Self {
109            max_retries: DEFAULT_MAX_RETRIES,
110            base_ms: DEFAULT_RETRY_BASE_MS,
111            max_delay_ms: DEFAULT_RETRY_MAX_DELAY_MS,
112            enabled: true,
113        }
114    }
115}
116
117/// Classification of an HTTP status for the retry gate.
118#[derive(Debug, Clone, Copy, PartialEq, Eq)]
119pub enum RetryClass {
120    /// Do not retry (4xx client errors, success, unknown permanent).
121    Permanent,
122    /// Retry with exponential full-jitter backoff (5xx).
123    Transient,
124    /// Retry respecting optional `Retry-After` (429, and 503 with header).
125    RateLimited {
126        /// Parsed `Retry-After` delta-seconds when present.
127        retry_after: Option<Duration>,
128    },
129}
130
131/// Classify HTTP status for in-process retry (GET-only product).
132pub fn classify_http_status(status: StatusCode, retry_after: Option<Duration>) -> RetryClass {
133    match status.as_u16() {
134        429 => RetryClass::RateLimited { retry_after },
135        500 | 502 | 504 => RetryClass::Transient,
136        // 503: prefer Retry-After when present (same as many CDNs).
137        503 => {
138            if retry_after.is_some() {
139                RetryClass::RateLimited { retry_after }
140            } else {
141                RetryClass::Transient
142            }
143        }
144        // Success and permanent client / other statuses: never retry.
145        _ => RetryClass::Permanent,
146    }
147}
148
149/// Parse `Retry-After` as **delta-seconds** only.
150///
151/// HTTP-date form is intentionally unsupported (no `chrono`/`httpdate` dep).
152/// Callers fall back to exponential backoff when this returns `None`.
153pub fn parse_retry_after(headers: &HeaderMap) -> Option<Duration> {
154    let raw = headers
155        .get(reqwest::header::RETRY_AFTER)
156        .and_then(|v| v.to_str().ok())?
157        .trim();
158    // Reject HTTP-date and empty: only pure non-negative integer seconds.
159    if raw.is_empty() || !raw.bytes().all(|b| b.is_ascii_digit()) {
160        return None;
161    }
162    let secs: u64 = raw.parse().ok()?;
163    // Cap pathological values (e.g. years) to hard max delay.
164    Some(Duration::from_secs(secs.min(HARD_MAX_DELAY_MS / 1000)))
165}
166
167/// Full jitter: `uniform(0..=min(base*2^attempt, max_delay))`.
168///
169/// Entropy from monotonic `Instant` + stack address (no `rand` dependency).
170/// Not cryptographic; sufficient to desynchronize multi-agent thundering herds.
171pub fn backoff_full_jitter(base_ms: u64, attempt: u32, max_delay_ms: u64) -> Duration {
172    let base = base_ms.max(1);
173    let max_delay = max_delay_ms.max(base);
174    // Saturating shift: attempt capped so 2^n fits in u64 comfortably.
175    let exp = base.saturating_mul(1u64 << attempt.min(16));
176    let cap = exp.min(max_delay);
177    let pick = mix_u64(attempt) % (cap.saturating_add(1));
178    Duration::from_millis(pick)
179}
180
181/// Per-host politeness delay with additive jitter (never below the configured floor).
182///
183/// ```text
184/// effective = base + uniform(0..=base/5)   // up to +20% jitter
185/// ```
186///
187/// Keeps the operator-configured minimum interval (crawl-delay style floor) while
188/// avoiding synchronized multi-process hits that a fixed sleep would create.
189/// Zero base stays zero (tests / `--rate-limit-delay-ms 0`).
190pub fn politeness_delay(base: Duration) -> Duration {
191    let base_ms = base.as_millis() as u64;
192    if base_ms == 0 {
193        return Duration::ZERO;
194    }
195    let span = (base_ms / 5).max(1);
196    let extra = mix_u64(base_ms as u32) % (span.saturating_add(1));
197    Duration::from_millis(base_ms.saturating_add(extra))
198}
199
200/// Prefer server `Retry-After` when present; otherwise full-jitter formula.
201pub fn wait_for_retry(
202    policy: RetryConfig,
203    attempt: u32,
204    retry_after: Option<Duration>,
205) -> Duration {
206    if let Some(d) = retry_after {
207        // Respect server hint but never sleep longer than hard ceiling.
208        return d.min(Duration::from_millis(policy.max_delay_ms));
209    }
210    policy.delay_for_attempt(attempt)
211}
212
213fn mix_u64(attempt: u32) -> u64 {
214    let mut h = DefaultHasher::new();
215    Instant::now().hash(&mut h);
216    attempt.hash(&mut h);
217    std::thread::current().id().hash(&mut h);
218    // Stack address mixes per-call entropy without a global RNG.
219    let marker = &h as *const DefaultHasher as usize;
220    marker.hash(&mut h);
221    h.finish()
222}
223
224#[cfg(test)]
225mod tests {
226    use super::*;
227    use reqwest::header::{HeaderValue, RETRY_AFTER};
228
229    #[test]
230    fn max_attempts_respects_kill_switch() {
231        let mut p = RetryConfig::default();
232        assert_eq!(p.max_attempts(), 4);
233        p.enabled = false;
234        assert_eq!(p.max_attempts(), 1);
235        assert!(!p.may_retry(1));
236    }
237
238    #[test]
239    fn from_config_disable_and_clamp() {
240        let cfg = Config {
241            disable_retry: true,
242            max_retries: 99,
243            retry_max_delay_ms: 999_999,
244            ..Config::default()
245        };
246        let p = RetryConfig::from_config(&cfg);
247        assert!(!p.enabled);
248        assert_eq!(p.max_retries, HARD_MAX_RETRIES);
249        assert_eq!(p.max_delay_ms, HARD_MAX_DELAY_MS);
250        assert_eq!(p.max_attempts(), 1);
251    }
252
253    #[test]
254    fn backoff_respects_cap() {
255        let d = backoff_full_jitter(200, 20, 1_000);
256        assert!(d.as_millis() <= 1_000);
257    }
258
259    #[test]
260    fn politeness_delay_zero_stays_zero() {
261        assert_eq!(politeness_delay(Duration::ZERO), Duration::ZERO);
262    }
263
264    #[test]
265    fn politeness_delay_never_below_floor() {
266        let base = Duration::from_millis(1000);
267        for _ in 0..32 {
268            let d = politeness_delay(base);
269            assert!(d >= base, "delay {d:?} below floor {base:?}");
270            // Floor + up to 20% (span = base/5).
271            assert!(
272                d <= base + Duration::from_millis(200),
273                "delay {d:?} above floor+20%"
274            );
275        }
276    }
277
278    #[test]
279    fn classify_matrix() {
280        assert_eq!(
281            classify_http_status(StatusCode::OK, None),
282            RetryClass::Permanent
283        );
284        assert_eq!(
285            classify_http_status(StatusCode::NOT_FOUND, None),
286            RetryClass::Permanent
287        );
288        assert_eq!(
289            classify_http_status(StatusCode::BAD_REQUEST, None),
290            RetryClass::Permanent
291        );
292        assert_eq!(
293            classify_http_status(StatusCode::INTERNAL_SERVER_ERROR, None),
294            RetryClass::Transient
295        );
296        assert_eq!(
297            classify_http_status(StatusCode::TOO_MANY_REQUESTS, Some(Duration::from_secs(2))),
298            RetryClass::RateLimited {
299                retry_after: Some(Duration::from_secs(2))
300            }
301        );
302        assert_eq!(
303            classify_http_status(
304                StatusCode::SERVICE_UNAVAILABLE,
305                Some(Duration::from_secs(1))
306            ),
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(
324            RETRY_AFTER,
325            HeaderValue::from_static("Wed, 21 Oct 2015 07:28:00 GMT"),
326        );
327        assert_eq!(parse_retry_after(&h), None);
328
329        h.insert(RETRY_AFTER, HeaderValue::from_static(""));
330        assert_eq!(parse_retry_after(&h), None);
331    }
332
333    #[test]
334    fn wait_prefers_retry_after() {
335        let p = RetryConfig::default();
336        let w = wait_for_retry(p, 1, Some(Duration::from_secs(3)));
337        assert_eq!(w, Duration::from_secs(3));
338    }
339}