Skip to main content

eggfetch_core/
retry.rs

1//! Policy-driven retry subsystem.
2//!
3//! Retries are opt-in and idempotency-aware. The retry engine wraps the
4//! entire logical request attempt (including redirects) under a single
5//! total deadline. Each retry restarts the complete logical request,
6//! including redirects, under the original total deadline.
7//!
8//! # Safety
9//!
10//! POST and PATCH requests are never retried by default unless explicitly
11//! allowed by the policy or protected by an idempotency key. Stream
12//! bodies are never retried unless a replay factory is provided.
13//!
14//! # Backoff
15//!
16//! Uses bounded exponential backoff with jitter. Tests can use
17//! deterministic policies by injecting a fixed random source.
18
19use std::sync::atomic::{AtomicU64, Ordering};
20use std::sync::OnceLock;
21use std::time::Duration;
22
23use http::Method;
24
25use crate::body::RequestBody;
26use crate::error::Error;
27
28/// Default retryable status codes: 408, 429, 502, 503, 504.
29const DEFAULT_RETRYABLE_STATUSES: &[u16] = &[408, 429, 502, 503, 504];
30
31/// Returns `true` when a hyper-util legacy client error wraps a canceled
32/// hyper connection (stale pooled connection closed before any byte was
33/// sent). Delegates to the centralized bounded classifier evidence in
34/// `crate::error` so cancellation facts cannot diverge; retry policy
35/// semantics are unchanged (only this typed fact is consulted, never the
36/// broader `TransportFailureKind` category).
37#[cfg(any(feature = "transport-http1", feature = "transport-http2"))]
38fn is_hyper_canceled(inner: &hyper_util::client::legacy::Error) -> bool {
39    crate::error::hyper_legacy_is_canceled(inner)
40}
41
42/// Default retryable methods: GET, HEAD, OPTIONS.
43const DEFAULT_RETRYABLE_METHODS: &[Method] = &[Method::GET, Method::HEAD, Method::OPTIONS];
44
45/// Policy-driven retry configuration.
46///
47/// Controls which requests are retried, how many times, and with what
48/// backoff strategy. Retries are opt-in: the default policy disables
49/// retries.
50///
51/// # Examples
52///
53/// ```
54/// use std::time::Duration;
55/// use eggfetch_core::RetryPolicy;
56///
57/// let policy = RetryPolicy::builder()
58///     .max_attempts(3)
59///     .backoff_factor(0.2)
60///     .retry_status(429)
61///     .retry_status(503)
62///     .build();
63/// ```
64#[derive(Debug, Clone)]
65pub struct RetryPolicy {
66    /// Maximum number of total attempts (1 = no retries).
67    max_attempts: usize,
68    /// Maximum total elapsed time across all attempts including backoff sleeps.
69    max_elapsed: Option<Duration>,
70    /// Backoff configuration.
71    backoff: BackoffPolicy,
72    /// Which HTTP methods are eligible for retry.
73    method_policy: MethodPolicy,
74    /// Which status codes trigger a retry.
75    status_policy: StatusPolicy,
76    /// Whether to respect `Retry-After` headers.
77    respect_retry_after: bool,
78}
79
80impl Default for RetryPolicy {
81    fn default() -> Self {
82        Self {
83            max_attempts: 1,
84            max_elapsed: None,
85            backoff: BackoffPolicy::default(),
86            method_policy: MethodPolicy::default(),
87            status_policy: StatusPolicy::default(),
88            respect_retry_after: false,
89        }
90    }
91}
92
93impl RetryPolicy {
94    /// Create a new retry policy builder.
95    #[must_use]
96    pub fn builder() -> RetryPolicyBuilder {
97        RetryPolicyBuilder::new()
98    }
99
100    /// Returns the maximum number of total attempts.
101    #[must_use]
102    pub fn max_attempts(&self) -> usize {
103        self.max_attempts
104    }
105
106    /// Returns the maximum total elapsed time.
107    #[must_use]
108    pub fn max_elapsed(&self) -> Option<Duration> {
109        self.max_elapsed
110    }
111
112    /// Returns a reference to the backoff policy.
113    #[must_use]
114    pub fn backoff(&self) -> &BackoffPolicy {
115        &self.backoff
116    }
117
118    /// Returns a reference to the method policy.
119    #[must_use]
120    pub fn method_policy(&self) -> &MethodPolicy {
121        &self.method_policy
122    }
123
124    /// Returns a reference to the status policy.
125    #[must_use]
126    pub fn status_policy(&self) -> &StatusPolicy {
127        &self.status_policy
128    }
129
130    /// Returns whether `Retry-After` headers are respected.
131    #[must_use]
132    pub fn respect_retry_after(&self) -> bool {
133        self.respect_retry_after
134    }
135
136    /// Returns `true` if retries are effectively enabled (`max_attempts` > 1).
137    #[must_use]
138    pub fn is_enabled(&self) -> bool {
139        self.max_attempts > 1
140    }
141
142    /// Returns `true` if the given method is eligible for retry.
143    #[must_use]
144    pub fn is_method_retryable(&self, method: &Method) -> bool {
145        self.method_policy.is_retryable(method)
146    }
147
148    /// Returns `true` if the given status code is eligible for retry.
149    #[must_use]
150    pub fn is_status_retryable(&self, status: u16) -> bool {
151        self.status_policy.is_retryable(status)
152    }
153
154    /// Returns `true` if the given error is eligible for retry.
155    #[must_use]
156    pub fn is_error_retryable(error: &Error) -> bool {
157        #[cfg(any(feature = "transport-http1", feature = "transport-http2"))]
158        if let Error::HyperClient(inner) = error {
159            // Only retry failures that can succeed on replay:
160            // connect-level errors (`is_connect`, including DNS/TCP and
161            // connector handshake failures) and stale-pooled-connection
162            // cancellations (`hyper::Error::is_canceled`, "connection
163            // closed" before any byte was sent). User/config errors
164            // (unsupported method/version/absolute-uri) and mid-request
165            // send failures are never retried, so cert/config problems
166            // cannot be masked by a retry loop.
167            return inner.is_connect() || is_hyper_canceled(inner.as_ref());
168        }
169        match error {
170            Error::Connect(_)
171            | Error::Io(_)
172            | Error::Hyper(_)
173            | Error::Timeout {
174                phase: crate::timeout::TimeoutPhase::Connect,
175                ..
176            }
177            | Error::Timeout {
178                phase: crate::timeout::TimeoutPhase::Pool,
179                ..
180            }
181            | Error::Timeout {
182                phase:
183                    crate::timeout::TimeoutPhase::ProxyConnect | crate::timeout::TimeoutPhase::ProxyTls,
184                ..
185            }
186            | Error::H3Connect(_) => true,
187            Error::CustomTransport(error) => matches!(
188                error.kind(),
189                crate::transport::dialer::DialErrorKind::Connection
190                    | crate::transport::dialer::DialErrorKind::Timeout
191            ),
192            Error::Http2StreamReset { reason } if reason.starts_with("REFUSED_STREAM") => true,
193            _ => false,
194        }
195    }
196
197    /// Compute the backoff delay for the given attempt number (1-indexed).
198    ///
199    /// Returns `None` if no delay is needed (attempt 1).
200    #[must_use]
201    pub fn backoff_delay(&self, attempt: usize) -> Option<Duration> {
202        self.backoff.delay(attempt)
203    }
204
205    /// Compute the delay after receiving a `Retry-After` header value.
206    ///
207    /// Parses `Retry-After` as either a number of seconds or an HTTP-date.
208    /// Returns `None` if parsing fails, if a past HTTP-date is supplied
209    /// (the header carries no useful information), or if the value
210    /// exceeds the backoff cap.
211    #[must_use]
212    pub fn retry_after_delay(&self, retry_after: &str) -> Option<Duration> {
213        if !self.respect_retry_after {
214            return None;
215        }
216        let delay = if let Ok(secs) = retry_after.trim().parse::<u64>() {
217            Duration::from_secs(secs)
218        } else if let Ok(date) = httpdate::parse_http_date(retry_after.trim()) {
219            match date.duration_since(std::time::SystemTime::now()) {
220                Ok(duration) => duration,
221                Err(_) => return None,
222            }
223        } else {
224            return None;
225        };
226        let cap = self.backoff.max_delay;
227        Some(if delay > cap { cap } else { delay })
228    }
229
230    /// Check if a request body is replayable for retry.
231    ///
232    /// Returns `ReplayCheck::Replayable` if the body can be replayed,
233    /// or `ReplayCheck::NotReplayable` if the body is a live stream.
234    #[must_use]
235    pub fn check_body_replayable(body: &RequestBody) -> ReplayCheck {
236        if body.is_replayable() {
237            ReplayCheck::Replayable
238        } else {
239            ReplayCheck::NotReplayable
240        }
241    }
242}
243
244/// Builder for constructing a [`RetryPolicy`].
245pub struct RetryPolicyBuilder {
246    max_attempts: usize,
247    max_elapsed: Option<Duration>,
248    backoff: BackoffPolicyBuilder,
249    method_policy: MethodPolicy,
250    status_policy: StatusPolicy,
251    respect_retry_after: bool,
252    custom_statuses_used: bool,
253}
254
255impl RetryPolicyBuilder {
256    /// Create a new builder with defaults.
257    #[must_use]
258    pub fn new() -> Self {
259        Self {
260            max_attempts: 1,
261            max_elapsed: None,
262            backoff: BackoffPolicyBuilder::new(),
263            method_policy: MethodPolicy::default(),
264            status_policy: StatusPolicy::default(),
265            respect_retry_after: false,
266            custom_statuses_used: false,
267        }
268    }
269
270    /// Set the maximum number of total attempts (including the first request).
271    ///
272    /// A value of 1 means no retries. A value of 3 means up to 2 retries.
273    #[must_use]
274    pub fn max_attempts(mut self, max: usize) -> Self {
275        self.max_attempts = max;
276        self
277    }
278
279    /// Set the maximum total elapsed time across all attempts.
280    ///
281    /// Includes backoff sleeps. If `None`, no total time limit is applied.
282    #[must_use]
283    pub fn max_elapsed(mut self, elapsed: Duration) -> Self {
284        self.max_elapsed = Some(elapsed);
285        self
286    }
287
288    /// Set the backoff factor for exponential backoff.
289    ///
290    /// The delay before retry attempt `n` (`n >= 2`) is
291    /// `initial_delay * factor^(n - 2)`, capped at `max_delay` and
292    /// reduced by full jitter. The default factor is `2.0`.
293    #[must_use]
294    pub fn backoff_factor(mut self, factor: f64) -> Self {
295        self.backoff = self.backoff.factor(factor);
296        self
297    }
298
299    /// Set the maximum delay between retries.
300    #[must_use]
301    pub fn max_delay(mut self, delay: Duration) -> Self {
302        self.backoff = self.backoff.max_delay(delay);
303        self
304    }
305
306    /// Set the initial delay for the first retry.
307    #[must_use]
308    pub fn initial_delay(mut self, delay: Duration) -> Self {
309        self.backoff = self.backoff.initial_delay(delay);
310        self
311    }
312
313    /// Add a retryable status code.
314    ///
315    /// The first call to `retry_status` replaces the default set
316    /// (408, 429, 502, 503, 504). Subsequent calls add to the set.
317    #[must_use]
318    pub fn retry_status(mut self, status: u16) -> Self {
319        if !self.custom_statuses_used {
320            self.status_policy = StatusPolicy::default_empty();
321            self.custom_statuses_used = true;
322        }
323        self.status_policy.add_status(status);
324        self
325    }
326
327    /// Set the retryable status codes, replacing any existing ones.
328    #[must_use]
329    pub fn retry_statuses(mut self, statuses: impl IntoIterator<Item = u16>) -> Self {
330        self.status_policy = StatusPolicy::new(statuses);
331        self.custom_statuses_used = true;
332        self
333    }
334
335    /// Add a retryable method.
336    #[must_use]
337    pub fn retry_method(mut self, method: Method) -> Self {
338        self.method_policy.add_method(method);
339        self
340    }
341
342    /// Allow POST requests to be retried.
343    #[must_use]
344    pub fn allow_post_retry(mut self) -> Self {
345        self.method_policy.add_method(Method::POST);
346        self
347    }
348
349    /// Allow PUT requests to be retried.
350    #[must_use]
351    pub fn allow_put_retry(mut self) -> Self {
352        self.method_policy.add_method(Method::PUT);
353        self
354    }
355
356    /// Allow DELETE requests to be retried.
357    #[must_use]
358    pub fn allow_delete_retry(mut self) -> Self {
359        self.method_policy.add_method(Method::DELETE);
360        self
361    }
362
363    /// Allow PATCH requests to be retried.
364    #[must_use]
365    pub fn allow_patch_retry(mut self) -> Self {
366        self.method_policy.add_method(Method::PATCH);
367        self
368    }
369
370    /// Enable or disable `Retry-After` header support.
371    #[must_use]
372    pub fn respect_retry_after(mut self, respect: bool) -> Self {
373        self.respect_retry_after = respect;
374        self
375    }
376
377    /// Build the retry policy.
378    #[must_use]
379    pub fn build(self) -> RetryPolicy {
380        RetryPolicy {
381            max_attempts: self.max_attempts,
382            max_elapsed: self.max_elapsed,
383            backoff: self.backoff.build(),
384            method_policy: self.method_policy,
385            status_policy: self.status_policy,
386            respect_retry_after: self.respect_retry_after,
387        }
388    }
389}
390
391impl Default for RetryPolicyBuilder {
392    fn default() -> Self {
393        Self::new()
394    }
395}
396
397/// Backoff strategy for retries.
398#[derive(Debug, Clone)]
399pub struct BackoffPolicy {
400    /// Base factor for exponential backoff.
401    factor: f64,
402    /// Maximum delay cap.
403    max_delay: Duration,
404    /// Initial delay for the first retry.
405    initial_delay: Duration,
406}
407
408impl Default for BackoffPolicy {
409    fn default() -> Self {
410        Self {
411            factor: 2.0,
412            max_delay: Duration::from_secs(30),
413            initial_delay: Duration::from_millis(500),
414        }
415    }
416}
417
418impl BackoffPolicy {
419    /// Compute the delay for the given attempt number (1-indexed).
420    ///
421    /// Attempt 1 returns `None` (no delay before the first attempt).
422    /// Later attempts use exponential backoff with full jitter: the
423    /// delay is drawn uniformly from `[0, capped)`, where `capped` is
424    /// `initial_delay * factor^(attempt - 2)` clamped to `max_delay`.
425    #[must_use]
426    #[allow(
427        clippy::cast_precision_loss,
428        reason = "the attempt counter is only used as an f64 exponent, so rounding beyond 2^53 attempts cannot change the delay"
429    )]
430    pub fn delay(&self, attempt: usize) -> Option<Duration> {
431        if attempt <= 1 {
432            return None;
433        }
434
435        // Exponential backoff: initial_delay * factor^(attempt-2)
436        let exp = (attempt - 2) as f64;
437        let raw = self.initial_delay.as_secs_f64() * self.factor.powf(exp);
438        // `Duration::MAX.as_secs_f64()` rounds up to 2^64 (oversize for
439        // `from_secs_f64`), so treat a non-convertible max as unbounded
440        // here; the saturating conversion below clamps to `max_delay` anyway.
441        let max_float = self.max_delay.as_secs_f64();
442        let max_secs = if Duration::try_from_secs_f64(max_float).is_ok() {
443            max_float
444        } else {
445            f64::MAX
446        };
447
448        // Guard against NaN, inf, negative, and values exceeding max_delay
449        // before converting to Duration. `Duration::from_secs_f64` panics on
450        // non-finite, negative, or oversized floats, and `max_delay` itself
451        // may be `Duration::MAX` whose `as_secs_f64()` rounds up to 2^64
452        // (oversize), so saturate instead of converting directly.
453        let capped = if !raw.is_finite() || raw < 0.0 || raw > max_secs {
454            self.max_delay
455        } else {
456            Duration::try_from_secs_f64(raw).unwrap_or(self.max_delay)
457        };
458
459        // Full jitter: uniform value in [0, capped) so retries in the
460        // saturated regime do not all collapse onto the cap (which would
461        // re-create the thundering-herd pattern jitter exists to prevent).
462        // If the system RNG fails, degrade to the deterministic capped
463        // delay instead of panicking.
464        let jittered_secs = match get_random_f64() {
465            Some(jitter) => capped.as_secs_f64() * jitter,
466            None => capped.as_secs_f64(),
467        };
468
469        let final_delay = if !jittered_secs.is_finite() || jittered_secs < 0.0 {
470            capped
471        } else {
472            // `capped` may be `Duration::MAX` (whose float form rounds to
473            // oversize 2^64); saturate instead of panicking.
474            Duration::try_from_secs_f64(jittered_secs).unwrap_or(capped)
475        };
476
477        // Avoid a zero-length retry loop when jitter rounds a positive
478        // budget down to zero. Preserve an explicitly zero cap as an
479        // intentional immediate retry.
480        Some(final_delay.max(Duration::from_millis(1).min(capped)))
481    }
482
483    /// Returns the maximum delay.
484    #[must_use]
485    pub fn max_delay(&self) -> Duration {
486        self.max_delay
487    }
488
489    /// Returns the factor.
490    #[must_use]
491    pub fn factor(&self) -> f64 {
492        self.factor
493    }
494
495    /// Returns the initial delay.
496    #[must_use]
497    pub fn initial_delay(&self) -> Duration {
498        self.initial_delay
499    }
500}
501
502/// Builder for [`BackoffPolicy`].
503pub struct BackoffPolicyBuilder {
504    factor: f64,
505    max_delay: Duration,
506    initial_delay: Duration,
507}
508
509impl BackoffPolicyBuilder {
510    #[must_use]
511    fn new() -> Self {
512        Self {
513            factor: 2.0,
514            max_delay: Duration::from_secs(30),
515            initial_delay: Duration::from_millis(500),
516        }
517    }
518
519    #[must_use]
520    fn factor(mut self, factor: f64) -> Self {
521        // `BackoffPolicy::delay` caps non-finite or non-positive factors to
522        // `max_delay` (see fuzz regression for NaN), so the builder accepts
523        // any f64 and defers validation to the delay computation.
524        self.factor = factor;
525        self
526    }
527
528    #[must_use]
529    fn max_delay(mut self, delay: Duration) -> Self {
530        self.max_delay = delay;
531        self
532    }
533
534    #[must_use]
535    fn initial_delay(mut self, delay: Duration) -> Self {
536        self.initial_delay = delay;
537        self
538    }
539
540    #[must_use]
541    fn build(self) -> BackoffPolicy {
542        BackoffPolicy {
543            factor: self.factor,
544            max_delay: self.max_delay,
545            initial_delay: self.initial_delay,
546        }
547    }
548}
549
550/// Policy controlling which HTTP methods are eligible for retry.
551#[derive(Debug, Clone)]
552pub struct MethodPolicy {
553    /// Set of methods eligible for retry.
554    methods: Vec<Method>,
555}
556
557impl Default for MethodPolicy {
558    fn default() -> Self {
559        Self {
560            methods: DEFAULT_RETRYABLE_METHODS.to_vec(),
561        }
562    }
563}
564
565impl MethodPolicy {
566    /// Create a method policy with the given methods.
567    #[must_use]
568    pub fn new(methods: Vec<Method>) -> Self {
569        Self { methods }
570    }
571
572    /// Add a method to the retryable set.
573    pub fn add_method(&mut self, method: Method) {
574        if !self.methods.contains(&method) {
575            self.methods.push(method);
576        }
577    }
578
579    /// Returns `true` if the method is retryable.
580    #[must_use]
581    pub fn is_retryable(&self, method: &Method) -> bool {
582        self.methods.contains(method)
583    }
584
585    /// Returns the list of retryable methods.
586    #[must_use]
587    pub fn methods(&self) -> &[Method] {
588        &self.methods
589    }
590}
591
592/// Policy controlling which status codes trigger a retry.
593#[derive(Debug, Clone)]
594pub struct StatusPolicy {
595    /// Set of status codes eligible for retry.
596    statuses: Vec<u16>,
597}
598
599impl Default for StatusPolicy {
600    fn default() -> Self {
601        Self {
602            statuses: DEFAULT_RETRYABLE_STATUSES.to_vec(),
603        }
604    }
605}
606
607impl StatusPolicy {
608    /// Create a status policy with the given codes.
609    #[must_use]
610    pub fn new(statuses: impl IntoIterator<Item = u16>) -> Self {
611        Self {
612            statuses: statuses.into_iter().collect(),
613        }
614    }
615
616    /// Create an empty status policy (no retryable statuses).
617    #[must_use]
618    pub fn default_empty() -> Self {
619        Self {
620            statuses: Vec::new(),
621        }
622    }
623
624    /// Add a status code to the retryable set.
625    pub fn add_status(&mut self, status: u16) {
626        if !self.statuses.contains(&status) {
627            self.statuses.push(status);
628        }
629    }
630
631    /// Returns `true` if the status code is retryable.
632    #[must_use]
633    pub fn is_retryable(&self, status: u16) -> bool {
634        self.statuses.contains(&status)
635    }
636
637    /// Returns the list of retryable status codes.
638    #[must_use]
639    pub fn statuses(&self) -> &[u16] {
640        &self.statuses
641    }
642}
643
644/// Result of a body replayability check.
645#[derive(Debug, Clone, Copy, PartialEq, Eq)]
646pub enum ReplayCheck {
647    /// The body can be replayed.
648    Replayable,
649    /// The body cannot be replayed.
650    NotReplayable,
651}
652
653/// The cause of a retry decision.
654#[derive(Debug, Clone, PartialEq, Eq)]
655pub enum RetryCause {
656    /// A transport error occurred (connection refused, reset, etc.).
657    TransportError(String),
658    /// A retryable HTTP status code was received.
659    Status(u16),
660    /// A timeout occurred during a retryable phase.
661    Timeout(String),
662}
663
664impl std::fmt::Display for RetryCause {
665    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
666        match self {
667            Self::TransportError(msg) => write!(f, "transport error: {msg}"),
668            Self::Status(status) => write!(f, "retryable status: {status}"),
669            Self::Timeout(phase) => write!(f, "timeout: {phase}"),
670        }
671    }
672}
673
674/// Context for a retry attempt.
675#[derive(Debug, Clone)]
676pub struct RetryContext {
677    /// The current attempt number (1-indexed).
678    pub attempt: usize,
679    /// The HTTP method.
680    pub method: Method,
681    /// Whether the request body is replayable.
682    pub body_replayable: bool,
683    /// The cause that triggered this retry.
684    pub cause: RetryCause,
685    /// Remaining total budget.
686    pub remaining_total: Option<Duration>,
687}
688
689/// Determine if an error/status should trigger a retry.
690///
691/// Returns `Some(RetryCause)` if the error is retryable under the given
692/// policy, `None` otherwise.
693#[must_use]
694pub fn should_retry(
695    policy: &RetryPolicy,
696    method: &Method,
697    body: &RequestBody,
698    error: Option<&Error>,
699    status: Option<u16>,
700) -> Option<RetryCause> {
701    // Check method eligibility
702    if !policy.is_method_retryable(method) {
703        return None;
704    }
705
706    // Check body replayability
707    if !body.is_replayable() {
708        return None;
709    }
710
711    // Check error-based retry
712    if let Some(err) = error {
713        if RetryPolicy::is_error_retryable(err) {
714            return Some(RetryCause::TransportError(err.to_string()));
715        }
716        return None;
717    }
718
719    // Check status-based retry
720    if let Some(status) = status {
721        if policy.is_status_retryable(status) {
722            return Some(RetryCause::Status(status));
723        }
724    }
725
726    None
727}
728
729/// Get a random f64 in [0, 1) from a process-local PRNG.
730///
731/// Returns `None` if the system RNG fails so callers can degrade
732/// gracefully (e.g. to a deterministic delay) instead of panicking.
733#[allow(
734    clippy::cast_precision_loss,
735    reason = "the 53 high bits of the PRNG state are exactly representable in f64, so the conversion is lossless"
736)]
737fn get_random_f64() -> Option<f64> {
738    // Only successful seeds are cached: a transient `getrandom` failure is
739    // retried on the next call instead of pinning the process to
740    // deterministic backoff for its whole lifetime.
741    static STATE: OnceLock<AtomicU64> = OnceLock::new();
742
743    let state = if let Some(state) = STATE.get() {
744        state
745    } else {
746        let mut buf = [0u8; 8];
747        let seed = u64::from_le_bytes({
748            getrandom::getrandom(&mut buf).ok()?;
749            buf
750        })
751        .max(1);
752        let _ = STATE.set(AtomicU64::new(seed));
753        STATE.get()?
754    };
755    // `fetch_update` is deprecated in favor of `try_update` on recent
756    // toolchains, but `try_update` is still unstable on MSRV 1.89, so the
757    // rename cannot be adopted until MSRV moves forward.
758    #[allow(
759        deprecated,
760        reason = "fetch_update is deprecated in favour of try_update, which is still unstable on the MSRV toolchain"
761    )]
762    let val = state
763        .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |mut value| {
764            value ^= value << 13;
765            value ^= value >> 7;
766            value ^= value << 17;
767            Some(value.max(1))
768        })
769        .ok()?;
770    // Use the top 53 bits so the value is exactly representable and the
771    // result stays strictly below 1.0 (dividing a rounded u64 by
772    // `u64::MAX as f64` could round up to exactly 1.0).
773    Some(((val >> 11) as f64) / ((1u64 << 53) as f64))
774}
775
776#[cfg(test)]
777mod tests {
778    use super::*;
779    use proptest::prelude::*;
780
781    #[test]
782    fn retry_policy_default_disables_retries() {
783        let policy = RetryPolicy::default();
784        assert!(!policy.is_enabled());
785        assert_eq!(policy.max_attempts(), 1);
786    }
787
788    #[test]
789    fn proxy_timeout_phases_are_retryable() {
790        for phase in [
791            crate::timeout::TimeoutPhase::ProxyConnect,
792            crate::timeout::TimeoutPhase::ProxyTls,
793        ] {
794            let error = Error::Timeout {
795                phase,
796                elapsed: Duration::from_secs(1),
797            };
798            assert!(RetryPolicy::is_error_retryable(&error));
799        }
800    }
801
802    #[test]
803    fn custom_dialer_connection_and_timeout_failures_are_retryable() {
804        for kind in [
805            crate::transport::dialer::DialErrorKind::Connection,
806            crate::transport::dialer::DialErrorKind::Timeout,
807        ] {
808            let error = Error::CustomTransport(std::sync::Arc::new(
809                crate::transport::dialer::DialError::new(kind, "route failed"),
810            ));
811            assert!(RetryPolicy::is_error_retryable(&error));
812        }
813        for kind in [
814            crate::transport::dialer::DialErrorKind::Authentication,
815            crate::transport::dialer::DialErrorKind::Rejected,
816            crate::transport::dialer::DialErrorKind::Other,
817        ] {
818            let error = Error::CustomTransport(std::sync::Arc::new(
819                crate::transport::dialer::DialError::new(kind, "route failed"),
820            ));
821            assert!(!RetryPolicy::is_error_retryable(&error));
822        }
823    }
824
825    #[test]
826    fn jitter_is_strictly_below_one() {
827        // The documented contract is [0, 1); a sample that rounds up to
828        // exactly 1.0 would let the backoff delay reach the capped max.
829        for _ in 0..10_000 {
830            let Some(jitter) = get_random_f64() else {
831                // RNG unavailable in this environment: the production
832                // path degrades to a deterministic delay, so there is
833                // nothing to assert here.
834                return;
835            };
836            assert!((0.0..1.0).contains(&jitter));
837        }
838    }
839
840    #[test]
841    fn retry_policy_builder_basic() {
842        let policy = RetryPolicy::builder()
843            .max_attempts(3)
844            .backoff_factor(0.2)
845            .build();
846        assert!(policy.is_enabled());
847        assert_eq!(policy.max_attempts(), 3);
848    }
849
850    #[test]
851    fn retry_policy_method_default_safe() {
852        let policy = RetryPolicy::default();
853        assert!(policy.is_method_retryable(&Method::GET));
854        assert!(policy.is_method_retryable(&Method::HEAD));
855        assert!(policy.is_method_retryable(&Method::OPTIONS));
856        assert!(!policy.is_method_retryable(&Method::POST));
857        assert!(!policy.is_method_retryable(&Method::PUT));
858        assert!(!policy.is_method_retryable(&Method::DELETE));
859        assert!(!policy.is_method_retryable(&Method::PATCH));
860    }
861
862    #[test]
863    fn retry_policy_method_allow_post() {
864        let policy = RetryPolicy::builder()
865            .max_attempts(3)
866            .allow_post_retry()
867            .build();
868        assert!(policy.is_method_retryable(&Method::POST));
869    }
870
871    #[test]
872    fn retry_policy_status_default() {
873        let policy = RetryPolicy::default();
874        assert!(policy.is_status_retryable(408));
875        assert!(policy.is_status_retryable(429));
876        assert!(policy.is_status_retryable(502));
877        assert!(policy.is_status_retryable(503));
878        assert!(policy.is_status_retryable(504));
879        assert!(!policy.is_status_retryable(200));
880        assert!(!policy.is_status_retryable(404));
881    }
882
883    #[test]
884    fn retry_policy_status_custom() {
885        let policy = RetryPolicy::builder()
886            .max_attempts(3)
887            .retry_status(429)
888            .retry_status(503)
889            .build();
890        assert!(policy.is_status_retryable(429));
891        assert!(policy.is_status_retryable(503));
892        assert!(!policy.is_status_retryable(408));
893        assert!(!policy.is_status_retryable(504));
894    }
895
896    #[test]
897    fn backoff_delay_none_for_first_attempt() {
898        let backoff = BackoffPolicy::default();
899        assert!(backoff.delay(1).is_none());
900    }
901
902    #[test]
903    fn backoff_delay_bounded_for_later_attempts() {
904        let backoff = BackoffPolicy {
905            factor: 0.5,
906            max_delay: Duration::from_secs(30),
907            initial_delay: Duration::from_millis(100),
908        };
909        // Full jitter: the delay is drawn from [0, capped).
910        let d2 = backoff.delay(2).unwrap();
911        assert!(d2 <= Duration::from_millis(100));
912
913        let d3 = backoff.delay(3).unwrap();
914        assert!(d3 <= Duration::from_millis(50));
915    }
916
917    #[test]
918    fn backoff_delay_has_minimum_when_cap_is_positive() {
919        let backoff = BackoffPolicy {
920            factor: 1.0,
921            max_delay: Duration::from_millis(1),
922            initial_delay: Duration::from_millis(1),
923        };
924        assert_eq!(backoff.delay(2), Some(Duration::from_millis(1)));
925    }
926
927    #[test]
928    fn default_backoff_grows_exponentially() {
929        // The default policy must back off, not speed up: the cap for
930        // attempt n is `initial_delay * 2^(n - 2)`. Jitter draws below
931        // the cap, so only upper bounds are asserted.
932        let backoff = BackoffPolicy::default();
933        assert!((backoff.factor() - 2.0).abs() < f64::EPSILON);
934        assert!(backoff.delay(2).unwrap() <= Duration::from_millis(500));
935        assert!(backoff.delay(3).unwrap() <= Duration::from_secs(1));
936        assert!(backoff.delay(4).unwrap() <= Duration::from_secs(2));
937    }
938
939    #[test]
940    fn backoff_delay_capped_at_max() {
941        let backoff = BackoffPolicy {
942            factor: 2.0,
943            max_delay: Duration::from_secs(5),
944            initial_delay: Duration::from_secs(1),
945        };
946        let d = backoff.delay(10).unwrap();
947        assert!(d < Duration::from_secs(5)); // full jitter stays below cap
948    }
949
950    #[test]
951    fn retry_after_disabled_by_default() {
952        let policy = RetryPolicy::default();
953        assert!(policy.retry_after_delay("5").is_none());
954    }
955
956    #[test]
957    fn retry_after_respected_when_enabled() {
958        let policy = RetryPolicy::builder()
959            .max_attempts(3)
960            .respect_retry_after(true)
961            .build();
962        let delay = policy.retry_after_delay("5").unwrap();
963        assert_eq!(delay, Duration::from_secs(5));
964    }
965
966    #[test]
967    fn retry_after_capped_at_max_delay() {
968        let policy = RetryPolicy::builder()
969            .max_attempts(3)
970            .respect_retry_after(true)
971            .max_delay(Duration::from_secs(10))
972            .build();
973        let delay = policy.retry_after_delay("60").unwrap();
974        assert_eq!(delay, Duration::from_secs(10));
975    }
976
977    #[test]
978    fn retry_after_invalid_ignored() {
979        let policy = RetryPolicy::builder()
980            .max_attempts(3)
981            .respect_retry_after(true)
982            .build();
983        assert!(policy.retry_after_delay("not-a-number").is_none());
984    }
985
986    #[test]
987    fn retry_after_http_date_parses() {
988        use std::time::UNIX_EPOCH;
989
990        let policy = RetryPolicy::builder()
991            .max_attempts(3)
992            .respect_retry_after(true)
993            .build();
994        // Build a future SystemTime and format it with httpdate, then parse it back
995        // to guarantee the day-of-week matches
996        let future_time = UNIX_EPOCH
997            + Duration::from_secs(
998                std::time::SystemTime::now()
999                    .duration_since(UNIX_EPOCH)
1000                    .unwrap()
1001                    .as_secs()
1002                    + 3600,
1003            ); // 1 hour from now
1004        let formatted = httpdate::fmt_http_date(future_time);
1005        let parsed = httpdate::parse_http_date(&formatted);
1006        assert!(parsed.is_ok(), "round-trip parse failed: {formatted}");
1007        let delay = policy.retry_after_delay(&formatted);
1008        assert!(
1009            delay.is_some(),
1010            "retry_after_delay returned None for HTTP-date: {formatted}"
1011        );
1012        let d = delay.unwrap();
1013        assert!(d.as_secs() > 0, "delay should be positive");
1014    }
1015
1016    #[test]
1017    fn retry_after_past_http_date_is_ignored() {
1018        use std::time::UNIX_EPOCH;
1019
1020        let policy = RetryPolicy::builder()
1021            .max_attempts(3)
1022            .respect_retry_after(true)
1023            .build();
1024        // One hour in the past: the header carries no useful information,
1025        // so it must be ignored (None) rather than mapped to zero.
1026        let past_time = UNIX_EPOCH
1027            + Duration::from_secs(
1028                std::time::SystemTime::now()
1029                    .duration_since(UNIX_EPOCH)
1030                    .unwrap()
1031                    .as_secs()
1032                    .saturating_sub(3600),
1033            );
1034        let formatted = httpdate::fmt_http_date(past_time);
1035        assert!(policy.retry_after_delay(&formatted).is_none());
1036    }
1037
1038    #[test]
1039    fn body_replayable_empty() {
1040        let body = RequestBody::Empty;
1041        assert_eq!(
1042            RetryPolicy::check_body_replayable(&body),
1043            ReplayCheck::Replayable
1044        );
1045    }
1046
1047    #[test]
1048    fn body_replayable_bytes() {
1049        let body = RequestBody::from(bytes::Bytes::from("hello"));
1050        assert_eq!(
1051            RetryPolicy::check_body_replayable(&body),
1052            ReplayCheck::Replayable
1053        );
1054    }
1055
1056    #[test]
1057    fn body_not_replayable_stream() {
1058        let body = RequestBody::from_stream(
1059            futures_util::stream::empty::<std::result::Result<bytes::Bytes, crate::Error>>(),
1060            None,
1061        );
1062        assert_eq!(
1063            RetryPolicy::check_body_replayable(&body),
1064            ReplayCheck::NotReplayable
1065        );
1066    }
1067
1068    #[test]
1069    fn should_retry_get_with_retryable_status() {
1070        let policy = RetryPolicy::builder().max_attempts(3).build();
1071        let body = RequestBody::Empty;
1072        let cause = should_retry(&policy, &Method::GET, &body, None, Some(503));
1073        assert_eq!(cause, Some(RetryCause::Status(503)));
1074    }
1075
1076    #[test]
1077    fn should_not_retry_post_by_default() {
1078        let policy = RetryPolicy::builder().max_attempts(3).build();
1079        let body = RequestBody::Empty;
1080        let cause = should_retry(&policy, &Method::POST, &body, None, Some(503));
1081        assert_eq!(cause, None);
1082    }
1083
1084    #[test]
1085    fn should_retry_post_when_allowed() {
1086        let policy = RetryPolicy::builder()
1087            .max_attempts(3)
1088            .allow_post_retry()
1089            .build();
1090        let body = RequestBody::Empty;
1091        let cause = should_retry(&policy, &Method::POST, &body, None, Some(503));
1092        assert_eq!(cause, Some(RetryCause::Status(503)));
1093    }
1094
1095    #[test]
1096    fn should_not_retry_non_retryable_status() {
1097        let policy = RetryPolicy::builder().max_attempts(3).build();
1098        let body = RequestBody::Empty;
1099        let cause = should_retry(&policy, &Method::GET, &body, None, Some(200));
1100        assert_eq!(cause, None);
1101    }
1102
1103    #[test]
1104    fn should_not_retry_stream_body() {
1105        let policy = RetryPolicy::builder().max_attempts(3).build();
1106        let body = RequestBody::from_stream(
1107            futures_util::stream::empty::<std::result::Result<bytes::Bytes, crate::Error>>(),
1108            None,
1109        );
1110        let cause = should_retry(&policy, &Method::GET, &body, None, Some(503));
1111        assert_eq!(cause, None);
1112    }
1113
1114    #[test]
1115    fn should_retry_connect_error() {
1116        let policy = RetryPolicy::builder().max_attempts(3).build();
1117        let body = RequestBody::Empty;
1118        let err = Error::Connect("connection refused".into());
1119        let cause = should_retry(&policy, &Method::GET, &body, Some(&err), None);
1120        assert!(matches!(cause, Some(RetryCause::TransportError(_))));
1121    }
1122
1123    #[test]
1124    fn should_not_retry_invalid_url() {
1125        let policy = RetryPolicy::builder().max_attempts(3).build();
1126        let body = RequestBody::Empty;
1127        let err = Error::InvalidUrl("bad url".into());
1128        let cause = should_retry(&policy, &Method::GET, &body, Some(&err), None);
1129        assert_eq!(cause, None);
1130    }
1131
1132    #[test]
1133    #[cfg(feature = "http3")]
1134    fn should_retry_h3_connect_error() {
1135        let policy = RetryPolicy::builder().max_attempts(3).build();
1136        let body = RequestBody::Empty;
1137        let err = Error::H3Connect("QUIC handshake failed".into());
1138        let cause = should_retry(&policy, &Method::GET, &body, Some(&err), None);
1139        assert!(matches!(cause, Some(RetryCause::TransportError(_))));
1140    }
1141
1142    #[test]
1143    #[cfg(feature = "http3")]
1144    fn should_not_retry_h3_connection_closed() {
1145        let policy = RetryPolicy::builder().max_attempts(3).build();
1146        let body = RequestBody::Empty;
1147        let err = Error::H3ConnectionClosed("peer sent GOAWAY".into());
1148        let cause = should_retry(&policy, &Method::GET, &body, Some(&err), None);
1149        assert_eq!(cause, None);
1150    }
1151
1152    #[test]
1153    #[cfg(feature = "http3")]
1154    fn should_not_retry_h3_protocol_error() {
1155        let policy = RetryPolicy::builder().max_attempts(3).build();
1156        let body = RequestBody::Empty;
1157        let err = Error::H3Protocol("unexpected frame".into());
1158        let cause = should_retry(&policy, &Method::GET, &body, Some(&err), None);
1159        assert_eq!(cause, None);
1160    }
1161
1162    #[test]
1163    #[cfg(feature = "http3")]
1164    fn should_not_retry_h3_stream_error() {
1165        let policy = RetryPolicy::builder().max_attempts(3).build();
1166        let body = RequestBody::Empty;
1167        let err = Error::H3Stream("stream reset".into());
1168        let cause = should_retry(&policy, &Method::GET, &body, Some(&err), None);
1169        assert_eq!(cause, None);
1170    }
1171
1172    #[test]
1173    fn retry_cause_display() {
1174        assert_eq!(
1175            RetryCause::TransportError("refused".into()).to_string(),
1176            "transport error: refused"
1177        );
1178        assert_eq!(RetryCause::Status(503).to_string(), "retryable status: 503");
1179        assert_eq!(
1180            RetryCause::Timeout("total".into()).to_string(),
1181            "timeout: total"
1182        );
1183    }
1184
1185    #[test]
1186    fn method_policy_add_method() {
1187        let mut policy = MethodPolicy::default();
1188        assert!(!policy.is_retryable(&Method::POST));
1189        policy.add_method(Method::POST);
1190        assert!(policy.is_retryable(&Method::POST));
1191    }
1192
1193    #[test]
1194    fn status_policy_add_status() {
1195        let mut policy = StatusPolicy::default();
1196        assert!(!policy.is_retryable(418));
1197        policy.add_status(418);
1198        assert!(policy.is_retryable(418));
1199    }
1200
1201    #[test]
1202    fn retry_policy_max_elapsed() {
1203        let policy = RetryPolicy::builder()
1204            .max_attempts(3)
1205            .max_elapsed(Duration::from_secs(10))
1206            .build();
1207        assert_eq!(policy.max_elapsed(), Some(Duration::from_secs(10)));
1208    }
1209
1210    #[test]
1211    fn retry_policy_display_cause() {
1212        let cause = RetryCause::Status(429);
1213        assert_eq!(format!("{cause}"), "retryable status: 429");
1214    }
1215
1216    #[test]
1217    fn prop_backoff_delay_some_for_attempt_gt_1() {
1218        proptest::proptest!(|(attempt in 2usize..100usize)| {
1219            let backoff = BackoffPolicy::default();
1220            prop_assert!(backoff.delay(attempt).is_some());
1221        });
1222    }
1223
1224    #[test]
1225    fn prop_backoff_delay_bounded_by_max_delay() {
1226        proptest::proptest!(|(
1227            factor in 0.1f64..2.0f64,
1228            initial_ms in 1u64..1000u64,
1229            max_secs in 1u64..60u64,
1230            attempt in 2usize..20usize,
1231        )| {
1232            let backoff = BackoffPolicy {
1233                factor,
1234                max_delay: Duration::from_secs(max_secs),
1235                initial_delay: Duration::from_millis(initial_ms),
1236            };
1237            if let Some(delay) = backoff.delay(attempt) {
1238                prop_assert!(delay <= Duration::from_secs(max_secs * 2));
1239            }
1240        });
1241    }
1242
1243    #[test]
1244    fn prop_method_policy_default_contains_get_head_options() {
1245        let policy = MethodPolicy::default();
1246        assert!(policy.is_retryable(&Method::GET));
1247        assert!(policy.is_retryable(&Method::HEAD));
1248        assert!(policy.is_retryable(&Method::OPTIONS));
1249    }
1250
1251    #[test]
1252    fn prop_status_policy_default_contains_expected() {
1253        let policy = StatusPolicy::default();
1254        assert!(policy.is_retryable(408));
1255        assert!(policy.is_retryable(429));
1256        assert!(policy.is_retryable(502));
1257        assert!(policy.is_retryable(503));
1258        assert!(policy.is_retryable(504));
1259    }
1260
1261    #[test]
1262    fn prop_retry_after_delay_returns_none_for_garbage() {
1263        proptest::proptest!(|(input in ".{0,100}")| {
1264            let policy = RetryPolicy::builder()
1265                .max_attempts(3)
1266                .respect_retry_after(true)
1267                .build();
1268            let _ = policy.retry_after_delay(&input);
1269        });
1270    }
1271
1272    #[test]
1273    fn regression_fuzz_retry_crash_extreme_backoff_factor() {
1274        let backoff = BackoffPolicy {
1275            factor: 22.0,
1276            max_delay: Duration::from_secs(30),
1277            initial_delay: Duration::from_millis(500),
1278        };
1279        for attempt in 2..=20 {
1280            let delay = backoff.delay(attempt);
1281            assert!(delay.is_some());
1282            assert!(delay.unwrap() <= backoff.max_delay);
1283        }
1284    }
1285
1286    #[test]
1287    fn backoff_delay_nan_factor_returns_bounded_delay() {
1288        let backoff = BackoffPolicy {
1289            factor: f64::NAN,
1290            max_delay: Duration::from_secs(30),
1291            initial_delay: Duration::from_millis(500),
1292        };
1293        let d = backoff.delay(5).unwrap();
1294        assert!(d <= Duration::from_secs(30));
1295    }
1296
1297    #[test]
1298    fn backoff_delay_infinite_factor_returns_bounded_delay() {
1299        let backoff = BackoffPolicy {
1300            factor: f64::INFINITY,
1301            max_delay: Duration::from_secs(30),
1302            initial_delay: Duration::from_millis(500),
1303        };
1304        let d = backoff.delay(5).unwrap();
1305        assert!(d <= Duration::from_secs(30));
1306    }
1307
1308    #[test]
1309    fn backoff_delay_max_duration_does_not_panic() {
1310        // `Duration::MAX.as_secs_f64()` rounds up to 2^64, which
1311        // `Duration::from_secs_f64` rejects: the delay must saturate.
1312        let backoff = BackoffPolicy {
1313            factor: 2.0,
1314            max_delay: Duration::MAX,
1315            initial_delay: Duration::from_millis(500),
1316        };
1317        for attempt in [2, 5, 100] {
1318            let d = backoff.delay(attempt).unwrap();
1319            assert!(d <= Duration::MAX);
1320        }
1321    }
1322
1323    #[test]
1324    fn prop_is_error_retryable_never_panics() {
1325        proptest::proptest!(|(msg in ".{0,200}")| {
1326            let errors = vec![
1327                Error::Connect(msg.clone()),
1328                Error::Io(std::sync::Arc::new(std::io::Error::other(msg.clone()))),
1329                Error::InvalidUrl(msg.clone()),
1330                Error::Tls(msg.clone()),
1331                Error::Protocol(msg.clone()),
1332                Error::Body(msg.clone()),
1333            ];
1334            for err in &errors {
1335                let _ = RetryPolicy::is_error_retryable(err);
1336            }
1337        });
1338    }
1339}