feat(java-sdk): implement individual tuple error handling for non-tra… (#573)

Author: curfew-marathon

config/clients/java/config.overrides.json

@@ -181,6 +181,14 @@
       "destinationFilename": "src/main/java/dev/openfga/sdk/api/client/model/ClientWriteResponse.java",
       "templateType": "SupportingFiles"
     },
+    "src/main/api/client/model/ClientWriteSingleResponse.java.mustache": {
+      "destinationFilename": "src/main/java/dev/openfga/sdk/api/client/model/ClientWriteSingleResponse.java",
+      "templateType": "SupportingFiles"
+    },
+    "src/main/api/client/model/ClientWriteStatus.java.mustache": {
+      "destinationFilename": "src/main/java/dev/openfga/sdk/api/client/model/ClientWriteStatus.java",
+      "templateType": "SupportingFiles"
+    },
     "src/main/api/client/ClientAssertion.java.mustache": {
       "destinationFilename": "src/main/java/dev/openfga/sdk/api/client/ClientAssertion.java",
       "templateType": "SupportingFiles"
@@ -429,6 +437,14 @@
       "destinationFilename": "src/test/java/dev/openfga/sdk/api/client/OpenFgaClientTest.java",
       "templateType": "SupportingFiles"
     },
+    "src/test/api/client/model/ClientWriteStatusTest.java.mustache": {
+      "destinationFilename": "src/test/java/dev/openfga/sdk/api/client/model/ClientWriteStatusTest.java",
+      "templateType": "SupportingFiles"
+    },
+    "src/test/api/client/model/ClientWriteSingleResponseTest.java.mustache": {
+      "destinationFilename": "src/test/java/dev/openfga/sdk/api/client/model/ClientWriteSingleResponseTest.java",
+      "templateType": "SupportingFiles"
+    },
     "src/test/api/configuration/ClientCredentialsTest.java.mustache": {
       "destinationFilename": "src/test/java/dev/openfga/sdk/api/configuration/ClientCredentialsTest.java",
       "templateType": "SupportingFiles"

config/clients/java/template/example/example1/src/main/java/dev/openfga/sdk/example/Example1.java

@@ -18,9 +18,9 @@ public void run(String apiUrl) throws Exception {
         if (System.getenv("FGA_CLIENT_ID") != null) {
             credentials = new Credentials(new ClientCredentials()
                     .apiAudience(System.getenv("FGA_API_AUDIENCE"))
-                    .apiTokenIssuer(System.getenv("FGA_TOKEN_ISSUER"))
-                    .clientId("FGA_CLIENT_ID")
-                    .clientSecret("FGA_CLIENT_SECRET"));
+                    .apiTokenIssuer(System.getenv("FGA_API_TOKEN_ISSUER"))
+                    .clientId(System.getenv("FGA_CLIENT_ID"))
+                    .clientSecret(System.getenv("FGA_CLIENT_SECRET")));
         } else {
             System.out.println("Proceeding with no credentials (expecting localhost)");
         }
@@ -102,10 +102,20 @@ public void run(String apiUrl) throws Exception {
         fgaClient
                 .write(
                         new ClientWriteRequest()
-                                .writes(List.of(new ClientTupleKey()
-                                        .user("user:anne")
-                                        .relation("writer")
-                                        ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"))),
+                                .writes(List.of(
+                                        new ClientTupleKey()
+                                                .user("user:anne")
+                                                .relation("writer")
+                                                ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"),
+                                        new ClientTupleKey()
+                                                .user("user:anne")
+                                                .relation("writer")
+                                                ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a"), // duplicate
+                                        new ClientTupleKey()
+                                                .user("user:anne")
+                                                .relation("owner")
+                                                ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a") // different relation
+                                )),
                         new ClientWriteOptions()
                                 .disableTransactions(true)
                                 .authorizationModelId(authorizationModel.getAuthorizationModelId()))

config/clients/java/template/settings.gradle.mustache

@@ -1 +1,8 @@
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+}
+
 rootProject.name = '{{artifactId}}'

config/clients/java/template/src/main/api/client/OpenFgaClient.java.mustache

@@ -4,16 +4,29 @@ package {{clientPackage}}.model;
 import {{clientPackage}}.ApiResponse;
 import java.util.List;
 import java.util.Map;
+import java.util.Collections;
 
 public class ClientWriteResponse {
     private final int statusCode;
     private final Map<String, List<String>> headers;
     private final String rawResponse;
+    private final List<ClientWriteSingleResponse> writes;
+    private final List<ClientWriteSingleResponse> deletes;
 
     public ClientWriteResponse(ApiResponse<Object> apiResponse) {
         this.statusCode = apiResponse.getStatusCode();
         this.headers = apiResponse.getHeaders();
         this.rawResponse = apiResponse.getRawResponse();
+        this.writes = Collections.emptyList();
+        this.deletes = Collections.emptyList();
+    }
+
+    public ClientWriteResponse(List<ClientWriteSingleResponse> writes, List<ClientWriteSingleResponse> deletes) {
+        this.statusCode = 200;
+        this.headers = Collections.emptyMap();
+        this.rawResponse = "";
+        this.writes = writes != null ? writes : Collections.emptyList();
+        this.deletes = deletes != null ? deletes : Collections.emptyList();
     }
 
     public int getStatusCode() {
@@ -27,4 +40,12 @@ public class ClientWriteResponse {
     public String getRawResponse() {
         return rawResponse;
     }
+
+    public List<ClientWriteSingleResponse> getWrites() {
+        return writes;
+    }
+
+    public List<ClientWriteSingleResponse> getDeletes() {
+        return deletes;
+    }
 }

config/clients/java/template/src/main/api/client/model/ClientWriteResponse.java.mustache

@@ -0,0 +1,32 @@
+{{>licenseInfo}}
+package {{clientPackage}}.model;
+
+import {{modelPackage}}.TupleKey;
+
+public class ClientWriteSingleResponse {
+    private final TupleKey tupleKey;
+    private final ClientWriteStatus status;
+    private final Exception error;
+
+    public ClientWriteSingleResponse(TupleKey tupleKey, ClientWriteStatus status) {
+        this(tupleKey, status, null);
+    }
+
+    public ClientWriteSingleResponse(TupleKey tupleKey, ClientWriteStatus status, Exception error) {
+        this.tupleKey = tupleKey;
+        this.status = status;
+        this.error = error;
+    }
+
+    public TupleKey getTupleKey() {
+        return tupleKey;
+    }
+
+    public ClientWriteStatus getStatus() {
+        return status;
+    }
+
+    public Exception getError() {
+        return error;
+    }
+}

config/clients/java/template/src/main/api/client/model/ClientWriteSingleResponse.java.mustache

@@ -0,0 +1,22 @@
+{{>licenseInfo}}
+package {{clientPackage}}.model;
+
+public enum ClientWriteStatus {
+    SUCCESS("success"),
+    FAILURE("failure");
+
+    private final String value;
+
+    ClientWriteStatus(String value) {
+        this.value = value;
+    }
+
+    public String getValue() {
+        return value;
+    }
+
+    @Override
+    public String toString() {
+        return value;
+    }
+}

config/clients/java/template/src/main/api/client/model/ClientWriteStatus.java.mustache

@@ -1144,6 +1144,13 @@ public class OpenFgaClientTest {
         // Then
         mockHttpClient.verify().post(postPath).withBody(is(expectedBody)).called(1);
         assertEquals(200, response.getStatusCode());
+        
+        // Verify new response structure for transaction-based writes
+        assertEquals(1, response.getWrites().size());
+        assertEquals(0, response.getDeletes().size());
+        assertEquals(ClientWriteStatus.SUCCESS, response.getWrites().get(0).getStatus());
+        assertEquals(DEFAULT_USER, response.getWrites().get(0).getTupleKey().getUser());
+        assertNull(response.getWrites().get(0).getError());
     }
 
     /**
@@ -1245,18 +1252,18 @@ public class OpenFgaClientTest {
     }
 
     @Test
-    public void writeTest_nonTransactionsWithFailure() {
+    public void writeTest_nonTransactionsWithFailure() throws Exception {
         // Given
         String postPath = "https://api.fga.example/stores/01YCP46JKYM8FJCQ37NMBYHE5X/write";
         String firstUser = "user:first";
         String failedUser = "user:SECOND";
-        String skippedUser = "user:third";
+        String thirdUser = "user:third";
         Function<String, String> writeBody = user -> String.format(
                 "{\"writes\":{\"tuple_keys\":[{\"user\":\"%s\",\"relation\":\"%s\",\"object\":\"%s\",\"condition\":{\"name\":\"condition\",\"context\":{\"some\":\"context\"}}}]},\"deletes\":null,\"authorization_model_id\":\"%s\"}",
                 user, DEFAULT_RELATION, DEFAULT_OBJECT, DEFAULT_AUTH_MODEL_ID);
         mockHttpClient
                 .onPost(postPath)
-                .withBody(isOneOf(writeBody.apply(firstUser), writeBody.apply(skippedUser)))
+                .withBody(isOneOf(writeBody.apply(firstUser), writeBody.apply(thirdUser)))
                 .withHeader(CLIENT_METHOD_HEADER, "Write")
                 .withHeader(CLIENT_BULK_REQUEST_ID_HEADER, anyValidUUID())
                 .doReturn(200, EMPTY_RESPONSE_BODY);
@@ -1267,7 +1274,7 @@ public class OpenFgaClientTest {
                 .withHeader(CLIENT_BULK_REQUEST_ID_HEADER, anyValidUUID())
                 .doReturn(400, "{\"code\":\"validation_error\",\"message\":\"Generic validation error\"}");
         ClientWriteRequest request = new ClientWriteRequest()
-                .writes(Stream.of(firstUser, failedUser, skippedUser)
+                .writes(Stream.of(firstUser, failedUser, thirdUser)
                         .map(user -> new ClientTupleKey()
                                 ._object(DEFAULT_OBJECT)
                                 .relation(DEFAULT_RELATION)
@@ -1278,8 +1285,7 @@ public class OpenFgaClientTest {
                 new ClientWriteOptions().disableTransactions(true).transactionChunkSize(1);
 
         // When
-        var execException = assertThrows(
-                ExecutionException.class, () -> fga.write(request, options).get());
+        ClientWriteResponse response = fga.write(request, options).get();
 
         // Then
         mockHttpClient
@@ -1299,12 +1305,28 @@ public class OpenFgaClientTest {
         mockHttpClient
                 .verify()
                 .post(postPath)
-                .withBody(is(writeBody.apply(skippedUser)))
+                .withBody(is(writeBody.apply(thirdUser)))
                 .withHeader(CLIENT_METHOD_HEADER, "Write")
                 .withHeader(CLIENT_BULK_REQUEST_ID_HEADER, anyValidUUID())
-                .called(0);
-        var exception = assertInstanceOf(FgaApiValidationError.class, execException.getCause());
-        assertEquals(400, exception.getStatusCode());
+                .called(1);
+        
+        // Verify response structure
+        assertEquals(3, response.getWrites().size());
+        assertEquals(0, response.getDeletes().size());
+        
+        // Check individual tuple statuses
+        var writes = response.getWrites();
+        assertEquals(ClientWriteStatus.SUCCESS, writes.get(0).getStatus());
+        assertEquals(firstUser, writes.get(0).getTupleKey().getUser());
+        assertNull(writes.get(0).getError());
+        
+        assertEquals(ClientWriteStatus.FAILURE, writes.get(1).getStatus());
+        assertEquals(failedUser, writes.get(1).getTupleKey().getUser());
+        assertNotNull(writes.get(1).getError());
+        
+        assertEquals(ClientWriteStatus.SUCCESS, writes.get(2).getStatus());
+        assertEquals(thirdUser, writes.get(2).getTupleKey().getUser());
+        assertNull(writes.get(2).getError());
     }
 
     @Test

config/clients/java/template/src/test/api/client/OpenFgaClientTest.java.mustache

@@ -0,0 +1,38 @@
+{{>licenseInfo}}
+package {{clientPackage}}.model;
+
+import static org.junit.jupiter.api.Assertions.*;
+import org.junit.jupiter.api.Test;
+import {{modelPackage}}.TupleKey;
+
+public class ClientWriteSingleResponseTest {
+
+    @Test
+    public void testSuccessfulResponse() {
+        TupleKey tupleKey = new TupleKey()
+                .user("user:alice")
+                .relation("viewer")
+                ._object("document:test");
+        
+        ClientWriteSingleResponse response = new ClientWriteSingleResponse(tupleKey, ClientWriteStatus.SUCCESS);
+        
+        assertEquals(tupleKey, response.getTupleKey());
+        assertEquals(ClientWriteStatus.SUCCESS, response.getStatus());
+        assertNull(response.getError());
+    }
+
+    @Test
+    public void testFailedResponse() {
+        TupleKey tupleKey = new TupleKey()
+                .user("user:bob")
+                .relation("editor")
+                ._object("document:test");
+        Exception error = new RuntimeException("Test error");
+        
+        ClientWriteSingleResponse response = new ClientWriteSingleResponse(tupleKey, ClientWriteStatus.FAILURE, error);
+        
+        assertEquals(tupleKey, response.getTupleKey());
+        assertEquals(ClientWriteStatus.FAILURE, response.getStatus());
+        assertEquals(error, response.getError());
+    }
+}

config/clients/java/template/src/test/api/client/model/ClientWriteSingleResponseTest.java.mustache

@@ -0,0 +1,20 @@
+{{>licenseInfo}}
+package {{clientPackage}}.model;
+
+import static org.junit.jupiter.api.Assertions.*;
+import org.junit.jupiter.api.Test;
+
+public class ClientWriteStatusTest {
+
+    @Test
+    public void testSuccessValue() {
+        assertEquals("success", ClientWriteStatus.SUCCESS.getValue());
+        assertEquals("success", ClientWriteStatus.SUCCESS.toString());
+    }
+
+    @Test
+    public void testFailureValue() {
+        assertEquals("failure", ClientWriteStatus.FAILURE.getValue());
+        assertEquals("failure", ClientWriteStatus.FAILURE.toString());
+    }
+}