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//! - **Budget:** `max_attempts` **and** `max_elapsed_ms` are enforced together;
15//!   a sleep that would exceed the elapsed budget aborts retry (no partial
16//!   sleep then fail).
17//!
18//! # Delay formula
19//!
20//! ```text
21//! cap(n)  = min(base_ms * 2^min(n, 16), max_delay_ms)
22//! delay   = uniform(0..=cap)   // full jitter (AWS Architecture Blog)
23//! ```
24//!
25//! Monotonic clock: sleeps use `tokio::time::sleep` (not `SystemTime`).
26//! `Retry-After` (delta-seconds **or** HTTP-date via `httpdate`) overrides the
27//! formula for 429/503 when present. Past HTTP-dates within 1s skew → zero wait;
28//! older past dates fall back to the formula.
29//!
30//! # Out of scope (one-shot agent CLI)
31//!
32//! Circuit breaker, retry budget token-bucket, hedged requests, gRPC,
33//! OAuth refresh, outbox/saga, multi-host sticky sessions.
34
35use std::collections::hash_map::DefaultHasher;
36use std::hash::{Hash, Hasher};
37use std::time::{Duration, Instant, SystemTime};
38
39use reqwest::StatusCode;
40use reqwest::header::HeaderMap;
41
42use crate::config::Config;
43
44/// Default maximum retries after the first attempt (total attempts = N+1).
45pub const DEFAULT_MAX_RETRIES: u32 = 3;
46/// Default base backoff in milliseconds (also minimum floor for formula).
47pub const DEFAULT_RETRY_BASE_MS: u64 = 200;
48/// Default ceiling for a single backoff sleep (milliseconds).
49pub const DEFAULT_RETRY_MAX_DELAY_MS: u64 = 30_000;
50/// Hard cap on configured retries (prevents accidental retry storms).
51pub const HARD_MAX_RETRIES: u32 = 10;
52/// Hard ceiling for a single delay (milliseconds).
53pub const HARD_MAX_DELAY_MS: u64 = 60_000;
54/// Minimum allowed base delay (Rules Rust: never below 50ms in production config).
55pub const MIN_RETRY_BASE_MS: u64 = 50;
56/// Hard ceiling for total retry wall time including sleeps (milliseconds).
57pub const HARD_MAX_ELAPSED_MS: u64 = 300_000;
58/// Default total retry budget when not overridden (`0` in config = derive from timeout).
59/// Used only when `timeout_secs` is unavailable; production derives from wall timeout.
60pub const DEFAULT_RETRY_MAX_ELAPSED_MS: u64 = 30_000;
61/// Clock-skew tolerance for past HTTP-date `Retry-After` values.
62const RETRY_AFTER_SKEW_SECS: u64 = 1;
63
64/// Named retry policy for the product HTTP client (one dependency class).
65///
66/// Built from [`Config`] so CLI / TOML / env share one struct. Clone is cheap
67/// (`Copy`).
68#[derive(Debug, Clone, Copy, PartialEq, Eq)]
69pub struct RetryConfig {
70    /// Retries after the first attempt (`0` = single try).
71    pub max_retries: u32,
72    /// Exponential base delay in milliseconds.
73    pub base_ms: u64,
74    /// Maximum single sleep in milliseconds.
75    pub max_delay_ms: u64,
76    /// Total wall budget for the retry loop (attempts + sleeps), milliseconds.
77    pub max_elapsed_ms: u64,
78    /// Kill switch: when false, never retries.
79    pub enabled: bool,
80}
81
82impl RetryConfig {
83    /// Resolve policy from runtime config (clamped).
84    ///
85    /// Coherence: `base_ms ≥ MIN_RETRY_BASE_MS`, `max_delay ≥ base`,
86    /// `max_elapsed ≥ max_delay` (or wall timeout when config field is `0`).
87    pub fn from_config(cfg: &Config) -> Self {
88        let max_retries = cfg.max_retries.min(HARD_MAX_RETRIES);
89        let base_ms = if cfg.retry_base_ms == 0 {
90            DEFAULT_RETRY_BASE_MS
91        } else {
92            cfg.retry_base_ms.max(MIN_RETRY_BASE_MS)
93        };
94        let max_delay_ms = cfg.retry_max_delay_ms.min(HARD_MAX_DELAY_MS).max(base_ms);
95        // `0` means derive from wall-clock timeout (one-shot: retries must not
96        // outlive the operation deadline).
97        let derived = cfg.timeout_secs.saturating_mul(1000).max(1_000);
98        let max_elapsed_ms = if cfg.retry_max_elapsed_ms == 0 {
99            derived.min(HARD_MAX_ELAPSED_MS)
100        } else {
101            cfg.retry_max_elapsed_ms
102                .min(HARD_MAX_ELAPSED_MS)
103                .max(max_delay_ms)
104        };
105        let enabled = !cfg.disable_retry && max_retries > 0;
106        Self {
107            max_retries,
108            base_ms,
109            max_delay_ms,
110            max_elapsed_ms,
111            enabled,
112        }
113    }
114
115    /// Total attempts including the first try.
116    pub fn max_attempts(self) -> u32 {
117        if !self.enabled {
118            1
119        } else {
120            self.max_retries.saturating_add(1)
121        }
122    }
123
124    /// Whether another attempt is allowed after `attempt` (1-based completed count).
125    pub fn may_retry(self, attempt: u32) -> bool {
126        self.enabled && attempt < self.max_attempts()
127    }
128
129    /// Whether another attempt is allowed given attempt count **and** elapsed budget.
130    ///
131    /// Rules: combine `max_attempts` and `max_elapsed_time`. A planned wait that
132    /// would exceed the remaining budget aborts retry (no sleep past budget).
133    pub fn may_retry_within_budget(
134        self,
135        attempt: u32,
136        elapsed: Duration,
137        planned_wait: Duration,
138    ) -> bool {
139        if !self.may_retry(attempt) {
140            return false;
141        }
142        let budget = Duration::from_millis(self.max_elapsed_ms);
143        if elapsed >= budget {
144            return false;
145        }
146        let remaining = budget.saturating_sub(elapsed);
147        planned_wait <= remaining
148    }
149
150    /// Remaining time in the elapsed budget (zero when exhausted).
151    pub fn remaining_budget(self, elapsed: Duration) -> Duration {
152        Duration::from_millis(self.max_elapsed_ms).saturating_sub(elapsed)
153    }
154
155    /// Full-jitter delay for this attempt number (1-based).
156    pub fn delay_for_attempt(self, attempt: u32) -> Duration {
157        backoff_full_jitter(self.base_ms, attempt, self.max_delay_ms)
158    }
159}
160
161impl Default for RetryConfig {
162    fn default() -> Self {
163        Self {
164            max_retries: DEFAULT_MAX_RETRIES,
165            base_ms: DEFAULT_RETRY_BASE_MS,
166            max_delay_ms: DEFAULT_RETRY_MAX_DELAY_MS,
167            max_elapsed_ms: DEFAULT_RETRY_MAX_ELAPSED_MS,
168            enabled: true,
169        }
170    }
171}
172
173/// Classification of an HTTP status for the retry gate.
174#[derive(Debug, Clone, Copy, PartialEq, Eq)]
175pub enum RetryClass {
176    /// Do not retry (4xx client errors, success, unknown permanent).
177    Permanent,
178    /// Retry with exponential full-jitter backoff (5xx / 408).
179    Transient,
180    /// Retry respecting optional `Retry-After` (429, and 503 with header).
181    RateLimited {
182        /// Parsed `Retry-After` delta-seconds or HTTP-date delta when present.
183        retry_after: Option<Duration>,
184    },
185}
186
187/// Detailed retry category exposed on errors (Rules checklist `retry_kind`).
188#[derive(Debug, Clone, Copy, PartialEq, Eq)]
189pub enum RetryKind {
190    /// Never auto-retry (validation, 4xx, parse, budget, cancel).
191    Permanent,
192    /// Transport / connect failure (may retry).
193    TransientNetwork,
194    /// Remote 5xx / temporary unavailability (may retry).
195    TransientServer,
196    /// HTTP 429 with optional `Retry-After` (may retry).
197    RateLimited,
198    /// Wall or request timeout (may retry).
199    Timeout,
200}
201
202/// Transport / protocol layer of a failure (Rules checklist `ErrorLayer`).
203///
204/// Reqwest/hyper does not always separate DNS from TCP or TLS handshake from
205/// connect; `TcpConnect` covers DNS+TCP+TLS establishment when only
206/// `is_connect()` is available.
207#[derive(Debug, Clone, Copy, PartialEq, Eq)]
208pub enum ErrorLayer {
209    /// Name resolution (when distinguishable; else folded into [`Self::TcpConnect`]).
210    Dns,
211    /// TCP connect / peer unreachable (includes DNS when not separated).
212    TcpConnect,
213    /// TLS handshake failure (when distinguishable).
214    Tls,
215    /// HTTP/1.1 or HTTP/2 protocol error after connect.
216    HttpProtocol,
217    /// HTTP status from a completed response.
218    HttpStatus,
219    /// Application / parse / budget after a successful body read.
220    Application,
221    /// Unclassified.
222    Unknown,
223}
224
225impl ErrorLayer {
226    /// Stable snake_case label for logs and doctor detail.
227    pub fn as_str(self) -> &'static str {
228        match self {
229            Self::Dns => "dns",
230            Self::TcpConnect => "tcp_connect",
231            Self::Tls => "tls",
232            Self::HttpProtocol => "http_protocol",
233            Self::HttpStatus => "http_status",
234            Self::Application => "application",
235            Self::Unknown => "unknown",
236        }
237    }
238}
239
240impl RetryKind {
241    /// Stable snake_case label.
242    pub fn as_str(self) -> &'static str {
243        match self {
244            Self::Permanent => "permanent",
245            Self::TransientNetwork => "transient_network",
246            Self::TransientServer => "transient_server",
247            Self::RateLimited => "rate_limited",
248            Self::Timeout => "timeout",
249        }
250    }
251
252    /// Whether this kind is eligible for in-process or agent retry.
253    pub fn is_retryable(self) -> bool {
254        !matches!(self, Self::Permanent)
255    }
256}
257
258/// Classify HTTP status for in-process retry (GET-only product).
259pub fn classify_http_status(status: StatusCode, retry_after: Option<Duration>) -> RetryClass {
260    match status.as_u16() {
261        429 => RetryClass::RateLimited { retry_after },
262        // 408 Request Timeout — transient by design (client may retry).
263        408 | 500 | 502 | 504 => RetryClass::Transient,
264        // 503: prefer Retry-After when present (same as many CDNs).
265        503 => {
266            if retry_after.is_some() {
267                RetryClass::RateLimited { retry_after }
268            } else {
269                RetryClass::Transient
270            }
271        }
272        // Success and permanent client / other statuses: never retry.
273        _ => RetryClass::Permanent,
274    }
275}
276
277/// True when any error in the source chain is a [`rustls::Error`].
278///
279/// Does not string-match messages (Rules Rust — classification). When hyper
280/// folds TLS into a plain connect I/O error without a rustls source, the
281/// caller still reports [`ErrorLayer::TcpConnect`] (documented fold).
282pub(crate) fn source_chain_has_rustls(err: &(dyn std::error::Error + 'static)) -> bool {
283    let mut cur: Option<&(dyn std::error::Error + 'static)> = Some(err);
284    while let Some(e) = cur {
285        if e.downcast_ref::<rustls::Error>().is_some() {
286            return true;
287        }
288        cur = e.source();
289    }
290    false
291}
292
293/// Classify a reqwest transport error without string-matching messages.
294///
295/// Returns `(app ErrorKind, layer, in_process_retryable)`.
296///
297/// When a [`rustls::Error`] appears in the source chain, the layer is
298/// [`ErrorLayer::Tls`] even if reqwest also flags timeout/connect/request
299/// (prefer precise TLS labeling for agent diagnostics).
300pub fn classify_reqwest_error(err: &reqwest::Error) -> (crate::error::ErrorKind, ErrorLayer, bool) {
301    use crate::error::ErrorKind;
302
303    let tls = source_chain_has_rustls(err as &(dyn std::error::Error + 'static));
304
305    if err.is_timeout() {
306        // Connect or total timeout — both are transient for GET.
307        let layer = if tls {
308            ErrorLayer::Tls
309        } else {
310            ErrorLayer::TcpConnect
311        };
312        return (ErrorKind::Timeout, layer, true);
313    }
314    if tls {
315        // Handshake / cert validation failures when discriminable via rustls.
316        return (ErrorKind::Network, ErrorLayer::Tls, true);
317    }
318    if err.is_connect() {
319        // Hyper folds DNS + TCP (+ often TLS without rustls source) into connect.
320        return (ErrorKind::Network, ErrorLayer::TcpConnect, true);
321    }
322    if err.is_request() {
323        // Protocol / request construction / HTTP/2 stream issues after dial.
324        return (ErrorKind::Network, ErrorLayer::HttpProtocol, true);
325    }
326    if err.is_body() || err.is_decode() {
327        // Incomplete body after headers — rare; treat as network, non-retry in
328        // send path (body path is separate). Keep retryable=false here.
329        return (ErrorKind::Network, ErrorLayer::HttpProtocol, false);
330    }
331    (ErrorKind::Network, ErrorLayer::Unknown, false)
332}
333
334/// Parse `Retry-After` as **delta-seconds** or **HTTP-date** (RFC 7231).
335///
336/// - Pure non-negative integer → seconds (capped at [`HARD_MAX_DELAY_MS`]).
337/// - IMF-fixdate via `httpdate` → duration until that instant.
338/// - Past date within [`RETRY_AFTER_SKEW_SECS`] → `Duration::ZERO`.
339/// - Older past date or unparseable → `None` (caller falls back to formula).
340pub fn parse_retry_after(headers: &HeaderMap) -> Option<Duration> {
341    let raw = headers
342        .get(reqwest::header::RETRY_AFTER)
343        .and_then(|v| v.to_str().ok())?
344        .trim();
345    if raw.is_empty() {
346        return None;
347    }
348    // Delta-seconds (preferred when the value is purely numeric).
349    if raw.bytes().all(|b| b.is_ascii_digit()) {
350        let secs: u64 = raw.parse().ok()?;
351        return Some(Duration::from_secs(secs.min(HARD_MAX_DELAY_MS / 1000)));
352    }
353    // HTTP-date form.
354    let when = httpdate::parse_http_date(raw).ok()?;
355    let now = SystemTime::now();
356    match when.duration_since(now) {
357        Ok(d) => Some(d.min(Duration::from_millis(HARD_MAX_DELAY_MS))),
358        Err(e) => {
359            // Clock skew: slightly past → treat as immediate; deep past → formula.
360            if e.duration() <= Duration::from_secs(RETRY_AFTER_SKEW_SECS) {
361                Some(Duration::ZERO)
362            } else {
363                None
364            }
365        }
366    }
367}
368
369/// Full jitter: `uniform(0..=min(base*2^attempt, max_delay))`.
370///
371/// Entropy from monotonic `Instant` + stack address (no `rand` dependency).
372/// Not cryptographic; sufficient to desynchronize multi-agent thundering herds.
373/// For deterministic tests use [`backoff_full_jitter_seeded`].
374pub fn backoff_full_jitter(base_ms: u64, attempt: u32, max_delay_ms: u64) -> Duration {
375    let seed = mix_u64(attempt);
376    backoff_full_jitter_seeded(base_ms, attempt, max_delay_ms, seed)
377}
378
379/// Full jitter with explicit seed (tests / property checks).
380pub fn backoff_full_jitter_seeded(
381    base_ms: u64,
382    attempt: u32,
383    max_delay_ms: u64,
384    seed: u64,
385) -> Duration {
386    let base = base_ms.max(1);
387    let max_delay = max_delay_ms.max(base);
388    // Saturating shift: attempt capped so 2^n fits in u64 comfortably.
389    let exp = base.saturating_mul(1u64 << attempt.min(16));
390    let cap = exp.min(max_delay);
391    let pick = seed % (cap.saturating_add(1));
392    Duration::from_millis(pick)
393}
394
395/// Per-host politeness delay with additive jitter (never below the configured floor).
396///
397/// ```text
398/// effective = base + uniform(0..=base/5)   // up to +20% jitter
399/// ```
400///
401/// Keeps the operator-configured minimum interval (crawl-delay style floor) while
402/// avoiding synchronized multi-process hits that a fixed sleep would create.
403/// Zero base stays zero (tests / `--rate-limit-delay-ms 0`).
404pub fn politeness_delay(base: Duration) -> Duration {
405    let base_ms = base.as_millis() as u64;
406    if base_ms == 0 {
407        return Duration::ZERO;
408    }
409    let span = (base_ms / 5).max(1);
410    let extra = mix_u64(base_ms as u32) % (span.saturating_add(1));
411    Duration::from_millis(base_ms.saturating_add(extra))
412}
413
414/// Prefer server `Retry-After` when present; otherwise full-jitter formula.
415///
416/// Server hint is honored without additional jitter and **without** shrinking
417/// below the server value via `max_delay_ms` (Rules: never impose a shorter
418/// backoff than `Retry-After`). Only the hard delay ceiling applies; the
419/// elapsed budget gate in the HTTP loop refuses waits that would overrun
420/// `max_elapsed_ms`.
421pub fn wait_for_retry(
422    policy: RetryConfig,
423    attempt: u32,
424    retry_after: Option<Duration>,
425) -> Duration {
426    if let Some(d) = retry_after {
427        return d.min(Duration::from_millis(HARD_MAX_DELAY_MS));
428    }
429    policy.delay_for_attempt(attempt)
430}
431
432fn mix_u64(attempt: u32) -> u64 {
433    let mut h = DefaultHasher::new();
434    Instant::now().hash(&mut h);
435    attempt.hash(&mut h);
436    std::thread::current().id().hash(&mut h);
437    // Stack address mixes per-call entropy without a global RNG.
438    let marker = &h as *const DefaultHasher as usize;
439    marker.hash(&mut h);
440    h.finish()
441}
442
443#[cfg(test)]
444mod tests {
445    use super::*;
446    use reqwest::header::{HeaderValue, RETRY_AFTER};
447
448    #[test]
449    fn max_attempts_respects_kill_switch() {
450        let mut p = RetryConfig::default();
451        assert_eq!(p.max_attempts(), 4);
452        p.enabled = false;
453        assert_eq!(p.max_attempts(), 1);
454        assert!(!p.may_retry(1));
455    }
456
457    #[test]
458    fn from_config_disable_and_clamp() {
459        let cfg = Config {
460            disable_retry: true,
461            max_retries: 99,
462            retry_max_delay_ms: 999_999,
463            retry_base_ms: 10, // below MIN → raised
464            retry_max_elapsed_ms: 0, // derive from timeout
465            timeout_secs: 12,
466            ..Config::default()
467        };
468        let p = RetryConfig::from_config(&cfg);
469        assert!(!p.enabled);
470        assert_eq!(p.max_retries, HARD_MAX_RETRIES);
471        assert_eq!(p.max_delay_ms, HARD_MAX_DELAY_MS);
472        assert_eq!(p.base_ms, MIN_RETRY_BASE_MS);
473        assert_eq!(p.max_elapsed_ms, 12_000);
474        assert_eq!(p.max_attempts(), 1);
475    }
476
477    #[test]
478    fn from_config_explicit_max_elapsed() {
479        let cfg = Config {
480            retry_max_elapsed_ms: 5_000,
481            retry_base_ms: 200,
482            retry_max_delay_ms: 1_000,
483            ..Config::default()
484        };
485        let p = RetryConfig::from_config(&cfg);
486        assert_eq!(p.max_elapsed_ms, 5_000);
487    }
488
489    #[test]
490    fn may_retry_within_budget_blocks_oversleep() {
491        let p = RetryConfig {
492            max_retries: 5,
493            base_ms: 100,
494            max_delay_ms: 1_000,
495            max_elapsed_ms: 500,
496            enabled: true,
497        };
498        assert!(p.may_retry_within_budget(1, Duration::from_millis(0), Duration::from_millis(400)));
499        assert!(!p.may_retry_within_budget(1, Duration::from_millis(0), Duration::from_millis(600)));
500        assert!(!p.may_retry_within_budget(1, Duration::from_millis(500), Duration::ZERO));
501    }
502
503    #[test]
504    fn backoff_respects_cap() {
505        let d = backoff_full_jitter(200, 20, 1_000);
506        assert!(d.as_millis() <= 1_000);
507    }
508
509    #[test]
510    fn backoff_seeded_is_deterministic() {
511        let a = backoff_full_jitter_seeded(200, 3, 10_000, 42);
512        let b = backoff_full_jitter_seeded(200, 3, 10_000, 42);
513        assert_eq!(a, b);
514        // Property: always ≤ cap for any seed.
515        for seed in 0..64u64 {
516            for attempt in 0..8u32 {
517                let d = backoff_full_jitter_seeded(100, attempt, 500, seed);
518                assert!(d.as_millis() <= 500);
519            }
520        }
521    }
522
523    #[test]
524    fn politeness_delay_zero_stays_zero() {
525        assert_eq!(politeness_delay(Duration::ZERO), Duration::ZERO);
526    }
527
528    #[test]
529    fn politeness_delay_never_below_floor() {
530        let base = Duration::from_millis(1000);
531        for _ in 0..32 {
532            let d = politeness_delay(base);
533            assert!(d >= base, "delay {d:?} below floor {base:?}");
534            // Floor + up to 20% (span = base/5).
535            assert!(
536                d <= base + Duration::from_millis(200),
537                "delay {d:?} above floor+20%"
538            );
539        }
540    }
541
542    #[test]
543    fn classify_matrix() {
544        assert_eq!(
545            classify_http_status(StatusCode::OK, None),
546            RetryClass::Permanent
547        );
548        assert_eq!(
549            classify_http_status(StatusCode::NOT_FOUND, None),
550            RetryClass::Permanent
551        );
552        assert_eq!(
553            classify_http_status(StatusCode::BAD_REQUEST, None),
554            RetryClass::Permanent
555        );
556        assert_eq!(
557            classify_http_status(StatusCode::INTERNAL_SERVER_ERROR, None),
558            RetryClass::Transient
559        );
560        assert_eq!(
561            classify_http_status(StatusCode::REQUEST_TIMEOUT, None),
562            RetryClass::Transient
563        );
564        assert_eq!(
565            classify_http_status(StatusCode::TOO_MANY_REQUESTS, Some(Duration::from_secs(2))),
566            RetryClass::RateLimited {
567                retry_after: Some(Duration::from_secs(2))
568            }
569        );
570        assert_eq!(
571            classify_http_status(
572                StatusCode::SERVICE_UNAVAILABLE,
573                Some(Duration::from_secs(1))
574            ),
575            RetryClass::RateLimited {
576                retry_after: Some(Duration::from_secs(1))
577            }
578        );
579        assert_eq!(
580            classify_http_status(StatusCode::SERVICE_UNAVAILABLE, None),
581            RetryClass::Transient
582        );
583        // Permanent auth / client errors never retry.
584        assert_eq!(
585            classify_http_status(StatusCode::UNAUTHORIZED, None),
586            RetryClass::Permanent
587        );
588        assert_eq!(
589            classify_http_status(StatusCode::FORBIDDEN, None),
590            RetryClass::Permanent
591        );
592        assert_eq!(
593            classify_http_status(StatusCode::UNPROCESSABLE_ENTITY, None),
594            RetryClass::Permanent
595        );
596    }
597
598    #[test]
599    fn parse_retry_after_seconds_and_http_date() {
600        let mut h = HeaderMap::new();
601        h.insert(RETRY_AFTER, HeaderValue::from_static("7"));
602        assert_eq!(parse_retry_after(&h), Some(Duration::from_secs(7)));
603
604        h.insert(RETRY_AFTER, HeaderValue::from_static(""));
605        assert_eq!(parse_retry_after(&h), None);
606
607        // Future HTTP-date (~2s) must parse to a short positive duration.
608        let future = SystemTime::now() + Duration::from_secs(2);
609        let http_date = httpdate::fmt_http_date(future);
610        h.insert(
611            RETRY_AFTER,
612            HeaderValue::from_str(&http_date).expect("http-date header"),
613        );
614        let d = parse_retry_after(&h).expect("HTTP-date Retry-After");
615        assert!(d <= Duration::from_secs(3), "got {d:?}");
616        assert!(d >= Duration::from_millis(500), "got {d:?}");
617
618        // Deep past HTTP-date → None (fall back to formula).
619        let past = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
620        let past_s = httpdate::fmt_http_date(past);
621        h.insert(
622            RETRY_AFTER,
623            HeaderValue::from_str(&past_s).expect("past http-date"),
624        );
625        assert_eq!(parse_retry_after(&h), None);
626    }
627
628    #[test]
629    fn wait_prefers_retry_after() {
630        let p = RetryConfig::default();
631        let w = wait_for_retry(p, 1, Some(Duration::from_secs(3)));
632        assert_eq!(w, Duration::from_secs(3));
633    }
634
635    #[test]
636    fn source_chain_detects_rustls_and_ignores_plain_io() {
637        let tls = rustls::Error::General("unit-test".into());
638        assert!(source_chain_has_rustls(&tls));
639        let io = std::io::Error::other("not tls");
640        assert!(!source_chain_has_rustls(&io));
641        assert_eq!(ErrorLayer::Tls.as_str(), "tls");
642    }
643
644    #[test]
645    fn retry_kind_labels() {
646        assert_eq!(RetryKind::Timeout.as_str(), "timeout");
647        assert!(RetryKind::TransientNetwork.is_retryable());
648        assert!(!RetryKind::Permanent.is_retryable());
649        assert_eq!(ErrorLayer::TcpConnect.as_str(), "tcp_connect");
650    }
651}