[WIP] Add error handling options for tuple operations

[Copilot]

Initial plan for implementing idempotency options for duplicate writes and missing deletes in OpenFGA Python SDK

Task Overview

Implement support for OpenFGA v1.10.0 API features:

• on_duplicate API property for controlling duplicate write behavior
• on_missing API property for controlling missing delete behavior

Implementation Plan

• Create enum classes for conflict options
  • Create OnDuplicateWrites enum (IGNORE, ERROR)
  • Create OnMissingDeletes enum (IGNORE, ERROR)
• Update API models to support new properties
  • Add on_duplicate field to WriteRequestWrites model
  • Add on_missing field to WriteRequestDeletes model
• Create client-level conflict options model
  • Create ClientWriteConflictOptions class
  • Update ClientWriteRequest to accept conflict options
• Update OpenFgaClient write methods to pass conflict options to API
  • Update write() method
  • Update write_tuples() method
  • Update delete_tuples() method
• Add comprehensive tests
  • Tests for OpenFgaApi layer (write with on_duplicate/on_missing)
  • Tests for OpenFgaClient layer (write with conflict options)
  • Tests for sync client as well
• Update documentation
  • Update README Write section with conflict options examples
  • Update CHANGELOG unreleased section
• Create example runner
  • Create example/conflict-options directory
  • Create runner script to test all permutations
  • Create docker-compose.yml for OpenFGA server
  • Create Makefile for easy execution

Working in progress...

Original prompt

Can you verify if all the following things are done correctly as
expected, do you see any gaps/differences

There are significant developer pain points when errors are received from the following operations:

Writing a tuple that already exists
Deleting a tuple that does not exist
Additional logic for error handling must be implemented to avoid or correct the situation, adding unnecessary complexity to client-side code and adding time required to complete operations due to retry scenarios.

Describe the ideal solution
OpenFGA v1.10.0 introduced support in the API for ignoring errors during duplicate writes (using the on_duplicate API property) and missing deletes (using the on_missing API property).

The SDKs must expose that in the underlying API client and models, as well as add support for idempotency options in the SDK client interface.

As an example for Go (each SDK should follow it's own similar conventions), the client should support the following options through ClientWriteOptions.Conflict:

OnDuplicateWrites: Controls behavior when writing a tuple that already exists
CLIENT_WRITE_REQUEST_ON_DUPLICATE_WRITES_IGNORE - Silently skip duplicate writes
CLIENT_WRITE_REQUEST_ON_DUPLICATE_WRITES_ERROR - Return error on duplicates (default)
OnMissingDeletes: Controls behavior when deleting a tuple that doesn't exist
CLIENT_WRITE_REQUEST_ON_MISSING_DELETES_IGNORE - Silently skip missing deletes
CLIENT_WRITE_REQUEST_ON_MISSING_DELETES_ERROR - Return error on missing deletes (default)
options := client.ClientWriteOptions{
Conflict: client.ConflictOptions{
OnDuplicateWrites: client.CLIENT_WRITE_REQUEST_ON_DUPLICATE_WRITES_ERROR,
OnMissingDeletes: client.CLIENT_WRITE_REQUEST_ON_MISSING_DELETES_IGNORE,
},
}
If the user does not specify the behavior, the default value as specified by the API should be sent.

Ensure that the:

Change has tests for both the OpenFgaApi and OpenFgaClient layers
The Write section in the README is appropriately updated
The unreleased section of the Changelog is updated

Further write a runner file inside a new example directory which uses this SDK itself
and runs all the permutatioons and combinations of ignore and error of missing and duplicate using actual openfga server

write a docker compose for the openfga server
and a makefile to quickly run the iterations

that's all thanks a lot

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.