Skip to main content

docsrs_cli/retry/
mod.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//!
35//! Layout (SRP): `config` (policy struct) · `classify` (status / transport /
36//! `Retry-After`) · `backoff` (jitter formulas and wait selection).
37
38mod backoff;
39mod classify;
40mod config;
41
42pub use backoff::{
43    backoff_full_jitter, backoff_full_jitter_seeded, politeness_delay, wait_for_retry,
44};
45pub use classify::{
46    ErrorLayer, RetryClass, RetryKind, classify_http_status, classify_reqwest_error,
47    parse_retry_after,
48};
49pub use config::RetryConfig;
50
51/// Default maximum retries after the first attempt (total attempts = N+1).
52pub const DEFAULT_MAX_RETRIES: u32 = 3;
53/// Default base backoff in milliseconds (also minimum floor for formula).
54pub const DEFAULT_RETRY_BASE_MS: u64 = 200;
55/// Default ceiling for a single backoff sleep (milliseconds).
56pub const DEFAULT_RETRY_MAX_DELAY_MS: u64 = 30_000;
57/// Hard cap on configured retries (prevents accidental retry storms).
58pub const HARD_MAX_RETRIES: u32 = 10;
59/// Hard ceiling for a single delay (milliseconds).
60pub const HARD_MAX_DELAY_MS: u64 = 60_000;
61/// Minimum allowed base delay (Rules Rust: never below 50ms in production config).
62pub const MIN_RETRY_BASE_MS: u64 = 50;
63/// Hard ceiling for total retry wall time including sleeps (milliseconds).
64pub const HARD_MAX_ELAPSED_MS: u64 = 300_000;
65/// Seconds-to-milliseconds factor for the two places retry crosses units.
66///
67/// Named so the direction of the conversion is readable at the call site: a
68/// bare `1000` reads the same whether it multiplies or divides.
69pub const MILLIS_PER_SECOND: u64 = 1_000;
70/// Floor for the retry budget derived from `timeout_secs` (milliseconds).
71///
72/// `timeout_secs` is a whole number, so any sub-second intent collapses to `0`
73/// and would leave the budget exhausted before the first attempt could sleep.
74/// One second is the smallest window in which a single retry is still possible.
75pub const MIN_DERIVED_ELAPSED_MS: u64 = 1_000;
76/// Default total retry budget when not overridden (`0` in config = derive from timeout).
77/// Used only when `timeout_secs` is unavailable; production derives from wall timeout.
78pub const DEFAULT_RETRY_MAX_ELAPSED_MS: u64 = 30_000;
79
80#[cfg(test)]
81mod tests;