From ba3e013cfb75560343b8ffb47b488485cd4c8f79 Mon Sep 17 00:00:00 2001 From: openfga-releaser-bot Date: Tue, 28 Jul 2026 11:55:28 +0000 Subject: [PATCH] chore(sync): sync with generator Generated from openfga/sdk-generator@3bcfe054e5adfca0dfc9e839db222d18507723b4 --- README.md | 141 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 72 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index ae027fe8..3ccf9301 100644 --- a/README.md +++ b/README.md @@ -46,8 +46,8 @@ This is an autogenerated Java SDK for OpenFGA. It provides a wrapper around the - [Assertions](#assertions) - [Read Assertions](#read-assertions) - [Write Assertions](#write-assertions) - - [Retries](#retries) - [Calling Other Endpoints](#calling-other-endpoints) + - [Retries](#retries) - [API Endpoints](#api-endpoints) - [Models](#models) - [OpenTelemetry](#opentelemetry) @@ -1114,74 +1114,6 @@ fgaClient.writeAssertions(assertions, options).get(); ``` -### Retries - -The SDK implements RFC 9110 compliant retry behavior with support for the `Retry-After` header. By default, the SDK will automatically retry failed requests up to **3 times** with delay calculation (maximum allowable: 15 retries). - -#### Retry Behavior - -**Rate Limiting (429 errors):** Always retried regardless of HTTP method. - -**Server Errors (5xx):** All requests are retried on 5xx errors (except 501 Not Implemented) regardless of HTTP method: -- **All operations** (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS): Always retried on 5xx errors with delay calculation - -#### Delay Calculation - -1. **Retry-After header present**: Uses the server-specified delay (supports both integer seconds and HTTP-date formats) -2. **No Retry-After header**: Uses exponential backoff with jitter (base delay: 2^retryCount * 100ms, capped at 120 seconds) -3. **Minimum delay**: Respects the configured `minimumRetryDelay` as a floor value - -#### Configuration - -Customize retry behavior using the `ClientConfiguration` builder. The SDK enforces a maximum of 15 retries to prevent accidental server overload: - -**⚠️ Breaking Changes:** -- Configuration validation now prevents setting `maxRetries` above 15 -- `FgaError` now exposes the `Retry-After` header value via `getRetryAfterHeader()` - -```java -import com.fasterxml.jackson.databind.ObjectMapper; -import dev.openfga.sdk.api.client.OpenFgaClient; -import dev.openfga.sdk.api.configuration.ClientConfiguration; -import java.net.http.HttpClient; - -public class Example { - public static void main(String[] args) throws Exception { - var config = new ClientConfiguration() - .apiUrl(System.getenv("FGA_API_URL")) // If not specified, will default to "http://localhost:8080" - .storeId(System.getenv("FGA_STORE_ID")) // Not required when calling createStore() or listStores() - .authorizationModelId(System.getenv("FGA_MODEL_ID")) // Optional, can be overridden per request - .maxRetries(3) // retry up to 3 times on API requests (default: 3, maximum: 15) - .minimumRetryDelay(Duration.ofMillis(100)); // minimum wait time between retries in milliseconds (default: 100ms) - - var fgaClient = new OpenFgaClient(config); - var response = fgaClient.readAuthorizationModels().get(); - } -} -``` - -#### Error Handling with Retry Information - -When handling errors, you can access the `Retry-After` header value for debugging or custom retry logic: - -```java -try { - var response = fgaClient.check(request).get(); -} catch (ExecutionException e) { - if (e.getCause() instanceof FgaError) { - FgaError error = (FgaError) e.getCause(); - - // Access Retry-After header if present - String retryAfter = error.getRetryAfterHeader(); - if (retryAfter != null) { - System.out.println("Server requested retry after: " + retryAfter + " seconds"); - } - - System.out.println("Error: " + error.getMessage()); - } -} -``` - ### Calling Other Endpoints The API Executor provides direct HTTP access to OpenFGA endpoints not yet wrapped by the SDK. It maintains the SDK's client configuration including authentication, telemetry, retries, and error handling. @@ -1288,6 +1220,77 @@ For a complete working example, see [examples/api-executor](examples/api-executo See [docs/ApiExecutor.md](docs/ApiExecutor.md) for complete API reference and examples for both `ApiExecutor` and `StreamingApiExecutor`. + +### Retries + +The SDK implements RFC 9110 compliant retry behavior with support for the `Retry-After` header. By default, the SDK will automatically retry failed requests up to **3 times** with delay calculation (maximum allowable: 15 retries). + +#### Retry Behavior + +**Rate Limiting (429 errors):** Always retried regardless of HTTP method. + +**Server Errors (5xx):** All requests are retried on 5xx errors (except 501 Not Implemented) regardless of HTTP method: +- **All operations** (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS): Always retried on 5xx errors with delay calculation + +#### Delay Calculation + +1. **Retry-After header present**: Uses the server-specified delay (supports both integer seconds and HTTP-date formats) +2. **No Retry-After header**: Uses exponential backoff with jitter (base delay: 2^retryCount * 100ms, capped at 120 seconds) +3. **Minimum delay**: Respects the configured `minimumRetryDelay` as a floor value + +#### Configuration + +Customize retry behavior using the `ClientConfiguration` builder. The SDK enforces a maximum of 15 retries to prevent accidental server overload: + +**⚠️ Breaking Changes:** +- Configuration validation now prevents setting `maxRetries` above 15 +- `FgaError` now exposes the `Retry-After` header value via `getRetryAfterHeader()` + +```java +import com.fasterxml.jackson.databind.ObjectMapper; +import dev.openfga.sdk.api.client.OpenFgaClient; +import dev.openfga.sdk.api.configuration.ClientConfiguration; +import java.net.http.HttpClient; + +public class Example { + public static void main(String[] args) throws Exception { + var config = new ClientConfiguration() + .apiUrl(System.getenv("FGA_API_URL")) // If not specified, will default to "http://localhost:8080" + .storeId(System.getenv("FGA_STORE_ID")) // Not required when calling createStore() or listStores() + .authorizationModelId(System.getenv("FGA_MODEL_ID")) // Optional, can be overridden per request + .maxRetries(3) // retry up to 3 times on API requests (default: 3, maximum: 15) + .minimumRetryDelay(Duration.ofMillis(100)); // minimum wait time between retries in milliseconds (default: 100ms) + + var fgaClient = new OpenFgaClient(config); + var response = fgaClient.readAuthorizationModels().get(); + } +} +``` + +#### Error Handling with Retry Information + +When handling errors, you can access the `Retry-After` header value for debugging or custom retry logic: + +```java +try { + var response = fgaClient.check(request).get(); +} catch (ExecutionException e) { + if (e.getCause() instanceof FgaError) { + FgaError error = (FgaError) e.getCause(); + + // Access Retry-After header if present + String retryAfter = error.getRetryAfterHeader(); + if (retryAfter != null) { + System.out.println("Server requested retry after: " + retryAfter + " seconds"); + } + + System.out.println("Error: " + error.getMessage()); + } +} +``` + + + ### API Endpoints | Method | HTTP request | Description |