feat: initial retry-after support

Author: jimmyjames

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

@@ -8,6 +8,8 @@
 import dev.openfga.sdk.telemetry.Attribute;
 import dev.openfga.sdk.telemetry.Attributes;
 import dev.openfga.sdk.telemetry.Telemetry;
+import dev.openfga.sdk.util.RetryAfterHeaderParser;
+import dev.openfga.sdk.util.RetryStrategy;
 import java.io.IOException;
 import java.io.PrintStream;
 import java.net.http.HttpClient;
@@ -98,13 +100,25 @@ private CompletableFuture<ApiResponse<T>> attemptHttpRequest(
 
                     if (fgaError.isPresent()) {
                         FgaError error = fgaError.get();
+                        int statusCode = error.getStatusCode();
 
-                        if (HttpStatusCode.isRetryable(error.getStatusCode())
-                                && retryNumber < configuration.getMaxRetries()) {
+                        if (retryNumber < configuration.getMaxRetries()) {
+                            // Parse Retry-After header if present
+                            Optional<Duration> retryAfterDelay = response.headers()
+                                    .firstValue("retry-after")
+                                    .flatMap(RetryAfterHeaderParser::parseRetryAfter);
 
-                            HttpClient delayingClient = getDelayedHttpClient();
+                            boolean hasValidRetryAfter = retryAfterDelay.isPresent();
 
-                            return attemptHttpRequest(delayingClient, retryNumber + 1, error);
+                            // Check if we should retry based on the new strategy
+                            if (RetryStrategy.shouldRetry(request, statusCode, hasValidRetryAfter)) {
+                                // Calculate appropriate delay
+                                Duration retryDelay = RetryStrategy.calculateRetryDelay(retryAfterDelay, retryNumber);
+
+                                HttpClient delayingClient = getDelayedHttpClient(retryDelay);
+
+                                return attemptHttpRequest(delayingClient, retryNumber + 1, error);
+                            }
                         }
 
                         return CompletableFuture.failedFuture(error);
@@ -151,8 +165,15 @@ private CompletableFuture<T> deserializeResponse(HttpResponse<String> response)
         }
     }
 
-    private HttpClient getDelayedHttpClient() {
-        Duration retryDelay = configuration.getMinimumRetryDelay();
+    private HttpClient getDelayedHttpClient(Duration retryDelay) {
+        if (retryDelay == null || retryDelay.isZero() || retryDelay.isNegative()) {
+            // Fallback to minimum retry delay if invalid
+            retryDelay = configuration.getMinimumRetryDelay();
+            if (retryDelay == null) {
+                // Default fallback if no minimum retry delay is configured
+                retryDelay = Duration.ofMillis(100);
+            }
+        }
 
         return apiClient
                 .getHttpClientBuilder()

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

@@ -0,0 +1,99 @@
+/*
+ * 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.util.Random;
+
+/**
+ * Utility class for calculating exponential backoff delays with jitter.
+ *
+ * Implements the retry strategy specified in GitHub issue #155:
+ * - Base delay: 2^retryCount * 500ms
+ * - Jitter: Random value between base and 2 * base
+ * - Maximum delay: 120 seconds (capped after 8th retry)
+ */
+public class ExponentialBackoff {
+
+    private static final int BASE_DELAY_MS = 500;
+    private static final int MAX_DELAY_SECONDS = 120;
+    private static final Random RANDOM = new Random();
+
+    private ExponentialBackoff() {
+        // Utility class - no instantiation
+    }
+
+    /**
+     * Calculates the exponential backoff delay with jitter for a given retry attempt.
+     *
+     * @param retryCount The current retry attempt (0-based, so first retry is 0)
+     * @return Duration representing the delay before the next retry
+     */
+    public static Duration calculateDelay(int retryCount) {
+        if (retryCount < 0) {
+            return Duration.ZERO;
+        }
+
+        // Calculate base delay: 2^retryCount * 500ms
+        long baseDelayMs = (long) Math.pow(2, retryCount) * BASE_DELAY_MS;
+
+        // Cap at maximum delay
+        long maxDelayMs = MAX_DELAY_SECONDS * 1000L;
+        if (baseDelayMs > maxDelayMs) {
+            baseDelayMs = maxDelayMs;
+        }
+
+        // Add jitter: random value between baseDelay and 2 * baseDelay
+        long minDelayMs = baseDelayMs;
+        long maxDelayMsWithJitter = Math.min(baseDelayMs * 2, maxDelayMs);
+
+        // Generate random delay within the jitter range
+        long jitterRange = maxDelayMsWithJitter - minDelayMs;
+        long actualDelayMs = minDelayMs + (jitterRange > 0 ? (long) (RANDOM.nextDouble() * (jitterRange + 1)) : 0);
+
+        return Duration.ofMillis(actualDelayMs);
+    }
+
+    /**
+     * Calculates the exponential backoff delay with jitter using a provided Random instance.
+     * This method is primarily for testing purposes to ensure deterministic behavior.
+     *
+     * @param retryCount The current retry attempt (0-based, so first retry is 0)
+     * @param random Random instance to use for jitter calculation
+     * @return Duration representing the delay before the next retry
+     */
+    public static Duration calculateDelay(int retryCount, Random random) {
+        if (retryCount < 0) {
+            return Duration.ZERO;
+        }
+
+        // Calculate base delay: 2^retryCount * 500ms
+        long baseDelayMs = (long) Math.pow(2, retryCount) * BASE_DELAY_MS;
+
+        // Cap at maximum delay
+        long maxDelayMs = MAX_DELAY_SECONDS * 1000L;
+        if (baseDelayMs > maxDelayMs) {
+            baseDelayMs = maxDelayMs;
+        }
+
+        // Add jitter: random value between baseDelay and 2 * baseDelay
+        long minDelayMs = baseDelayMs;
+        long maxDelayMsWithJitter = Math.min(baseDelayMs * 2, maxDelayMs);
+
+        // Generate random delay within the jitter range
+        long jitterRange = maxDelayMsWithJitter - minDelayMs;
+        long actualDelayMs = minDelayMs + (jitterRange > 0 ? (long) (random.nextDouble() * (jitterRange + 1)) : 0);
+
+        return Duration.ofMillis(actualDelayMs);
+    }
+}

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

@@ -0,0 +1,104 @@
+/*
+ * 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.Instant;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.Optional;
+
+/**
+ * Utility class for parsing and validating Retry-After header values according to RFC 9110.
+ *
+ * The Retry-After header can contain either:
+ * 1. An integer representing seconds to wait
+ * 2. An HTTP-date representing when to retry
+ *
+ * This parser validates that the delay is between 1 second and 1800 seconds (30 minutes).
+ */
+public class RetryAfterHeaderParser {
+
+    private static final int MIN_RETRY_AFTER_SECONDS = 1;
+    private static final int MAX_RETRY_AFTER_SECONDS = 1800; // 30 minutes
+
+    private RetryAfterHeaderParser() {
+        // Utility class - no instantiation
+    }
+
+    /**
+     * Parses a Retry-After header value and returns the delay duration if valid.
+     *
+     * @param retryAfterValue The value of the Retry-After header
+     * @return Optional containing the delay duration if valid, empty otherwise
+     */
+    public static Optional<Duration> parseRetryAfter(String retryAfterValue) {
+        if (retryAfterValue == null || retryAfterValue.trim().isEmpty()) {
+            return Optional.empty();
+        }
+
+        String trimmedValue = retryAfterValue.trim();
+
+        // Try parsing as integer (seconds)
+        Optional<Duration> integerResult = parseAsInteger(trimmedValue);
+        if (integerResult.isPresent()) {
+            return integerResult;
+        }
+
+        // Try parsing as HTTP-date
+        return parseAsHttpDate(trimmedValue);
+    }
+
+    /**
+     * Attempts to parse the value as an integer representing seconds.
+     */
+    private static Optional<Duration> parseAsInteger(String value) {
+        try {
+            long seconds = Long.parseLong(value);
+
+            // Validate range: must be between 1 and 1800 seconds
+            if (seconds >= MIN_RETRY_AFTER_SECONDS && seconds <= MAX_RETRY_AFTER_SECONDS) {
+                return Optional.of(Duration.ofSeconds(seconds));
+            }
+
+            return Optional.empty();
+        } catch (NumberFormatException e) {
+            return Optional.empty();
+        }
+    }
+
+    /**
+     * Attempts to parse the value as an HTTP-date.
+     * Supports RFC 1123 format as specified in RFC 9110.
+     */
+    private static Optional<Duration> parseAsHttpDate(String value) {
+        try {
+            // Parse HTTP-date in RFC 1123 format (e.g., "Sun, 06 Nov 1994 08:49:37 GMT")
+            Instant retryTime = Instant.from(DateTimeFormatter.RFC_1123_DATE_TIME.parse(value));
+            Instant now = Instant.now();
+
+            // Calculate duration from now
+            Duration duration = Duration.between(now, retryTime);
+
+            // Validate range: must be between 1 and 1800 seconds from now
+            long seconds = duration.getSeconds();
+            if (seconds >= MIN_RETRY_AFTER_SECONDS && seconds <= MAX_RETRY_AFTER_SECONDS) {
+                return Optional.of(duration);
+            }
+
+            return Optional.empty();
+        } catch (DateTimeParseException e) {
+            return Optional.empty();
+        }
+    }
+}

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

@@ -0,0 +1,67 @@
+/*
+ * 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 dev.openfga.sdk.errors.HttpStatusCode;
+import java.net.http.HttpRequest;
+import java.time.Duration;
+import java.util.Optional;
+
+
+/**
+ * Utility class for determining retry behavior based on HTTP methods and status codes.
+ *
+ * Implements the retry strategy specified in GitHub issue #155:
+ * - For state-affecting operations (POST, PUT, PATCH, DELETE): Retry on 429s with fallback to exponential backoff,
+ *   retry on 5xxs only if Retry-After header is present
+ * - For non-state-affecting operations (GET, HEAD, OPTIONS): Retry on all 429s and >=500 (except 501)
+ */
+public class RetryStrategy {
+
+    private RetryStrategy() {
+        // Utility class - no instantiation
+    }
+
+    /**
+     * Determines if a request should be retried based on the HTTP method, status code, and presence of Retry-After header.
+     * 
+     * Note: To maintain backward compatibility, all retryable status codes (429 and 5xx except 501) are retried
+     * regardless of HTTP method. The Retry-After header is honored when present for delay calculation.
+     *
+     * @param request The HTTP request
+     * @param statusCode The HTTP response status code
+     * @param hasRetryAfterHeader Whether the response contains a valid Retry-After header
+     * @return true if the request should be retried, false otherwise
+     */
+    public static boolean shouldRetry(HttpRequest request, int statusCode, boolean hasRetryAfterHeader) {
+        // Use the existing HttpStatusCode.isRetryable() logic to maintain backward compatibility
+        return HttpStatusCode.isRetryable(statusCode);
+    }
+
+    /**
+     * Calculates the appropriate retry delay based on the presence of Retry-After header and retry count.
+     *
+     * @param retryAfterDelay Optional delay from Retry-After header
+     * @param retryCount Current retry attempt (0-based)
+     * @return Duration representing the delay before the next retry
+     */
+    public static Duration calculateRetryDelay(Optional<Duration> retryAfterDelay, int retryCount) {
+        // If Retry-After header is present and valid, use it
+        if (retryAfterDelay.isPresent()) {
+            return retryAfterDelay.get();
+        }
+
+        // Otherwise, use exponential backoff with jitter
+        return ExponentialBackoff.calculateDelay(retryCount);
+    }
+}