public inbox for pbs-devel@lists.proxmox.com
 help / color / mirror / Atom feed
From: Christian Ebner <c.ebner@proxmox.com>
To: pbs-devel@lists.proxmox.com
Subject: [PATCH proxmox v3 02/11] s3-client: distinguish transient errors and throttled requests
Date: Thu, 12 Nov 2026 19:01:10 +0100	[thread overview]
Message-ID: <20261112180119.660923-3-c.ebner@proxmox.com> (raw)
In-Reply-To: <20261112180119.660923-1-c.ebner@proxmox.com>

Currently failed requests are retried after a fixed 1 and 3 seconds,
regardless of the cause. This is longer than needed for connection or
server errors, only intended as graceful recovery period for heavily
loaded S3 APIs in the previous implementation.

Therefore, distinguish these 2 modes by following the backoff logic
use by the AWS SDK's standard retry mode instead: wait base * 2^retry,
capped at 20 seconds, with a base delay of 50 ms for transient errors
and 1 second for throttling.

Cover only the too many requests http status code for now, additional
status codes will use this based on the error code in the response
body parsing as extended in subsequent changes.

Link: https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html
Signed-off-by: Christian Ebner <c.ebner@proxmox.com>
---
 proxmox-s3-client/src/client.rs | 110 ++++++++++++++++++++++++++++----
 1 file changed, 96 insertions(+), 14 deletions(-)

diff --git a/proxmox-s3-client/src/client.rs b/proxmox-s3-client/src/client.rs
index 3f2a7107..677557f9 100644
--- a/proxmox-s3-client/src/client.rs
+++ b/proxmox-s3-client/src/client.rs
@@ -47,7 +47,11 @@ const MAX_S3_UPLOAD_RETRY: usize = 3;
 // Assumed minimum upload rate of 1 KiB/s for dynamic put object request timeout calculation.
 const S3_MIN_ASSUMED_UPLOAD_RATE: u64 = 1024;
 const MAX_S3_HTTP_REQUEST_RETRY: usize = 3;
-const S3_HTTP_REQUEST_RETRY_BACKOFF_DEFAULT: Duration = Duration::from_secs(1);
+// Retry backoff as used by the AWS SDKs standard retry mode, see
+// https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html
+const S3_RETRY_BASE_DELAY_TRANSIENT: Duration = Duration::from_millis(50);
+const S3_RETRY_BASE_DELAY_THROTTLING: Duration = Duration::from_secs(1);
+const S3_RETRY_MAX_BACKOFF: Duration = Duration::from_secs(20);
 
 static SHARED_COUNTER_FLUSHER: LazyLock<RwLock<MmapFlusher>> =
     LazyLock::new(|| RwLock::new(MmapFlusher::new()));
@@ -506,19 +510,20 @@ impl S3Client {
                 self.client.request(request).await
             };
 
-            let do_retry = match &response {
-                Ok(response) => matches!(
-                    response.status(),
+            let retry_reason = match &response {
+                Ok(response) => match response.status() {
                     StatusCode::INTERNAL_SERVER_ERROR
-                        | StatusCode::BAD_GATEWAY
-                        | StatusCode::SERVICE_UNAVAILABLE
-                        | StatusCode::GATEWAY_TIMEOUT
-                        | StatusCode::TOO_MANY_REQUESTS
-                ),
-                Err(_) => true,
+                    | StatusCode::BAD_GATEWAY
+                    | StatusCode::SERVICE_UNAVAILABLE
+                    | StatusCode::GATEWAY_TIMEOUT => Some(RetryReason::Transient),
+                    StatusCode::TOO_MANY_REQUESTS => Some(RetryReason::Throttling),
+                    _ => None,
+                },
+                Err(_) => Some(RetryReason::Transient),
             };
 
-            if !do_retry || retry >= MAX_S3_HTTP_REQUEST_RETRY - 1 {
+            let Some(retry_reason) = retry_reason.filter(|_| retry < MAX_S3_HTTP_REQUEST_RETRY - 1)
+            else {
                 if let Some(counters) = self.request_counters.as_ref()
                     && response.is_ok()
                 {
@@ -533,10 +538,9 @@ impl S3Client {
                     let _ = SHARED_COUNTER_FLUSHER.read().unwrap().request_flush();
                 }
                 return Ok(response?);
-            }
+            };
 
-            let backoff_secs = S3_HTTP_REQUEST_RETRY_BACKOFF_DEFAULT * 3_u32.pow(retry as u32);
-            tokio::time::sleep(backoff_secs).await;
+            tokio::time::sleep(retry_backoff(retry_reason, retry)).await;
         }
 
         bail!("failed to send request exceeding retries");
@@ -1026,10 +1030,88 @@ impl S3Client {
     }
 }
 
