feat: add automatic S3 request retry with exponential backoff

Implements SDK-level automatic retry matching the minio-go retry-mechanism
spec. All requests through BaseS3Client.executeAsync() now retry on
retryable S3 error codes (InternalError, SlowDown, RequestTimeout, etc.),
retryable HTTP status codes (408, 429, 499, 500, 502, 503, 504, 520), and
transient IO errors (connection reset, EOF, server closed idle connection).

Non-seekable request bodies (raw okhttp3.RequestBody) get a single attempt;
seekable bodies (byte[], ByteBuffer, RandomAccessFile) retry up to maxRetries
(default 10). Backoff is full-jitter exponential: rand(0, min(1s, 200ms*2^n))
before the nth retry, matching minio-go's DefaultRetryUnit/DefaultRetryCap.
The "RetryHead" S3 code is explicitly excluded so executeHeadAsync region
redirect logic is unaffected. maxRetries is configurable via builder and
setMaxRetries() post-construction.

Closes #1700.

Author: allanrogerr

api/src/main/java/io/minio/BaseS3Client.java

@@ -62,6 +62,9 @@
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionException;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.TimeUnit;
 import java.util.function.Supplier;
 import java.util.logging.Logger;
 import javax.annotation.Nonnull;
@@ -103,6 +106,15 @@ public abstract class BaseS3Client implements AutoCloseable {
   private static final String UPLOAD_ID = "uploadId";
   private static final Set<String> TRACE_QUERY_PARAMS =
       ImmutableSet.of("retention", "legal-hold", "tagging", UPLOAD_ID, "acl", "attributes");
+
+  private static final ScheduledExecutorService RETRY_SCHEDULER =
+      Executors.newSingleThreadScheduledExecutor(
+          r -> {
+            Thread t = new Thread(r, "minio-retry-scheduler");
+            t.setDaemon(true);
+            return t;
+          });
+
   private PrintWriter traceStream;
   protected final Map<String, String> regionCache = new ConcurrentHashMap<>();
   protected String userAgent = Utils.getDefaultUserAgent();
@@ -111,6 +123,7 @@ public abstract class BaseS3Client implements AutoCloseable {
   protected Provider provider;
   protected OkHttpClient httpClient;
   protected boolean closeHttpClient;
+  protected volatile int maxRetries = Retry.MAX_RETRY;
 
   protected BaseS3Client(
       Http.BaseUrl baseUrl, Provider provider, OkHttpClient httpClient, boolean closeHttpClient) {
@@ -125,6 +138,7 @@ protected BaseS3Client(BaseS3Client client) {
     this.provider = client.provider;
     this.httpClient = client.httpClient;
     this.closeHttpClient = client.closeHttpClient;
+    this.maxRetries = client.maxRetries;
   }
 
   /** Closes underneath HTTP client. */
@@ -136,6 +150,18 @@ public void close() {
     }
   }
 
+  /**
+   * Sets the maximum number of retry attempts for failed S3 requests. Requests with non-seekable
+   * bodies are never retried regardless of this value. The default is {@code Retry.MAX_RETRY} (10).
+   * Pass 1 to disable automatic retries.
+   *
+   * @param maxRetries maximum attempts (must be >= 1).
+   */
+  public void setMaxRetries(int maxRetries) {
+    if (maxRetries < 1) throw new IllegalArgumentException("maxRetries must be >= 1");
+    this.maxRetries = maxRetries;
+  }
+
   /**
    * Sets HTTP connect, write and read timeouts. A value of 0 means no timeout, otherwise values
    * must be between 1 and Integer.MAX_VALUE when converted to milliseconds.
@@ -270,8 +296,47 @@ private String[] handleRedirectResponse(
     return new String[] {code, message};
   }
 
-  /** Execute HTTP request asynchronously for given parameters. */
+  /** Execute HTTP request asynchronously for given parameters, with automatic retry. */
   protected CompletableFuture<Response> executeAsync(Http.S3Request s3request, String region) {
+    // Non-seekable bodies (raw okhttp3 RequestBody) cannot be replayed — single attempt only.
+    Http.Body body = s3request.body();
+    int maxAttempts = (body != null && body.isHttpRequestBody()) ? 1 : this.maxRetries;
+    return executeWithRetry(s3request, region, maxAttempts, 0);
+  }
+
+  private CompletableFuture<Response> executeWithRetry(
+      Http.S3Request s3request, String region, int maxAttempts, int attempt) {
+    return doExecuteAsync(s3request, region)
+        .handle(
+            (response, throwable) -> {
+              if (throwable == null) {
+                return CompletableFuture.completedFuture(response);
+              }
+              Throwable cause =
+                  (throwable instanceof CompletionException) ? throwable.getCause() : throwable;
+              if (cause == null) cause = throwable;
+              if (attempt + 1 >= maxAttempts || !Retry.isRetryable(cause)) {
+                return Utils.<Response>failedFuture(cause);
+              }
+              long delayMs = Retry.computeBackoffMs(attempt + 1, RANDOM);
+              CompletableFuture<Response> retryFuture = new CompletableFuture<>();
+              RETRY_SCHEDULER.schedule(
+                  () ->
+                      executeWithRetry(s3request, region, maxAttempts, attempt + 1)
+                          .whenComplete(
+                              (r, t) -> {
+                                if (t != null) retryFuture.completeExceptionally(t);
+                                else retryFuture.complete(r);
+                              }),
+                  delayMs,
+                  TimeUnit.MILLISECONDS);
+              return retryFuture;
+            })
+        .thenCompose(cf -> cf);
+  }
+
+  /** Execute single HTTP request attempt asynchronously for given parameters. */
+  private CompletableFuture<Response> doExecuteAsync(Http.S3Request s3request, String region) {
     Credentials credentials = (provider == null) ? null : provider.fetch();
     Http.Request request = null;
     try {
@@ -285,11 +350,6 @@ protected CompletableFuture<Response> executeAsync(Http.S3Request s3request, Str
     if (traceStream != null) traceStream.print(request.httpTraces());
 
     OkHttpClient httpClient = this.httpClient;
-    // FIXME: enable retry for all request.
-    // if (!s3request.retryFailure()) {
-    //   httpClient = httpClient.newBuilder().retryOnConnectionFailure(false).build();
-    // }
-
     okhttp3.Request httpRequest = request.httpRequest();
     CompletableFuture<Response> completableFuture = newCompleteableFuture();
     httpClient

api/src/main/java/io/minio/Http.java

@@ -1503,6 +1503,11 @@ public String object() {
       return object;
     }
 
+    /** Returns the request body, or {@code null} if none was set. */
+    public Body body() {
+      return body;
+    }
+
     private Request toRequest(
         BaseUrl baseUrl, String region, Credentials credentials, Integer expiry)
         throws MinioException {

api/src/main/java/io/minio/MinioAsyncClient.java

@@ -156,6 +156,7 @@ public static final class Builder {
     private Provider provider;
     private OkHttpClient httpClient;
     private boolean closeHttpClient;
+    private int maxRetries = Retry.MAX_RETRY;
 
     public Builder baseUrl(Http.BaseUrl baseUrl) {
       if (baseUrl.region() == null) {
@@ -217,6 +218,16 @@ public Builder httpClient(OkHttpClient httpClient, boolean close) {
       return this;
     }
 
+    /**
+     * Sets the maximum number of retry attempts per request. Pass 1 to disable automatic retries.
+     * Defaults to {@link Retry#MAX_RETRY} (10).
+     */
+    public Builder maxRetries(int maxRetries) {
+      if (maxRetries < 1) throw new IllegalArgumentException("maxRetries must be >= 1");
+      this.maxRetries = maxRetries;
+      return this;
+    }
+
     public MinioAsyncClient build() {
       Utils.validateNotNull(baseUrl, "endpoint");
 
@@ -232,7 +243,10 @@ public MinioAsyncClient build() {
         httpClient = Http.newDefaultClient();
       }
 
-      return new MinioAsyncClient(baseUrl, provider, httpClient, closeHttpClient);
+      MinioAsyncClient client =
+          new MinioAsyncClient(baseUrl, provider, httpClient, closeHttpClient);
+      client.maxRetries = maxRetries;
+      return client;
     }
   }
 

api/src/main/java/io/minio/MinioClient.java

@@ -1979,6 +1979,15 @@ public void setAwsS3Prefix(String awsS3Prefix) {
     asyncClient.setAwsS3Prefix(awsS3Prefix);
   }
 
+  /**
+   * Sets the maximum number of retry attempts. Pass 1 to disable automatic retries.
+   *
+   * @param maxRetries maximum attempts (must be >= 1).
+   */
+  public void setMaxRetries(int maxRetries) {
+    asyncClient.setMaxRetries(maxRetries);
+  }
+
   /** Closes underneath async client. */
   @Override
   public void close() throws Exception {
@@ -2043,6 +2052,15 @@ public Builder httpClient(OkHttpClient httpClient, boolean close) {
       return this;
     }
 
+    /**
+     * Sets the maximum number of retry attempts per request. Pass 1 to disable automatic retries.
+     * Defaults to {@link Retry#MAX_RETRY} (10).
+     */
+    public Builder maxRetries(int maxRetries) {
+      asyncClientBuilder.maxRetries(maxRetries);
+      return this;
+    }
+
     public MinioClient build() {
       MinioAsyncClient asyncClient = asyncClientBuilder.build();
       return new MinioClient(asyncClient);

api/src/main/java/io/minio/Retry.java

@@ -0,0 +1,152 @@
+/*
+ * MinIO Java SDK for Amazon S3 Compatible Cloud Storage, (C) 2026 MinIO, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.minio;
+
+import com.google.common.collect.ImmutableSet;
+import io.minio.errors.ErrorResponseException;
+import io.minio.errors.InvalidResponseException;
+import io.minio.errors.ServerException;
+import java.io.IOException;
+import java.util.Random;
+import java.util.Set;
+import java.util.concurrent.CompletionException;
+import javax.net.ssl.SSLHandshakeException;
+
+/** Retry configuration and helpers for S3 request execution. */
+class Retry {
+  /** Default maximum number of retry attempts per request. */
+  static final int MAX_RETRY = 10;
+
+  /** Base sleep unit for exponential backoff (milliseconds). */
+  static final long RETRY_BASE_MS = 200L;
+
+  /** Maximum sleep cap for exponential backoff (milliseconds). */
+  static final long RETRY_CAP_MS = 1_000L;
+
+  /**
+   * S3 error codes that should trigger a retry. Matches the retryableS3Codes set from minio-go
+   * retry.go.
+   */
+  private static final Set<String> RETRYABLE_S3_CODES =
+      ImmutableSet.of(
+          "RequestError",
+          "RequestTimeout",
+          "Throttling",
+          "ThrottlingException",
+          "RequestLimitExceeded",
+          "RequestThrottled",
+          "InternalError",
+          "ExpiredToken",
+          "ExpiredTokenException",
+          "SlowDown",
+          "SlowDownWrite",
+          "SlowDownRead");
+
+  /**
+   * HTTP status codes that should trigger a retry. Matches retryableHTTPStatusCodes from minio-go
+   * retry.go.
+   */
+  private static final Set<Integer> RETRYABLE_HTTP_CODES =
+      ImmutableSet.of(
+          408, // Request Timeout
+          429, // Too Many Requests
+          499, // Client Closed Request (nginx)
+          500, // Internal Server Error
+          502, // Bad Gateway
+          503, // Service Unavailable
+          504, // Gateway Timeout
+          520 // Cloudflare unknown error
+          );
+
+  static boolean isRetryableS3Code(String code) {
+    return code != null && RETRYABLE_S3_CODES.contains(code);
+  }
+
+  static boolean isRetryableHttpCode(int code) {
+    return RETRYABLE_HTTP_CODES.contains(code);
+  }
+
+  /**
+   * Returns true if the IOException is retryable. Non-retryable: TLS handshake failures, HTTP/HTTPS
+   * protocol mismatch. Everything else (connection reset, EOF, server closed idle connection) is
+   * retried.
+   */
+  static boolean isRetryableIOException(IOException e) {
+    // TLS certificate / handshake failures are not retryable.
+    if (e instanceof SSLHandshakeException) return false;
+    String msg = e.getMessage();
+    // Protocol mismatch is not retryable.
+    if (msg != null && msg.contains("server gave HTTP response to HTTPS client")) return false;
+    return true;
+  }
+
+  /**
+   * Returns true if the throwable represents a retryable failure. Handles IOException,
+   * ErrorResponseException, ServerException, and InvalidResponseException.
+   */
+  static boolean isRetryable(Throwable t) {
+    if (t instanceof CompletionException) t = t.getCause();
+    if (t == null) return false;
+
+    if (t instanceof IOException) {
+      return isRetryableIOException((IOException) t);
+    }
+
+    if (t instanceof ErrorResponseException) {
+      ErrorResponseException e = (ErrorResponseException) t;
+      String code = e.errorResponse().code();
+      // "RetryHead" is handled separately by executeHeadAsync — must not be swallowed here.
+      if ("RetryHead".equals(code)) return false;
+      if (isRetryableS3Code(code)) return true;
+      if (e.response() != null && isRetryableHttpCode(e.response().code())) return true;
+      return false;
+    }
+
+    if (t instanceof ServerException) {
+      return isRetryableHttpCode(((ServerException) t).statusCode());
+    }
+
+    if (t instanceof InvalidResponseException) {
+      return isRetryableHttpCode(((InvalidResponseException) t).responseCode());
+    }
+
+    return false;
+  }
+
+  /**
+   * Computes the full-jitter exponential backoff delay for retry {@code attempt} (1-indexed: 1 =
+   * first retry). Matches minio-go's {@code exponentialBackoffWait(i)}:
+   *
+   * <pre>
+   * attempt=1 → [0, 200 ms]
+   * attempt=2 → [0, 400 ms]
+   * attempt=3 → [0, 800 ms]
+   * attempt=4+→ [0, 1000 ms] (capped)
+   * </pre>
+   *
+   * Pass {@code attempt <= 0} to get 0 (no delay).
+   */
+  static long computeBackoffMs(int attempt, Random random) {
+    if (attempt <= 0) return 0L;
+    // exp = attempt-1 so that attempt=1 maps to base*2^0=200ms cap
+    int exp = Math.min(attempt - 1, 30);
+    long cap = Math.min(RETRY_CAP_MS, RETRY_BASE_MS * (1L << exp));
+    return (long) (random.nextDouble() * cap);
+  }
+
+  private Retry() {}
+}

api/src/main/java/io/minio/errors/InvalidResponseException.java

@@ -20,6 +20,8 @@
 public class InvalidResponseException extends MinioException {
   private static final long serialVersionUID = -4793742105569629274L;
 
+  private final int responseCode;
+
   public InvalidResponseException(
       int responseCode, String contentType, String body, String httpTrace) {
     super(
@@ -30,5 +32,11 @@ public InvalidResponseException(
             + ", body: "
             + body,
         httpTrace);
+    this.responseCode = responseCode;
+  }
+
+  /** Returns the HTTP response code that triggered this exception. */
+  public int responseCode() {
+    return responseCode;
   }
 }