qcs_api_client_common/
backoff.rs

1//! Exponential backoff for use with QCS.
2//!
3//! This re-exports types from [`backoff`](::backoff) and provides a [`default_backoff`] function
4//! to create a more useful default [`ExpontentialBackoff`].
5
6use std::{error::Error, time::Duration};
7
8use qcs_dependencies_client::http::StatusCode;
9
10use ::backoff::backoff::Backoff;
11pub use ::backoff::*;
12
13/// Create a default [`ExponentialBackoff`] for use with QCS.
14///
15/// This backoff will retry for up to 5 minutes, with a maximum interval of 30 seconds and some
16/// randomized jitter.
17#[allow(clippy::module_name_repetitions)]
18#[must_use]
19pub fn default_backoff() -> ExponentialBackoff {
20    ExponentialBackoffBuilder::new()
21        .with_max_elapsed_time(Some(Duration::from_secs(300)))
22        .with_max_interval(Duration::from_secs(30))
23        .build()
24}
25
26/// Return `true` if the status code is one that could be retried.
27#[must_use]
28pub const fn status_code_is_retry(code: StatusCode) -> bool {
29    matches!(
30        code,
31        StatusCode::SERVICE_UNAVAILABLE | StatusCode::BAD_GATEWAY | StatusCode::TOO_MANY_REQUESTS
32    )
33}
34
35/// Return `Some` if the response specifies a `Retry-After` header or the provided `backoff` has
36/// another backoff to try. If `None` is returned, the request should not be retried.
37#[must_use]
38pub fn duration_from_response(
39    status: StatusCode,
40    headers: &qcs_dependencies_client::http::HeaderMap,
41    backoff: &mut ExponentialBackoff,
42) -> Option<Duration> {
43    use time::{OffsetDateTime, format_description::well_known::Rfc2822};
44
45    if status_code_is_retry(status) {
46        if let Some(value) = headers.get(qcs_dependencies_client::http::header::RETRY_AFTER) {
47            if let Ok(value) = value.to_str() {
48                if let Ok(value) = value.parse::<u64>() {
49                    return Some(Duration::from_secs(value));
50                } else if let Ok(date) = OffsetDateTime::parse(value, &Rfc2822) {
51                    let duration = date - OffsetDateTime::now_utc();
52                    // Convert from time::Duration to std::time::Duration
53                    // This will fail if the number is too large or negative
54                    let std_duration: Duration = duration.try_into().ok()?;
55                    return Some(std_duration);
56                }
57            }
58        }
59
60        backoff.next_backoff()
61    } else {
62        None
63    }
64}
65
66fn can_retry_method(method: &qcs_dependencies_client::http::Method) -> bool {
67    // Safe means the method is essentially read-only (see https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.1)
68    // Idempotent means multiple identical requests have the same side-effects as a single one (see https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2)
69
70    // Idempotent methods are defined as safe methods + PUT and DELETE.
71    // Since we have some API endpoints using PUT and DELETE that are not idempotent, this function
72    // currently returns just safe methods.
73
74    method.is_safe()
75}
76
77/// Return `Some` if the error is one that makes sense to retry and `method` is one that indicates
78/// it is safe to retry.
79#[must_use]
80pub fn duration_from_reqwest_error(
81    method: &qcs_dependencies_client::http::Method,
82    error: &qcs_dependencies_client::reqwest::Error,
83    backoff: &mut ExponentialBackoff,
84) -> Option<Duration> {
85    if can_retry_method(method) {
86        if error.is_timeout()
87            || error.is_connect()
88            || error.is_request()
89            || error
90                .source()
91                .and_then(|inner| inner.downcast_ref::<hyper::Error>())
92                .map(|hyper_error| hyper_error.is_closed())
93                .unwrap_or_default()
94        {
95            backoff.next_backoff()
96        } else {
97            None
98        }
99    } else {
100        None
101    }
102}
103
104/// Return `Some` if the error is one that makes sense to retry and `method` is one that indicates
105/// it is safe to retry.
106#[must_use]
107pub fn duration_from_io_error(
108    method: &qcs_dependencies_client::http::Method,
109    error: &std::io::Error,
110    backoff: &mut ExponentialBackoff,
111) -> Option<Duration> {
112    use std::io::ErrorKind;
113    if can_retry_method(method) {
114        if matches!(
115            error.kind(),
116            ErrorKind::ConnectionReset | ErrorKind::ConnectionAborted
117        ) {
118            backoff.next_backoff()
119        } else {
120            None
121        }
122    } else {
123        None
124    }
125}
qcs_api_client_common/backoff.rs

qcs_api_client_common/
backoff.rs
