From: Christian Ebner <c.ebner@proxmox.com>
To: pbs-devel@lists.proxmox.com
Subject: [PATCH proxmox v5 05/12] s3-client: honor response header directed retry delays
Date: Mon, 16 Nov 2026 10:54:27 +0100 [thread overview]
Message-ID: <20261116095434.110541-6-c.ebner@proxmox.com> (raw)
In-Reply-To: <20261116095434.110541-1-c.ebner@proxmox.com>
S3 API servers can tell clients when they expect to have capacity
available again by setting the x-amz-retry-after or Retry-After
header. The former is provided in milliseconds, the latter either as
integer seconds or http date. Since retrying earlier is likely to
fail again and only adds load, try to honor these server provided
delays before the next retry.
Use the server's requested delay instead of the computed backoff, but
never wait less than the backoff and at most 5 seconds longer, so a
misbehaving server cannot stall requests for a long time. No jitter
is applied, the server is expected to randomize the delay itself.
This follows the AWS SDKs implementation guide with respect to
x-amz-retry-after and general http protocol for Retry-After.
Link: https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html
Link: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After
Signed-off-by: Christian Ebner <c.ebner@proxmox.com>
---
proxmox-s3-client/src/client.rs | 99 ++++++++++++++++++++++++++++-
proxmox-s3-client/src/timestamps.rs | 7 ++
2 files changed, 103 insertions(+), 3 deletions(-)
diff --git a/proxmox-s3-client/src/client.rs b/proxmox-s3-client/src/client.rs
index 149b421c..c4fb2733 100644
--- a/proxmox-s3-client/src/client.rs
+++ b/proxmox-s3-client/src/client.rs
@@ -53,6 +53,8 @@ const MAX_S3_HTTP_REQUEST_RETRY: usize = 3;
const S3_RETRY_BASE_DELAY_TRANSIENT: Duration = Duration::from_millis(100);
const S3_RETRY_BASE_DELAY_THROTTLING: Duration = Duration::from_secs(2);
const S3_RETRY_MAX_BACKOFF: Duration = Duration::from_secs(20);
+// Maximum time a header directed retry delay may exceed the computed backoff.
+const S3_RETRY_AFTER_MAX_EXCESS: Duration = Duration::from_secs(5);
// Response body error codes interpreted as retry with throttled delay instead of transient delay.
const S3_THROTTLING_ERROR_CODES: &[&str] = &[
"Throttling",
@@ -558,8 +560,13 @@ impl S3Client {
return Ok(response?);
};
- // The response is discarded on retry, so use it to check the error code to detect
- // throttling signaled with a server error status.
+ let retry_after = response
+ .as_ref()
+ .ok()
+ .and_then(|response| parse_retry_after(response.headers()));
+
+ // The response is discarded for the retry anyway, so check its error code to detect
+ // throttling signaled with a server error status, for example S3's 503 SlowDown.
let retry_reason = match response {
Ok(response) if retry_reason == RetryReason::Transient => {
let response_body = response.into_body().collect();
@@ -580,7 +587,8 @@ impl S3Client {
_ => retry_reason,
};
- tokio::time::sleep(retry_backoff_with_jitter(retry_reason, retry)).await;
+ let backoff = retry_backoff(retry_reason, retry);
+ tokio::time::sleep(server_directed_delay(retry_after, backoff)).await;
}
bail!("failed to send request exceeding retries");
@@ -1130,6 +1138,42 @@ fn with_jitter(backoff: Duration) -> Duration {
}
}
+/// Parse the server directed retry delay from the response headers, if any.
+///
+/// Checks `x-amz-retry-after` (given in milliseconds) first, and falls back to the standard HTTP
+/// `Retry-After` header (given in integer seconds or as an HTTP-date) if not set.
+fn parse_retry_after(headers: &header::HeaderMap) -> Option<Duration> {
+ if let Some(millis) = headers
+ .get("x-amz-retry-after")
+ .and_then(|value| value.to_str().ok())
+ .and_then(|value| value.trim().parse().ok())
+ {
+ return Some(Duration::from_millis(millis));
+ }
+
+ let value = headers.get(header::RETRY_AFTER)?.to_str().ok()?.trim();
+ if let Ok(secs) = value.parse::<u64>() {
+ return Some(Duration::from_secs(secs));
+ }
+
+ let date = crate::HttpDate::from_str(value).ok()?;
+ let delay_secs = date
+ .epoch()
+ .saturating_sub(proxmox_time::epoch_i64())
+ .max(0) as u64;
+ Some(Duration::from_secs(delay_secs))
+}
+
+/// Use the response header directed retry delay if given, but never wait less than the computed
+/// backoff and at most a few seconds longer. The server is expected to randomize the delay, so
+/// no further jitter is applied.
+fn server_directed_delay(retry_after: Option<Duration>, backoff: Duration) -> Duration {
+ match retry_after {
+ Some(retry_after) => retry_after.clamp(backoff, backoff + S3_RETRY_AFTER_MAX_EXCESS),
+ None => with_jitter(backoff),
+ }
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -1175,6 +1219,55 @@ mod tests {
);
}
+ #[test]
+ fn retry_after_header() {
+ let mut headers = header::HeaderMap::new();
+ assert_eq!(parse_retry_after(&headers), None);
+ headers.insert("x-amz-retry-after", HeaderValue::from_static("1500"));
+ assert_eq!(
+ parse_retry_after(&headers),
+ Some(Duration::from_millis(1500))
+ );
+ headers.insert("x-amz-retry-after", HeaderValue::from_static("soon"));
+ assert_eq!(parse_retry_after(&headers), None);
+ headers.insert("x-amz-retry-after", HeaderValue::from_static("-1"));
+ assert_eq!(parse_retry_after(&headers), None);
+
+ headers.clear();
+ headers.insert(header::RETRY_AFTER, HeaderValue::from_static("3"));
+ assert_eq!(parse_retry_after(&headers), Some(Duration::from_secs(3)));
+ headers.insert(
+ header::RETRY_AFTER,
+ HeaderValue::from_static("Wed, 12 Oct 2009 17:50:00 GMT"),
+ );
+ assert_eq!(parse_retry_after(&headers), Some(Duration::ZERO));
+ headers.insert(
+ header::RETRY_AFTER,
+ HeaderValue::from_static("Thu, 01 Jan 2099 00:00:00 GMT"),
+ );
+ assert!(parse_retry_after(&headers).is_some_and(|delay| delay > Duration::ZERO));
+ headers.insert(header::RETRY_AFTER, HeaderValue::from_static("invalid"));
+ assert_eq!(parse_retry_after(&headers), None);
+ }
+
+ #[test]
+ fn server_directed_delay_is_clamped() {
+ let backoff = Duration::from_secs(1);
+ assert!(server_directed_delay(None, backoff) <= backoff);
+ assert_eq!(
+ server_directed_delay(Some(Duration::from_secs(3)), backoff),
+ Duration::from_secs(3)
+ );
+ assert_eq!(
+ server_directed_delay(Some(Duration::from_millis(10)), backoff),
+ backoff
+ );
+ assert_eq!(
+ server_directed_delay(Some(Duration::from_secs(60)), backoff),
+ Duration::from_secs(6)
+ );
+ }
+
#[test]
fn with_jitter_within_backoff() {
let backoff = Duration::from_secs(1);
diff --git a/proxmox-s3-client/src/timestamps.rs b/proxmox-s3-client/src/timestamps.rs
index af4c7d71..163a116e 100644
--- a/proxmox-s3-client/src/timestamps.rs
+++ b/proxmox-s3-client/src/timestamps.rs
@@ -33,6 +33,13 @@ pub struct HttpDate {
_epoch: i64,
}
+impl HttpDate {
+ /// Returns the Unix epoch timestamp in seconds.
+ pub(crate) fn epoch(&self) -> i64 {
+ self._epoch
+ }
+}
+
impl std::str::FromStr for HttpDate {
type Err = Error;
--
2.47.3
next prev parent reply other threads:[~2026-11-16 9:55 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-16 9:54 [PATCH proxmox{,-backup} v5 00/12] fix #7606: verify: s3: handle transient fetch errors and add retry Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox v5 01/12] s3-client: also retry requests on bad gateway responses Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox v5 02/12] s3-client: distinguish transient errors and throttled requests Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox v5 03/12] s3-client: detect throttling request from the response body on error Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox v5 04/12] s3-client: avoid retry bursts by adding jitter to retry backoff delay Christian Ebner
2026-11-16 9:54 ` Christian Ebner [this message]
2026-11-16 9:54 ` [PATCH proxmox v5 06/12] s3-client: add additional backoff delay between upload retries Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox v5 07/12] s3-client: add helper to fetch object contents with retry Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox v5 08/12] s3-client: add shared rate limiter based retry quota Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox-backup v5 09/12] s3: retry fetching object contents on body collection errors Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox-backup v5 10/12] datastore: snapshot: propagate errors in manifest update callback Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox-backup v5 11/12] fix #7606: verify: s3: handle transient chunk load errors Christian Ebner
2026-11-16 9:54 ` [PATCH proxmox-backup v5 12/12] verify: s3: stop early if the endpoint appears unreachable Christian Ebner
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261116095434.110541-6-c.ebner@proxmox.com \
--to=c.ebner@proxmox.com \
--cc=pbs-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.