1use 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
28const DEFAULT_RETRYABLE_STATUSES: &[u16] = &[408, 429, 502, 503, 504];
30
31#[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
42const DEFAULT_RETRYABLE_METHODS: &[Method] = &[Method::GET, Method::HEAD, Method::OPTIONS];
44
45#[derive(Debug, Clone)]
65pub struct RetryPolicy {
66 max_attempts: usize,
68 max_elapsed: Option<Duration>,
70 backoff: BackoffPolicy,
72 method_policy: MethodPolicy,
74 status_policy: StatusPolicy,
76 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 #[must_use]
96 pub fn builder() -> RetryPolicyBuilder {
97 RetryPolicyBuilder::new()
98 }
99
100 #[must_use]
102 pub fn max_attempts(&self) -> usize {
103 self.max_attempts
104 }
105
106 #[must_use]
108 pub fn max_elapsed(&self) -> Option<Duration> {
109 self.max_elapsed
110 }
111
112 #[must_use]
114 pub fn backoff(&self) -> &BackoffPolicy {
115 &self.backoff
116 }
117
118 #[must_use]
120 pub fn method_policy(&self) -> &MethodPolicy {
121 &self.method_policy
122 }
123
124 #[must_use]
126 pub fn status_policy(&self) -> &StatusPolicy {
127 &self.status_policy
128 }
129
130 #[must_use]
132 pub fn respect_retry_after(&self) -> bool {
133 self.respect_retry_after
134 }
135
136 #[must_use]
138 pub fn is_enabled(&self) -> bool {
139 self.max_attempts > 1
140 }
141
142 #[must_use]
144 pub fn is_method_retryable(&self, method: &Method) -> bool {
145 self.method_policy.is_retryable(method)
146 }
147
148 #[must_use]
150 pub fn is_status_retryable(&self, status: u16) -> bool {
151 self.status_policy.is_retryable(status)
152 }
153
154 #[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 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 #[must_use]
201 pub fn backoff_delay(&self, attempt: usize) -> Option<Duration> {
202 self.backoff.delay(attempt)
203 }
204
205 #[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 #[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
244pub 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 #[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 #[must_use]
274 pub fn max_attempts(mut self, max: usize) -> Self {
275 self.max_attempts = max;
276 self
277 }
278
279 #[must_use]
283 pub fn max_elapsed(mut self, elapsed: Duration) -> Self {
284 self.max_elapsed = Some(elapsed);
285 self
286 }
287
288 #[must_use]
294 pub fn backoff_factor(mut self, factor: f64) -> Self {
295 self.backoff = self.backoff.factor(factor);
296 self
297 }
298
299 #[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 #[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 #[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 #[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 #[must_use]
337 pub fn retry_method(mut self, method: Method) -> Self {
338 self.method_policy.add_method(method);
339 self
340 }
341
342 #[must_use]
344 pub fn allow_post_retry(mut self) -> Self {
345 self.method_policy.add_method(Method::POST);
346 self
347 }
348
349 #[must_use]
351 pub fn allow_put_retry(mut self) -> Self {
352 self.method_policy.add_method(Method::PUT);
353 self
354 }
355
356 #[must_use]
358 pub fn allow_delete_retry(mut self) -> Self {
359 self.method_policy.add_method(Method::DELETE);
360 self
361 }
362
363 #[must_use]
365 pub fn allow_patch_retry(mut self) -> Self {
366 self.method_policy.add_method(Method::PATCH);
367 self
368 }
369
370 #[must_use]
372 pub fn respect_retry_after(mut self, respect: bool) -> Self {
373 self.respect_retry_after = respect;
374 self
375 }
376
377 #[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#[derive(Debug, Clone)]
399pub struct BackoffPolicy {
400 factor: f64,
402 max_delay: Duration,
404 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 #[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 let exp = (attempt - 2) as f64;
437 let raw = self.initial_delay.as_secs_f64() * self.factor.powf(exp);
438 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 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 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 Duration::try_from_secs_f64(jittered_secs).unwrap_or(capped)
475 };
476
477 Some(final_delay.max(Duration::from_millis(1).min(capped)))
481 }
482
483 #[must_use]
485 pub fn max_delay(&self) -> Duration {
486 self.max_delay
487 }
488
489 #[must_use]
491 pub fn factor(&self) -> f64 {
492 self.factor
493 }
494
495 #[must_use]
497 pub fn initial_delay(&self) -> Duration {
498 self.initial_delay
499 }
500}
501
502pub 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 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#[derive(Debug, Clone)]
552pub struct MethodPolicy {
553 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 #[must_use]
568 pub fn new(methods: Vec<Method>) -> Self {
569 Self { methods }
570 }
571
572 pub fn add_method(&mut self, method: Method) {
574 if !self.methods.contains(&method) {
575 self.methods.push(method);
576 }
577 }
578
579 #[must_use]
581 pub fn is_retryable(&self, method: &Method) -> bool {
582 self.methods.contains(method)
583 }
584
585 #[must_use]
587 pub fn methods(&self) -> &[Method] {
588 &self.methods
589 }
590}
591
592#[derive(Debug, Clone)]
594pub struct StatusPolicy {
595 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 #[must_use]
610 pub fn new(statuses: impl IntoIterator<Item = u16>) -> Self {
611 Self {
612 statuses: statuses.into_iter().collect(),
613 }
614 }
615
616 #[must_use]
618 pub fn default_empty() -> Self {
619 Self {
620 statuses: Vec::new(),
621 }
622 }
623
624 pub fn add_status(&mut self, status: u16) {
626 if !self.statuses.contains(&status) {
627 self.statuses.push(status);
628 }
629 }
630
631 #[must_use]
633 pub fn is_retryable(&self, status: u16) -> bool {
634 self.statuses.contains(&status)
635 }
636
637 #[must_use]
639 pub fn statuses(&self) -> &[u16] {
640 &self.statuses
641 }
642}
643
644#[derive(Debug, Clone, Copy, PartialEq, Eq)]
646pub enum ReplayCheck {
647 Replayable,
649 NotReplayable,
651}
652
653#[derive(Debug, Clone, PartialEq, Eq)]
655pub enum RetryCause {
656 TransportError(String),
658 Status(u16),
660 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#[derive(Debug, Clone)]
676pub struct RetryContext {
677 pub attempt: usize,
679 pub method: Method,
681 pub body_replayable: bool,
683 pub cause: RetryCause,
685 pub remaining_total: Option<Duration>,
687}
688
689#[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 if !policy.is_method_retryable(method) {
703 return None;
704 }
705
706 if !body.is_replayable() {
708 return None;
709 }
710
711 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 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#[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 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 #[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 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 for _ in 0..10_000 {
830 let Some(jitter) = get_random_f64() else {
831 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 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 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)); }
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 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 ); 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 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 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}