feat: improve retry strategy

Author: aaguiarz

README.md

@@ -965,9 +965,11 @@ fgaClient.writeAssertions(assertions, options).get();
 
 ### Retries
 
-If a network request fails with a 429 or 5xx error from the server, the SDK will automatically retry the request up to 3 times with a minimum wait time of 100 milliseconds between each attempt.
+If a network request fails with a 429 or 5xx error from the server, the SDK will automatically retry the request up to 3 times.
+When the response includes a `Retry-After` header, the delay specified by the header will be used (up to 30 minutes).
+Otherwise the wait time follows an exponential backoff with jitter starting at 100 milliseconds and capped at 120 seconds.
 
-To customize this behavior, call `maxRetries` and `minimumRetryDelay` on the `ClientConfiguration` builder. `maxRetries` determines the maximum number of retries (up to 15), while `minimumRetryDelay` sets the minimum wait time between retries in milliseconds.
+To customize this behavior, call `maxRetries` and `minimumRetryDelay` on the `ClientConfiguration` builder. `maxRetries` determines the maximum number of retries (up to 15), while `minimumRetryDelay` sets the base delay used to calculate the exponential backoff.
 
 ```java
 import com.fasterxml.jackson.databind.ObjectMapper;

src/main/java/dev/openfga/sdk/api/client/HttpRequestAttempt.java

@@ -8,6 +8,7 @@
 import dev.openfga.sdk.telemetry.Attribute;
 import dev.openfga.sdk.telemetry.Attributes;
 import dev.openfga.sdk.telemetry.Telemetry;
+import dev.openfga.sdk.util.Retry;
 import java.io.IOException;
 import java.io.PrintStream;
 import java.net.http.HttpClient;
@@ -102,7 +103,8 @@ private CompletableFuture<ApiResponse<T>> attemptHttpRequest(
                         if (HttpStatusCode.isRetryable(error.getStatusCode())
                                 && retryNumber < configuration.getMaxRetries()) {
 
-                            HttpClient delayingClient = getDelayedHttpClient();
+                            Duration retryDelay = computeRetryDelay(response, retryNumber);
+                            HttpClient delayingClient = getDelayedHttpClient(retryDelay);
 
                             return attemptHttpRequest(delayingClient, retryNumber + 1, error);
                         }
@@ -151,15 +153,30 @@ private CompletableFuture<T> deserializeResponse(HttpResponse<String> response)
         }
     }
 
-    private HttpClient getDelayedHttpClient() {
-        Duration retryDelay = configuration.getMinimumRetryDelay();
-
+    private HttpClient getDelayedHttpClient(Duration retryDelay) {
         return apiClient
                 .getHttpClientBuilder()
                 .executor(CompletableFuture.delayedExecutor(retryDelay.toNanos(), TimeUnit.NANOSECONDS))
                 .build();
     }
 
+    private Duration computeRetryDelay(HttpResponse<String> response, int retryNumber) {
+        Duration retryAfter = response.headers()
+                .firstValue("Retry-After")
+                .map(Retry::parseRetryAfter)
+                .orElse(null);
+
+        if (retryAfter != null) {
+            return retryAfter;
+        }
+
+        Duration baseDelay = configuration.getMinimumRetryDelay();
+        if (baseDelay == null) {
+            baseDelay = Duration.ofMillis(100);
+        }
+        return Retry.computeExponentialDelay(baseDelay, retryNumber);
+    }
+
     private static class BodyLogger implements Flow.Subscriber<ByteBuffer> {
         private final PrintStream out;
         private final String target;

src/main/java/dev/openfga/sdk/errors/FgaError.java

@@ -4,6 +4,7 @@
 
 import dev.openfga.sdk.api.configuration.Configuration;
 import dev.openfga.sdk.api.configuration.CredentialsMethod;
+import dev.openfga.sdk.util.Retry;
 import java.net.http.HttpHeaders;
 import java.net.http.HttpRequest;
 import java.net.http.HttpResponse;
@@ -17,6 +18,7 @@ public class FgaError extends ApiException {
     private String grantType = null;
     private String requestId = null;
     private String apiErrorCode = null;
+    private Long retryAfterSeconds = null;
 
     public FgaError(String message, Throwable cause, int code, HttpHeaders responseHeaders, String responseBody) {
         super(message, cause, code, responseHeaders, responseBody);
@@ -57,6 +59,10 @@ public static Optional<FgaError> getError(
             error = new FgaError(name, previousError, status, headers, body);
         }
 
+        headers.firstValue("Retry-After")
+                .flatMap(value -> Optional.ofNullable(Retry.parseRetryAfterSeconds(value)))
+                .ifPresent(error::setRetryAfterSeconds);
+
         error.setMethod(request.method());
         error.setRequestUrl(configuration.getApiUrl());
 
@@ -126,4 +132,12 @@ public void setApiErrorCode(String apiErrorCode) {
     public String getApiErrorCode() {
         return apiErrorCode;
     }
+
+    public void setRetryAfterSeconds(Long retryAfterSeconds) {
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+
+    public Long getRetryAfterSeconds() {
+        return retryAfterSeconds;
+    }
 }

src/main/java/dev/openfga/sdk/util/Retry.java

@@ -0,0 +1,86 @@
+/*
+ * OpenFGA
+ * A high performance and flexible authorization/permission engine built for developers and inspired by Google Zanzibar.
+ *
+ * The version of the OpenAPI document: 1.x
+ * Contact: community@openfga.dev
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+package dev.openfga.sdk.util;
+
+import java.time.Duration;
+import java.time.OffsetDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.concurrent.ThreadLocalRandom;
+
+/**
+ * Helper methods for retry strategies.
+ */
+public class Retry {
+    private Retry() {}
+
+    /**
+     * Parse the Retry-After header value to a Duration in seconds.
+     * Returns null if the value is invalid or outside the allowed range (1s-30min).
+     */
+    public static Duration parseRetryAfter(String headerValue) {
+        if (StringUtil.isNullOrWhitespace(headerValue)) {
+            return null;
+        }
+
+        String value = headerValue.trim();
+        // Try integer seconds first
+        try {
+            long secs = Long.parseLong(value);
+            if (secs < 1 || secs > 1800) {
+                return null;
+            }
+            return Duration.ofSeconds(secs);
+        } catch (NumberFormatException ex) {
+            // try HTTP date
+            try {
+                OffsetDateTime date = OffsetDateTime.parse(value, DateTimeFormatter.RFC_1123_DATE_TIME);
+                long secs = Duration.between(OffsetDateTime.now(), date).getSeconds();
+                if (secs < 1 || secs > 1800) {
+                    return null;
+                }
+                return Duration.ofSeconds(secs);
+            } catch (DateTimeParseException e) {
+                return null;
+            }
+        }
+    }
+
+    /**
+     * Parse Retry-After header value returning seconds as Long. Returns null when invalid.
+     */
+    public static Long parseRetryAfterSeconds(String headerValue) {
+        Duration d = parseRetryAfter(headerValue);
+        return d != null ? d.getSeconds() : null;
+    }
+
+    /**
+     * Compute an exponential backoff with jitter based on the retry number.
+     * The result is capped at 120 seconds.
+     */
+    public static Duration computeExponentialDelay(Duration baseDelay, int retryNumber) {
+        long baseMillis = baseDelay.toMillis();
+        long minMillis = (long) Math.pow(2, retryNumber) * baseMillis;
+        long maxMillis = (long) Math.pow(2, retryNumber + 1) * baseMillis;
+        long cap = 120_000L; // 120 seconds
+        minMillis = Math.min(minMillis, cap);
+        maxMillis = Math.min(maxMillis, cap);
+        long delay;
+        if (minMillis == maxMillis) {
+            delay = minMillis;
+        } else {
+            delay = ThreadLocalRandom.current().nextLong(minMillis, maxMillis + 1);
+        }
+        return Duration.ofMillis(delay);
+    }
+}