Skip to main content

Module retry

Module retry 

Source
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 / TOML disable_retry = true / max_retries = 0.
  • Layer: single retry loop inside crate::http::HttpClient only — no middleware stack, no nested client retries, no agent-level auto-retry of permanent kinds.
  • Budget: max_attempts and max_elapsed_ms are 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§

RetryConfig
Named retry policy for the product HTTP client (one dependency class).

Enums§

ErrorLayer
Transport / protocol layer of a failure (Rules checklist ErrorLayer).
RetryClass
Classification of an HTTP status for the retry gate.
RetryKind
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 (0 in config = derive from timeout). Used only when timeout_secs is 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-After as 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-After when present; otherwise full-jitter formula.