Expand description
Explicit HTTP retry policy for crates.io / docs.rs (Rules Rust — retry/backoff).
§Workload and policy scope
- Dependency: public HTTPS hosts only (
crates.io,docs.rs,static.docs.rs,doc.rust-lang.org). - Operations: product surface is GET-only (idempotent by HTTP semantics). No POST/PUT/DELETE; no Idempotency-Key required.
- Default: retries on for transient failures (agent reliability).
Kill switch:
--disable-retry/ TOMLdisable_retry = true/max_retries = 0. - Layer: single retry loop inside
crate::http::HttpClientonly — no middleware stack, no nested client retries, no agent-level auto-retry of permanent kinds. - Budget:
max_attemptsandmax_elapsed_msare enforced together; a sleep that would exceed the elapsed budget aborts retry (no partial sleep then fail).
§Delay formula
cap(n) = min(base_ms * 2^min(n, 16), max_delay_ms)
delay = uniform(0..=cap) // full jitter (AWS Architecture Blog)Monotonic clock: sleeps use tokio::time::sleep (not SystemTime).
Retry-After (delta-seconds or HTTP-date via httpdate) overrides the
formula for 429/503 when present. Past HTTP-dates within 1s skew → zero wait;
older past dates fall back to the formula.
§Out of scope (one-shot agent CLI)
Circuit breaker, retry budget token-bucket, hedged requests, gRPC, OAuth refresh, outbox/saga, multi-host sticky sessions.
Layout (SRP): config (policy struct) · classify (status / transport /
Retry-After) · backoff (jitter formulas and wait selection).
Structs§
- Retry
Config - Named retry policy for the product HTTP client (one dependency class).
Enums§
- Error
Layer - Transport / protocol layer of a failure (Rules checklist
ErrorLayer). - Retry
Class - Classification of an HTTP status for the retry gate.
- Retry
Kind - Detailed retry category exposed on errors (Rules checklist
retry_kind).
Constants§
- DEFAULT_
MAX_ RETRIES - Default maximum retries after the first attempt (total attempts = N+1).
- DEFAULT_
RETRY_ BASE_ MS - Default base backoff in milliseconds (also minimum floor for formula).
- DEFAULT_
RETRY_ MAX_ DELAY_ MS - Default ceiling for a single backoff sleep (milliseconds).
- DEFAULT_
RETRY_ MAX_ ELAPSED_ MS - Default total retry budget when not overridden (
0in config = derive from timeout). Used only whentimeout_secsis unavailable; production derives from wall timeout. - HARD_
MAX_ DELAY_ MS - Hard ceiling for a single delay (milliseconds).
- HARD_
MAX_ ELAPSED_ MS - Hard ceiling for total retry wall time including sleeps (milliseconds).
- HARD_
MAX_ RETRIES - Hard cap on configured retries (prevents accidental retry storms).
- MILLIS_
PER_ SECOND - Seconds-to-milliseconds factor for the two places retry crosses units.
- MIN_
DERIVED_ ELAPSED_ MS - Floor for the retry budget derived from
timeout_secs(milliseconds). - MIN_
RETRY_ BASE_ MS - Minimum allowed base delay (Rules Rust: never below 50ms in production config).
Functions§
- backoff_
full_ jitter - Full jitter:
uniform(0..=min(base*2^attempt, max_delay)). - backoff_
full_ jitter_ seeded - Full jitter with explicit seed (tests / property checks).
- classify_
http_ status - Classify HTTP status for in-process retry (GET-only product).
- classify_
reqwest_ error - Classify a reqwest transport error without string-matching messages.
- parse_
retry_ after - Parse
Retry-Afteras delta-seconds or HTTP-date (RFC 7231). - politeness_
delay - Per-host politeness delay with additive jitter (never below the configured floor).
- wait_
for_ retry - Prefer server
Retry-Afterwhen present; otherwise full-jitter formula.