use std::time::{Duration, SystemTime};
use reqwest::header::{HeaderMap, RETRY_AFTER};
const NEVER_RETRIED: [u16; 5] = [400, 401, 403, 404, 422];
const RETRY_AFTER_MS: &str = "retry-after-ms";
#[derive(Clone, Debug, PartialEq)]
#[non_exhaustive]
pub struct RetryPolicy {
pub max_retries: u32,
pub backoff_initial: Duration,
pub backoff_max: Duration,
pub backoff_jitter: f64,
pub timeout: Duration,
pub respect_retry_after: bool,
pub max_retry_after: Duration,
pub retry_connection_errors: bool,
pub retry_timeouts: bool,
pub retry_statuses: Vec<u16>,
}
impl Default for RetryPolicy {
fn default() -> Self {
Self {
max_retries: 2,
backoff_initial: Duration::from_millis(500),
backoff_max: Duration::from_secs(5),
backoff_jitter: 0.25,
timeout: Duration::from_secs(30),
respect_retry_after: true,
max_retry_after: Duration::from_secs(60),
retry_connection_errors: true,
retry_timeouts: true,
retry_statuses: [408, 429].into_iter().chain(500..=599).collect(),
}
}
}
impl RetryPolicy {
#[must_use]
pub fn none() -> Self {
Self::default().with_max_retries(0)
}
#[must_use]
pub const fn with_max_retries(mut self, max_retries: u32) -> Self {
self.max_retries = max_retries;
self
}
#[must_use]
pub const fn with_backoff(mut self, initial: Duration, max: Duration) -> Self {
self.backoff_initial = initial;
self.backoff_max = max;
self
}
#[must_use]
pub const fn with_jitter(mut self, fraction: f64) -> Self {
self.backoff_jitter = fraction;
self
}
#[must_use]
pub const fn with_timeout(mut self, timeout: Duration) -> Self {
self.timeout = timeout;
self
}
#[must_use]
pub fn retries_status(&self, status: u16) -> bool {
!NEVER_RETRIED.contains(&status) && self.retry_statuses.contains(&status)
}
#[must_use]
pub fn backoff_delay(&self, retry: u32, random: f64) -> Duration {
let doubled = self
.backoff_initial
.saturating_mul(2_u32.saturating_pow(retry));
let capped = doubled.min(self.backoff_max);
let jitter = clamp_unit(self.backoff_jitter);
capped.mul_f64(1.0 - jitter * clamp_unit(random))
}
pub(crate) fn delay(
&self,
retry: u32,
server_delay: Option<Duration>,
random: f64,
) -> Duration {
server_delay
.filter(|delay| self.respect_retry_after && *delay <= self.max_retry_after)
.unwrap_or_else(|| self.backoff_delay(retry, random))
}
}
fn clamp_unit(value: f64) -> f64 {
if value.is_nan() {
0.0
} else {
value.clamp(0.0, 1.0)
}
}
pub(crate) fn server_delay(headers: &HeaderMap, now: SystemTime) -> Option<Duration> {
let text = |name: &str| headers.get(name)?.to_str().ok().map(str::trim);
if let Some(milliseconds) = text(RETRY_AFTER_MS).and_then(|value| value.parse::<f64>().ok()) {
return duration_from_secs(milliseconds / 1000.0);
}
let value = text(RETRY_AFTER.as_str())?;
if let Ok(seconds) = value.parse::<f64>() {
return duration_from_secs(seconds);
}
let date = httpdate::parse_http_date(value).ok()?;
Some(date.duration_since(now).unwrap_or(Duration::ZERO))
}
fn duration_from_secs(seconds: f64) -> Option<Duration> {
Duration::try_from_secs_f64(seconds).ok()
}
#[cfg(test)]
mod tests {
use std::time::{Duration, SystemTime};
use reqwest::header::{HeaderMap, HeaderValue};
use super::{RetryPolicy, server_delay};
fn headers(pairs: &[(&'static str, &'static str)]) -> HeaderMap {
pairs
.iter()
.map(|&(name, value)| (name.parse().unwrap(), HeaderValue::from_static(value)))
.collect()
}
#[test]
fn the_defaults_match_the_official_sdks() {
let policy = RetryPolicy::default();
assert_eq!(policy.max_retries, 2);
assert_eq!(policy.backoff_initial, Duration::from_millis(500));
assert_eq!(policy.backoff_max, Duration::from_secs(5));
assert_eq!(policy.backoff_jitter.to_bits(), 0.25_f64.to_bits());
assert_eq!(policy.timeout, Duration::from_secs(30));
assert_eq!(policy.max_retry_after, Duration::from_secs(60));
assert!(
policy.respect_retry_after && policy.retry_connection_errors && policy.retry_timeouts
);
}
#[test]
fn retries_408_429_and_every_5xx_including_529() {
let policy = RetryPolicy::default();
for status in [408, 429, 500, 502, 503, 504, 529, 599] {
assert!(policy.retries_status(status), "{status}");
}
for status in [200, 302, 400, 401, 403, 404, 409, 422, 499] {
assert!(!policy.retries_status(status), "{status}");
}
}
#[test]
fn request_errors_are_never_retried_even_when_the_policy_lists_them() {
let policy = RetryPolicy {
retry_statuses: vec![400, 401, 403, 404, 409, 422],
..RetryPolicy::default()
};
for status in [400, 401, 403, 404, 422] {
assert!(!policy.retries_status(status), "{status}");
}
assert!(policy.retries_status(409));
}
#[test]
fn backoff_doubles_from_half_a_second_up_to_the_cap() {
let policy = RetryPolicy::default().with_jitter(0.0);
let delays: Vec<u128> = (0..6)
.map(|retry| policy.backoff_delay(retry, 0.5).as_millis())
.collect();
assert_eq!(delays, [500, 1000, 2000, 4000, 5000, 5000]);
assert_eq!(
policy.backoff_delay(u32::MAX, 0.5),
Duration::from_secs(5),
"no overflow"
);
}
#[test]
fn jitter_only_ever_subtracts_up_to_its_fraction() {
let policy = RetryPolicy::default();
assert_eq!(policy.backoff_delay(0, 0.0), Duration::from_millis(500));
assert_eq!(policy.backoff_delay(0, 1.0), Duration::from_millis(375));
assert_eq!(policy.backoff_delay(0, 0.5), Duration::from_micros(437_500));
}
#[test]
fn nonsense_jitter_and_random_values_are_clamped() {
let full = RetryPolicy::default().with_jitter(7.0);
let negative = RetryPolicy::default().with_jitter(-1.0);
let nan = RetryPolicy::default().with_jitter(f64::NAN);
assert_eq!(full.backoff_delay(0, 1.0), Duration::ZERO);
assert_eq!(negative.backoff_delay(0, 1.0), Duration::from_millis(500));
assert_eq!(nan.backoff_delay(0, 1.0), Duration::from_millis(500));
assert_eq!(
RetryPolicy::default().backoff_delay(0, f64::NAN),
Duration::from_millis(500)
);
assert_eq!(
RetryPolicy::default().backoff_delay(0, -3.0),
Duration::from_millis(500)
);
}
#[test]
fn reads_the_server_delay_in_seconds_milliseconds_or_as_a_date() {
let now = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
assert_eq!(
server_delay(&headers(&[("retry-after", "1")]), now),
Some(Duration::from_secs(1))
);
assert_eq!(
server_delay(&headers(&[("retry-after", " 2.5 ")]), now),
Some(Duration::from_millis(2500))
);
assert_eq!(
server_delay(&headers(&[("retry-after-ms", "250")]), now),
Some(Duration::from_millis(250))
);
assert_eq!(
server_delay(
&headers(&[("retry-after", "Sun, 09 Sep 2001 01:46:50 GMT")]),
now
),
Some(Duration::from_secs(10))
);
assert_eq!(
server_delay(
&headers(&[("retry-after", "Sun, 09 Sep 2001 01:00:00 GMT")]),
now
),
Some(Duration::ZERO),
"a date in the past means now"
);
}
#[test]
fn milliseconds_win_over_seconds_and_unreadable_values_are_ignored() {
let now = SystemTime::UNIX_EPOCH;
let both = headers(&[("retry-after", "30"), ("retry-after-ms", "100")]);
assert_eq!(server_delay(&both, now), Some(Duration::from_millis(100)));
for value in ["soon", "-1", "NaN", "inf", ""] {
assert_eq!(
server_delay(&headers(&[("retry-after", value)]), now),
None,
"{value:?}"
);
}
assert_eq!(server_delay(&HeaderMap::new(), now), None);
}
#[test]
fn an_acceptable_server_delay_replaces_backoff_and_an_excessive_one_does_not() {
let policy = RetryPolicy::default().with_jitter(0.0);
assert_eq!(
policy.delay(0, Some(Duration::from_secs(1)), 0.0),
Duration::from_secs(1)
);
assert_eq!(
policy.delay(0, Some(Duration::from_secs(60)), 0.0),
Duration::from_secs(60)
);
assert_eq!(
policy.delay(1, Some(Duration::from_secs(61)), 0.0),
Duration::from_secs(1)
);
assert_eq!(policy.delay(1, None, 0.0), Duration::from_secs(1));
let deaf = RetryPolicy {
respect_retry_after: false,
..policy
};
assert_eq!(
deaf.delay(0, Some(Duration::from_secs(9)), 0.0),
Duration::from_millis(500)
);
}
}