feat: add support for write conflict settings (#234)

Author: ewanharris

README.md

@@ -641,6 +641,76 @@ var options = new ClientWriteOptions()
 var response = fgaClient.write(request, options).get();
 ```
 
+###### Conflict options for write operations
+
+Write conflict handling can be controlled using the `onDuplicate` option for writes and the `onMissing` option for deletes.
+
+> Note: this requires OpenFGA [v1.10.0](https://github.com/openfga/openfga/releases/tag/v1.10.0) or later.
+
+- `onDuplicate`: Controls behavior when attempting to create a tuple that already exists
+  - `WriteRequestWrites.OnDuplicateEnum.ERROR` (default): Return an error
+  - `WriteRequestWrites.OnDuplicateEnum.IGNORE`: Skip the duplicate tuple and continue
+  
+- `onMissing`: Controls behavior when attempting to delete a tuple that doesn't exist
+  - `WriteRequestDeletes.OnMissingEnum.ERROR` (default): Return an error
+  - `WriteRequestDeletes.OnMissingEnum.IGNORE`: Skip the missing tuple and continue
+
+**Using conflict options with the `write()` method:**
+
+```java
+var request = new ClientWriteRequest()
+    .writes(List.of(
+        new ClientTupleKey()
+            .user("user:81684243-9356-4421-8fbf-a4f8d36aa31b")
+            .relation("viewer")
+            ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a")
+    ))
+    .deletes(List.of(
+        new ClientTupleKeyWithoutCondition()
+            .user("user:81684243-9356-4421-8fbf-a4f8d36aa31b")
+            .relation("writer")
+            ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a")
+    ));
+
+var options = new ClientWriteOptions()
+    .onDuplicate(WriteRequestWrites.OnDuplicateEnum.IGNORE)
+    .onMissing(WriteRequestDeletes.OnMissingEnum.IGNORE);
+
+var response = fgaClient.write(request, options).get();
+```
+
+**Using conflict options with the `writeTuples()` convenience method:**
+
+```java
+var tuples = List.of(
+    new ClientTupleKey()
+        .user("user:81684243-9356-4421-8fbf-a4f8d36aa31b")
+        .relation("viewer")
+        ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a")
+);
+
+var options = new ClientWriteTuplesOptions()
+    .onDuplicate(WriteRequestWrites.OnDuplicateEnum.IGNORE);
+
+var response = fgaClient.writeTuples(tuples, options).get();
+```
+
+**Using conflict options with the `deleteTuples()` convenience method:**
+
+```java
+var tuples = List.of(
+    new ClientTupleKeyWithoutCondition()
+        .user("user:81684243-9356-4421-8fbf-a4f8d36aa31b")
+        .relation("writer")
+        ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a")
+);
+
+var options = new ClientDeleteTuplesOptions()
+    .onMissing(WriteRequestDeletes.OnMissingEnum.IGNORE);
+
+var response = fgaClient.deleteTuples(tuples, options).get();
+```
+
 #### Relationship Queries
 
 ##### Check

docs/OpenFgaApi.md

@@ -2303,7 +2303,7 @@ No authorization required
 
 Add or delete tuples from the store
 
-The Write API will transactionally update the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user. In the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored. The API is not idempotent: if, later on, you try to add the same tuple key (even if the `condition` is different), or if you try to delete a non-existing tuple, it will throw an error. The API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit. An `authorization_model_id` may be specified in the body. If it is, it will be used to assert that each written tuple (not deleted) is valid for the model specified. If it is not specified, the latest authorization model ID will be used. ## Example ### Adding relationships To add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following  ```json {   \"writes\": {     \"tuple_keys\": [       {         \"user\": \"user:anne\",         \"relation\": \"writer\",         \"object\": \"document:2021-budget\"       }     ]   },   \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ``` ### Removing relationships To remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following  ```json {   \"deletes\": {     \"tuple_keys\": [       {         \"user\": \"user:bob\",         \"relation\": \"reader\",         \"object\": \"document:2021-budget\"       }     ]   } } ``` 
+The Write API will transactionally update the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user. In the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored. The API is not idempotent by default: if, later on, you try to add the same tuple key (even if the `condition` is different), or if you try to delete a non-existing tuple, it will throw an error. To allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object. To allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object. If a Write request contains both idempotent (ignore) and non-idempotent (error) operations, the most restrictive action (error) will take precedence. If a condition fails for a sub-request with an error flag, the entire transaction will be rolled back. This gives developers explicit control over the atomicity of the requests. The API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit. An `authorization_model_id` may be specified in the body. If it is, it will be used to assert that each written tuple (not deleted) is valid for the model specified. If it is not specified, the latest authorization model ID will be used. ## Example ### Adding relationships To add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following  ```json {   \"writes\": {     \"tuple_keys\": [       {         \"user\": \"user:anne\",         \"relation\": \"writer\",         \"object\": \"document:2021-budget\"       }     ],     \"on_duplicate\": \"ignore\"   },   \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ``` ### Removing relationships To remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following  ```json {   \"deletes\": {     \"tuple_keys\": [       {         \"user\": \"user:bob\",         \"relation\": \"reader\",         \"object\": \"document:2021-budget\"       }     ],     \"on_missing\": \"ignore\"   } } ``` 
 
 ### Example
 
@@ -2378,7 +2378,7 @@ No authorization required
 
 Add or delete tuples from the store
 
-The Write API will transactionally update the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user. In the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored. The API is not idempotent: if, later on, you try to add the same tuple key (even if the `condition` is different), or if you try to delete a non-existing tuple, it will throw an error. The API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit. An `authorization_model_id` may be specified in the body. If it is, it will be used to assert that each written tuple (not deleted) is valid for the model specified. If it is not specified, the latest authorization model ID will be used. ## Example ### Adding relationships To add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following  ```json {   \"writes\": {     \"tuple_keys\": [       {         \"user\": \"user:anne\",         \"relation\": \"writer\",         \"object\": \"document:2021-budget\"       }     ]   },   \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ``` ### Removing relationships To remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following  ```json {   \"deletes\": {     \"tuple_keys\": [       {         \"user\": \"user:bob\",         \"relation\": \"reader\",         \"object\": \"document:2021-budget\"       }     ]   } } ``` 
+The Write API will transactionally update the tuples for a certain store. Tuples and type definitions allow OpenFGA to determine whether a relationship exists between an object and an user. In the body, `writes` adds new tuples and `deletes` removes existing tuples. When deleting a tuple, any `condition` specified with it is ignored. The API is not idempotent by default: if, later on, you try to add the same tuple key (even if the `condition` is different), or if you try to delete a non-existing tuple, it will throw an error. To allow writes when an identical tuple already exists in the database, set `\"on_duplicate\": \"ignore\"` on the `writes` object. To allow deletes when a tuple was already removed from the database, set `\"on_missing\": \"ignore\"` on the `deletes` object. If a Write request contains both idempotent (ignore) and non-idempotent (error) operations, the most restrictive action (error) will take precedence. If a condition fails for a sub-request with an error flag, the entire transaction will be rolled back. This gives developers explicit control over the atomicity of the requests. The API will not allow you to write tuples such as `document:2021-budget#viewer@document:2021-budget#viewer`, because they are implicit. An `authorization_model_id` may be specified in the body. If it is, it will be used to assert that each written tuple (not deleted) is valid for the model specified. If it is not specified, the latest authorization model ID will be used. ## Example ### Adding relationships To add `user:anne` as a `writer` for `document:2021-budget`, call write API with the following  ```json {   \"writes\": {     \"tuple_keys\": [       {         \"user\": \"user:anne\",         \"relation\": \"writer\",         \"object\": \"document:2021-budget\"       }     ],     \"on_duplicate\": \"ignore\"   },   \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ``` ### Removing relationships To remove `user:bob` as a `reader` for `document:2021-budget`, call write API with the following  ```json {   \"deletes\": {     \"tuple_keys\": [       {         \"user\": \"user:bob\",         \"relation\": \"reader\",         \"object\": \"document:2021-budget\"       }     ],     \"on_missing\": \"ignore\"   } } ``` 
 
 ### Example
 

docs/WriteRequestDeletes.md

@@ -8,6 +8,17 @@
 | Name | Type | Description | Notes |
 |------------ | ------------- | ------------- | -------------|
 |**tupleKeys** | [**List<TupleKeyWithoutCondition>**](TupleKeyWithoutCondition.md) |  |  |
+|**onMissing** | [**OnMissingEnum**](#OnMissingEnum) | On 'error', the API returns an error when deleting a tuple that does not exist. On 'ignore', deletes of non-existent tuples are treated as no-ops. |  [optional] |
+
+
+
+## Enum: OnMissingEnum
+
+| Name | Value |
+|---- | -----|
+| ERROR | "error" |
+| IGNORE | "ignore" |
+| UNKNOWN_DEFAULT_OPEN_API | "unknown_default_open_api" |
 
 
 

docs/WriteRequestWrites.md

@@ -8,6 +8,17 @@
 | Name | Type | Description | Notes |
 |------------ | ------------- | ------------- | -------------|
 |**tupleKeys** | [**List<TupleKey>**](TupleKey.md) |  |  |
+|**onDuplicate** | [**OnDuplicateEnum**](#OnDuplicateEnum) | On 'error' ( or unspecified ), the API returns an error if an identical tuple already exists. On 'ignore', identical writes are treated as no-ops (matching on user, relation, object, and RelationshipCondition). |  [optional] |
+
+
+
+## Enum: OnDuplicateEnum
+
+| Name | Value |
+|---- | -----|
+| ERROR | "error" |
+| IGNORE | "ignore" |
+| UNKNOWN_DEFAULT_OPEN_API | "unknown_default_open_api" |