+#[derive(Debug, PartialEq)]
+enum RetryReason {
+    Transient,
+    Throttling,
+}
+
+impl RetryReason {
+    fn base_delay(self) -> Duration {
+        match self {
+            Self::Transient => S3_RETRY_BASE_DELAY_TRANSIENT,
+            Self::Throttling => S3_RETRY_BASE_DELAY_THROTTLING,
+        }
+    }
+}
+
+/// Helper to get exponential backoff duration based on retry reason and count.
+///
+/// Calculates how long to wait before the next retry attempt for a request.
+/// The duration is limited by an upper bond of [`S3_RETRY_MAX_BACKOFF`].
+fn retry_backoff(reason: RetryReason, retry: usize) -> Duration {
+    u32::try_from(retry)
+        .ok()
+        .and_then(|retry| 2_u32.checked_pow(retry))
+        .and_then(|factor| reason.base_delay().checked_mul(factor))
+        .map_or(S3_RETRY_MAX_BACKOFF, |backoff| {
+            backoff.min(S3_RETRY_MAX_BACKOFF)
+        })
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    #[test]
+    fn retry_backoff_by_reason() {
+        assert_eq!(
+            retry_backoff(RetryReason::Transient, 0),
+            Duration::from_millis(50)
+        );
+        assert_eq!(
+            retry_backoff(RetryReason::Transient, 1),
+            Duration::from_millis(100)
+        );
+        assert_eq!(
+            retry_backoff(RetryReason::Throttling, 0),
+            Duration::from_secs(1)
+        );
+        assert_eq!(
+            retry_backoff(RetryReason::Throttling, 1),
+            Duration::from_secs(2)
+        );
+    }
+
+    #[test]
+    fn retry_backoff_is_capped() {
+        assert_eq!(
+            retry_backoff(RetryReason::Transient, 8),
+            Duration::from_millis(12_800)
+        );
+        assert_eq!(
+            retry_backoff(RetryReason::Transient, 9),
+            S3_RETRY_MAX_BACKOFF
+        );
+        assert_eq!(
+            retry_backoff(RetryReason::Throttling, 4),
+            Duration::from_secs(16)
+        );
+        assert_eq!(
+            retry_backoff(RetryReason::Throttling, 5),
+            S3_RETRY_MAX_BACKOFF
+        );
+        // must not overflow
+        assert_eq!(
+            retry_backoff(RetryReason::Throttling, 64),
+            S3_RETRY_MAX_BACKOFF
+        );
+        assert_eq!(
+            retry_backoff(RetryReason::Transient, usize::MAX),
+            S3_RETRY_MAX_BACKOFF
+        );
+    }
+
     struct TestDirectory(PathBuf);
 
     impl Drop for TestDirectory {
-- 
2.47.3





  parent reply	other threads:[~2026-11-12 18:02 UTC|newest]

Thread overview: 14+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-12 18:01 [PATCH proxmox{,-backup} v3 00/11] fix #7606: verify: s3: handle transient fetch errors and add retry Christian Ebner
2026-11-12 18:01 ` [PATCH proxmox v3 01/11] s3-client: also retry requests on bad gateway responses Christian Ebner
2026-11-12 18:01 ` Christian Ebner [this message]
2026-11-12 18:01 ` [PATCH proxmox v3 03/11] s3-client: detect throttling request from the response body on error Christian Ebner
2026-11-12 18:01 ` [PATCH proxmox v3 04/11] s3-client: avoid retry bursts by adding jitter to retry backoff delay Christian Ebner
2026-11-12 18:01 ` [PATCH proxmox v3 05/11] s3-client: honor response header directed retry delays Christian Ebner
2026-11-13  8:13   ` Christian Ebner
2026-11-12 18:01 ` [PATCH proxmox v3 06/11] s3-client: add additional backoff delay between upload retries Christian Ebner
2026-11-12 18:01 ` [PATCH proxmox v3 07/11] s3-client: add helper to fetch object contents with retry Christian Ebner
2026-11-12 18:01 ` [PATCH proxmox-backup v3 08/11] s3: retry fetching object contents on body collection errors Christian Ebner
2026-11-12 18:01 ` [PATCH proxmox-backup v3 09/11] datastore: snapshot: propagate errors in manifest update callback Christian Ebner
2026-11-12 18:01 ` [PATCH proxmox-backup v3 10/11] fix #7606: verify: s3: handle transient chunk load errors Christian Ebner
2026-11-12 18:01 ` [PATCH proxmox-backup v3 11/11] verify: s3: stop early if the endpoint appears unreachable Christian Ebner
2026-11-13 14:23 ` superseded: [PATCH proxmox{,-backup} v3 00/11] fix #7606: verify: s3: handle transient fetch errors and add retry 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=20261112180119.660923-3-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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal