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