docs(retry): clarify RetryInterceptor as supported API; add terminal-status assertions

Address Copilot review feedback (PR #1701, review 4246873092):

- RetryInterceptor Javadoc now declares it as part of the SDK's supported
  public API and documents how BaseS3Client wraps every supplied
  OkHttpClient. Drops {@link} references to package-private Retry helpers
  so the public Javadoc no longer points at internal symbols. Adds a
  Threading note about Thread.sleep blocking the OkHttp dispatcher slot
  during backoff and points high-concurrency callers at Dispatcher
  pool sizing.
- BaseS3Client.executeAsync Javadoc reworded to reflect the wrapWithRetry
  behaviour (interceptor installed on every supplied client, default or
  caller-provided) and to note the maxRetries supplier is read per request.
- RetryTest: strengthen testRetryExhaustedReturnsLastResponse to assert
  the InvalidResponseException reflects HTTP 500 rather than allowing any
  exception type to pass. Add testRetryExhaustedSurfacesXmlErrorResponse
  for the XML/ErrorResponseException path, asserting both response.code()
  and the parsed S3 code after retries are exhausted.

Validated locally on Java 17:
- :api:check (compile + spotless + spotbugs + tests) PASS
- :api:javadoc PASS

Author: allanrogerr

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

@@ -297,8 +297,11 @@ private String[] handleRedirectResponse(
   }
 
   /**
-   * Execute HTTP request asynchronously for given parameters. Retries on retryable HTTP status
-   * codes are handled by {@link Http.RetryInterceptor} installed on the default HTTP client.
+   * Execute HTTP request asynchronously for given parameters. Retries on retryable IOException,
+   * HTTP status, and S3 error code are handled by {@link Http.RetryInterceptor}, which {@link
+   * #wrapWithRetry} installs on the underlying {@link OkHttpClient} regardless of whether the
+   * client is the default or caller-supplied. The attempt budget is read from {@link #maxRetries}
+   * on every request.
    */
   protected CompletableFuture<Response> executeAsync(Http.S3Request s3request, String region) {
     Credentials credentials = (provider == null) ? null : provider.fetch();

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

@@ -692,24 +692,32 @@ public static OkHttpClient setTimeout(
   /**
    * OkHttp interceptor that retries transient HTTP failures with full-jitter exponential backoff.
    *
+   * <p>This is part of the SDK's supported public API: it is installed automatically by {@link
+   * BaseS3Client} on every supplied {@link OkHttpClient} (default or caller-provided), and may also
+   * be registered explicitly on a stand-alone {@link OkHttpClient} via {@code .addInterceptor(new
+   * Http.RetryInterceptor())}.
+   *
    * <p>Retries on:
    *
    * <ul>
-   *   <li>retryable IOException ({@link Retry#isRequestErrorRetryable}) — connection reset, EOF,
-   *       socket timeout, idle-connection close. Excludes TLS handshake / unknown-CA / HTTPS
-   *       protocol mismatch.
-   *   <li>retryable HTTP status code ({@link Retry#RETRYABLE_HTTP_STATUS_CODES}) — 408, 429, 499,
-   *       500, 502, 503, 504, 520.
-   *   <li>retryable S3 error code in a non-2xx response body ({@link Retry#RETRYABLE_S3_CODES}) —
-   *       {@code SlowDown}, {@code InternalError}, {@code ExpiredToken}, etc.
+   *   <li>retryable IOException — connection reset, EOF, socket timeout, idle-connection close.
+   *       Excludes TLS handshake / unknown-CA / HTTPS protocol mismatch.
+   *   <li>retryable HTTP status code — 408, 429, 499, 500, 502, 503, 504, 520.
+   *   <li>retryable S3 error code in a non-2xx response body — {@code SlowDown}, {@code
+   *       InternalError}, {@code ExpiredToken}, etc.
    * </ul>
    *
-   * <p>Backoff is computed by {@link Retry#exponentialBackoffMs}. The maximum number of attempts is
-   * supplied per intercept call via {@link IntSupplier} so that an SDK client can expose runtime
-   * tuning while keeping the interceptor itself stateless. The no-arg constructor uses the default
-   * {@link Retry#MAX_RETRY}.
+   * <p>Backoff is full-jitter exponential, with a 200&nbsp;ms unit and a 1&nbsp;s per-attempt cap.
+   * The maximum number of attempts is supplied per intercept call via {@link IntSupplier} so that
+   * an SDK client can expose runtime tuning while keeping the interceptor itself stateless. The
+   * no-arg constructor uses the package default of 10 attempts.
+   *
+   * <p><b>Threading.</b> Backoff sleeps on the OkHttp dispatcher thread that owns the call. Under
+   * sustained 5xx/429 storms this can hold dispatcher slots idle while waiting. Callers that need
+   * higher concurrency under widespread retry should size the dispatcher worker pool accordingly
+   * (see {@link okhttp3.Dispatcher#setMaxRequests} / {@code setMaxRequestsPerHost}).
    *
-   * <p>To opt out of retries on a custom {@link OkHttpClient}, simply do not register this
+   * <p>To opt out of retries on a stand-alone {@link OkHttpClient}, simply do not register this
    * interceptor.
    */
   public static class RetryInterceptor implements Interceptor {

api/src/test/java/io/minio/RetryTest.java

@@ -306,7 +306,35 @@ public void testRetryExhaustedReturnsLastResponse() throws IOException, MinioExc
         client.listBuckets();
         Assert.fail("expected exception after exhausted retries");
       } catch (InvalidResponseException e) {
-        // expected — non-XML 500
+        // Terminal exception must surface the underlying 500 status so callers can distinguish
+        // exhausted retries from unrelated failures (e.g. NPE, parser bugs).
+        Assert.assertTrue(
+            "exhausted-retries exception must reflect HTTP 500, got: " + e.getMessage(),
+            e.getMessage().contains("Response code: 500"));
+      }
+      Assert.assertEquals(3, server.getRequestCount());
+    }
+  }
+
+  @Test
+  public void testRetryExhaustedSurfacesXmlErrorResponse() throws IOException, MinioException {
+    // 3 attempts, all 503 with XML <Error><Code>InternalError</Code> — confirms the terminal
+    // ErrorResponseException carries both the 503 status and the parsed S3 code after the retry
+    // loop gives up.
+    try (MockWebServer server = new MockWebServer()) {
+      server.enqueue(xmlError(503, "InternalError"));
+      server.enqueue(xmlError(503, "InternalError"));
+      server.enqueue(xmlError(503, "InternalError"));
+      server.start();
+
+      MinioClient client =
+          MinioClient.builder().endpoint(server.url("").toString()).maxRetries(3).build();
+      try {
+        client.listBuckets();
+        Assert.fail("expected ErrorResponseException after exhausted retries");
+      } catch (ErrorResponseException e) {
+        Assert.assertEquals(503, e.response().code());
+        Assert.assertEquals("InternalError", e.errorResponse().code());
       }
       Assert.assertEquals(3, server.getRequestCount());
     }