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