diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e3b0d5d..311af7b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,12 @@ - per-request headers support via `Headers` property on all client options classes - `IRequestOptions` interface and `RequestOptions` class for API-level header support - `IClientRequestOptions` interface and `ClientRequestOptions` class for client-level header support - - add header validation to prevent overiding of reserved headers + - add header validation to prevent overriding of reserved headers +- feat: add write conflict resolution options + - `ConflictOptions` to control behavior for duplicate writes and missing deletes + - `OnDuplicateWrites` option: `Error` (default) or `Ignore` for handling duplicate tuple writes + - `OnMissingDeletes` option: `Error` (default) or `Ignore` for handling missing tuple deletes + - Available in `ClientWriteOptions.Conflict` property [!WARNING] BREAKING CHANGES: @@ -15,11 +20,13 @@ BREAKING CHANGES: - **OpenFgaApi methods**: All API methods now accept an `IRequestOptions? options` parameter. If you are using the low-level `OpenFgaApi` directly, you may need to update your calls: Before: + ```csharp await api.Check(storeId, body, cancellationToken); ``` After: + ```csharp var options = new RequestOptions { Headers = new Dictionary { { "X-Custom-Header", "value" } } @@ -30,11 +37,13 @@ BREAKING CHANGES: - **ClientRequestOptions renamed**: The base client request options interface has been renamed from `ClientRequestOptions` to `IClientRequestOptions` to better follow .NET naming conventions. A concrete `ClientRequestOptions` class is now also available. If you were casting to or implementing this interface, update your code: Before: + ```csharp var options = obj as ClientRequestOptions; ``` After: + ```csharp var options = obj as IClientRequestOptions; ``` diff --git a/README.md b/README.md index 8a05dc12..9f277f95 100644 --- a/README.md +++ b/README.md @@ -574,6 +574,45 @@ var options = new ClientWriteOptions { var response = await fgaClient.Write(body, options); ``` +##### Conflict Options for Write Operations + +The SDK allows you to control how write conflicts are handled using the `Conflict` option: + +- **OnDuplicateWrites**: Controls behavior when writing a tuple that already exists + - `OnDuplicateWrites.Error` - Return error on duplicates (default) + - `OnDuplicateWrites.Ignore` - Silently skip duplicate writes + +- **OnMissingDeletes**: Controls behavior when deleting a tuple that doesn't exist + - `OnMissingDeletes.Error` - Return error on missing deletes (default) + - `OnMissingDeletes.Ignore` - Silently skip missing deletes + +```csharp +var body = new ClientWriteRequest() { + Writes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + Deletes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "writer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, +}; +var options = new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", + Conflict = new ConflictOptions { + OnDuplicateWrites = OnDuplicateWrites.Ignore, + OnMissingDeletes = OnMissingDeletes.Ignore + } +}; +var response = await fgaClient.Write(body, options); +``` + #### Relationship Queries ##### Check diff --git a/src/OpenFga.Sdk.Test/Client/OpenFgaClientTests.cs b/src/OpenFga.Sdk.Test/Client/OpenFgaClientTests.cs index 830d50a0..0b059dcb 100644 --- a/src/OpenFga.Sdk.Test/Client/OpenFgaClientTests.cs +++ b/src/OpenFga.Sdk.Test/Client/OpenFgaClientTests.cs @@ -1021,7 +1021,8 @@ public async Task WriteWriteTest() { }, Deletes = new List(), // should not get passed }; - var response = await fgaClient.Write(body, new ClientWriteOptions { + + await fgaClient.Write(body, new ClientWriteOptions { AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", }); @@ -1066,7 +1067,8 @@ public async Task WriteDeleteTest() { } }, }; - var response = await fgaClient.Write(body, new ClientWriteOptions { + + await fgaClient.Write(body, new ClientWriteOptions { AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", }); @@ -1118,7 +1120,8 @@ public async Task WriteMixedWithAuthorizationModelIdTest() { } }, }; - var response = await fgaClient.Write(body, new ClientWriteOptions { + + await fgaClient.Write(body, new ClientWriteOptions { AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", }); @@ -2181,6 +2184,506 @@ await client.Write( AssertHeaderPresent(mockHandler, TestHeaders.TraceId, "trace-456"); } + /// + /// Test Write with OnDuplicateWrites = Ignore + /// + [Fact] + public async Task Write_WithConflictOnDuplicateWritesIgnore_ShouldPassOptionToApi() { + WriteRequest? capturedRequest = null; + var mockHandler = new Mock(MockBehavior.Strict); + mockHandler.Protected() + .Setup>( + "SendAsync", + ItExpr.Is(req => + req.RequestUri == new Uri($"{_config.BasePath}/stores/{_config.StoreId}/write") && + req.Method == HttpMethod.Post), + ItExpr.IsAny() + ) + .ReturnsAsync(new HttpResponseMessage() { + StatusCode = HttpStatusCode.OK, + Content = Utils.CreateJsonStringContent(new Object()), + }) + .Callback((req, _) => { + var content = req.Content!.ReadAsStringAsync().Result; + capturedRequest = JsonSerializer.Deserialize(content); + }); + + var httpClient = new HttpClient(mockHandler.Object); + var fgaClient = new OpenFgaClient(_config, httpClient); + + var body = new ClientWriteRequest() { + Writes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + }; + + await fgaClient.Write(body, new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", + Conflict = new ConflictOptions { + OnDuplicateWrites = OnDuplicateWrites.Ignore + } + }); + + Assert.NotNull(capturedRequest); + Assert.NotNull(capturedRequest.Writes); + Assert.Equal(WriteRequestWrites.OnDuplicateEnum.Ignore, capturedRequest.Writes.OnDuplicate); + } + + /// + /// Test Write with OnDuplicateWrites = Error + /// + [Fact] + public async Task Write_WithConflictOnDuplicateWritesError_ShouldPassOptionToApi() { + WriteRequest? capturedRequest = null; + var mockHandler = new Mock(MockBehavior.Strict); + mockHandler.Protected() + .Setup>( + "SendAsync", + ItExpr.Is(req => + req.RequestUri == new Uri($"{_config.BasePath}/stores/{_config.StoreId}/write") && + req.Method == HttpMethod.Post), + ItExpr.IsAny() + ) + .ReturnsAsync(new HttpResponseMessage() { + StatusCode = HttpStatusCode.OK, + Content = Utils.CreateJsonStringContent(new Object()), + }) + .Callback((req, _) => { + var content = req.Content!.ReadAsStringAsync().Result; + capturedRequest = JsonSerializer.Deserialize(content); + }); + + var httpClient = new HttpClient(mockHandler.Object); + var fgaClient = new OpenFgaClient(_config, httpClient); + + var body = new ClientWriteRequest() { + Writes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + }; + + await fgaClient.Write(body, new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", + Conflict = new ConflictOptions { + OnDuplicateWrites = OnDuplicateWrites.Error + } + }); + + Assert.NotNull(capturedRequest); + Assert.NotNull(capturedRequest.Writes); + Assert.Equal(WriteRequestWrites.OnDuplicateEnum.Error, capturedRequest.Writes.OnDuplicate); + } + + /// + /// Test Write with OnMissingDeletes = Ignore + /// + [Fact] + public async Task Write_WithConflictOnMissingDeletesIgnore_ShouldPassOptionToApi() { + WriteRequest? capturedRequest = null; + var mockHandler = new Mock(MockBehavior.Strict); + mockHandler.Protected() + .Setup>( + "SendAsync", + ItExpr.Is(req => + req.RequestUri == new Uri($"{_config.BasePath}/stores/{_config.StoreId}/write") && + req.Method == HttpMethod.Post), + ItExpr.IsAny() + ) + .ReturnsAsync(new HttpResponseMessage() { + StatusCode = HttpStatusCode.OK, + Content = Utils.CreateJsonStringContent(new Object()), + }) + .Callback((req, _) => { + var content = req.Content!.ReadAsStringAsync().Result; + capturedRequest = JsonSerializer.Deserialize(content); + }); + + var httpClient = new HttpClient(mockHandler.Object); + var fgaClient = new OpenFgaClient(_config, httpClient); + + var body = new ClientWriteRequest() { + Deletes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + }; + + await fgaClient.Write(body, new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", + Conflict = new ConflictOptions { + OnMissingDeletes = OnMissingDeletes.Ignore + } + }); + + Assert.NotNull(capturedRequest); + Assert.NotNull(capturedRequest.Deletes); + Assert.Equal(WriteRequestDeletes.OnMissingEnum.Ignore, capturedRequest.Deletes.OnMissing); + } + + /// + /// Test Write with OnMissingDeletes = Error + /// + [Fact] + public async Task Write_WithConflictOnMissingDeletesError_ShouldPassOptionToApi() { + WriteRequest? capturedRequest = null; + var mockHandler = new Mock(MockBehavior.Strict); + mockHandler.Protected() + .Setup>( + "SendAsync", + ItExpr.Is(req => + req.RequestUri == new Uri($"{_config.BasePath}/stores/{_config.StoreId}/write") && + req.Method == HttpMethod.Post), + ItExpr.IsAny() + ) + .ReturnsAsync(new HttpResponseMessage() { + StatusCode = HttpStatusCode.OK, + Content = Utils.CreateJsonStringContent(new Object()), + }) + .Callback((req, _) => { + var content = req.Content!.ReadAsStringAsync().Result; + capturedRequest = JsonSerializer.Deserialize(content); + }); + + var httpClient = new HttpClient(mockHandler.Object); + var fgaClient = new OpenFgaClient(_config, httpClient); + + var body = new ClientWriteRequest() { + Deletes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + }; + + await fgaClient.Write(body, new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", + Conflict = new ConflictOptions { + OnMissingDeletes = OnMissingDeletes.Error + } + }); + + Assert.NotNull(capturedRequest); + Assert.NotNull(capturedRequest.Deletes); + Assert.Equal(WriteRequestDeletes.OnMissingEnum.Error, capturedRequest.Deletes.OnMissing); + } + + /// + /// Test Write with both OnDuplicateWrites and OnMissingDeletes + /// + [Fact] + public async Task Write_WithBothConflictOptions_ShouldPassBothOptionsToApi() { + WriteRequest? capturedRequest = null; + var mockHandler = new Mock(MockBehavior.Strict); + mockHandler.Protected() + .Setup>( + "SendAsync", + ItExpr.Is(req => + req.RequestUri == new Uri($"{_config.BasePath}/stores/{_config.StoreId}/write") && + req.Method == HttpMethod.Post), + ItExpr.IsAny() + ) + .ReturnsAsync(new HttpResponseMessage() { + StatusCode = HttpStatusCode.OK, + Content = Utils.CreateJsonStringContent(new Object()), + }) + .Callback((req, _) => { + var content = req.Content!.ReadAsStringAsync().Result; + capturedRequest = JsonSerializer.Deserialize(content); + }); + + var httpClient = new HttpClient(mockHandler.Object); + var fgaClient = new OpenFgaClient(_config, httpClient); + + var body = new ClientWriteRequest() { + Writes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + Deletes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "writer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + }; + + await fgaClient.Write(body, new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", + Conflict = new ConflictOptions { + OnDuplicateWrites = OnDuplicateWrites.Ignore, + OnMissingDeletes = OnMissingDeletes.Ignore + } + }); + + Assert.NotNull(capturedRequest); + Assert.NotNull(capturedRequest.Writes); + Assert.NotNull(capturedRequest.Deletes); + Assert.Equal(WriteRequestWrites.OnDuplicateEnum.Ignore, capturedRequest.Writes.OnDuplicate); + Assert.Equal(WriteRequestDeletes.OnMissingEnum.Ignore, capturedRequest.Deletes.OnMissing); + } + + /// + /// Test Write in non-transaction mode with conflict options + /// + [Fact] + public async Task Write_NonTransactionWithConflictOptions_ShouldPassOptionsToAllRequests() { + var capturedRequests = new List(); + var mockHandler = new Mock(MockBehavior.Strict); + mockHandler.Protected() + .Setup>( + "SendAsync", + ItExpr.Is(req => + req.RequestUri == new Uri($"{_config.BasePath}/stores/{_config.StoreId}/write") && + req.Method == HttpMethod.Post), + ItExpr.IsAny() + ) + .ReturnsAsync(new HttpResponseMessage() { + StatusCode = HttpStatusCode.OK, + Content = Utils.CreateJsonStringContent(new Object()), + }) + .Callback((req, _) => { + var content = req.Content!.ReadAsStringAsync().Result; + var writeRequest = JsonSerializer.Deserialize(content); + if (writeRequest != null) { + capturedRequests.Add(writeRequest); + } + }); + + var httpClient = new HttpClient(mockHandler.Object); + var fgaClient = new OpenFgaClient(_config, httpClient); + + var body = new ClientWriteRequest() { + Writes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + }, + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:budget", + } + }, + Deletes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "writer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + }; + + await fgaClient.Write(body, new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", + Transaction = new TransactionOptions { + Disable = true, + MaxPerChunk = 1 + }, + Conflict = new ConflictOptions { + OnDuplicateWrites = OnDuplicateWrites.Ignore, + OnMissingDeletes = OnMissingDeletes.Ignore + } + }); + + // Should have made 3 requests (2 writes + 1 delete in non-transaction mode) + Assert.Equal(3, capturedRequests.Count); + + // Verify each request has the conflict options + foreach (var request in capturedRequests) { + if (request.Writes != null) { + Assert.Equal(WriteRequestWrites.OnDuplicateEnum.Ignore, request.Writes.OnDuplicate); + } + if (request.Deletes != null) { + Assert.Equal(WriteRequestDeletes.OnMissingEnum.Ignore, request.Deletes.OnMissing); + } + } + } + + /// + /// Test Write with null conflict options (default behavior) + /// + [Fact] + public async Task Write_WithNullConflictOptions_ShouldUseApiDefaults() { + WriteRequest? capturedRequest = null; + var mockHandler = new Mock(MockBehavior.Strict); + mockHandler.Protected() + .Setup>( + "SendAsync", + ItExpr.Is(req => + req.RequestUri == new Uri($"{_config.BasePath}/stores/{_config.StoreId}/write") && + req.Method == HttpMethod.Post), + ItExpr.IsAny() + ) + .ReturnsAsync(new HttpResponseMessage() { + StatusCode = HttpStatusCode.OK, + Content = Utils.CreateJsonStringContent(new Object()), + }) + .Callback((req, _) => { + var content = req.Content!.ReadAsStringAsync().Result; + capturedRequest = JsonSerializer.Deserialize(content); + }); + + var httpClient = new HttpClient(mockHandler.Object); + var fgaClient = new OpenFgaClient(_config, httpClient); + + var body = new ClientWriteRequest() { + Writes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + Deletes = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "writer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }, + }; + + // Don't specify Conflict options - should use API defaults + await fgaClient.Write(body, new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1" + }); + + Assert.NotNull(capturedRequest); + // When no options are specified, the SDK explicitly sends Error as the default + Assert.NotNull(capturedRequest.Writes); + Assert.Equal(WriteRequestWrites.OnDuplicateEnum.Error, capturedRequest.Writes.OnDuplicate); + Assert.NotNull(capturedRequest.Deletes); + Assert.Equal(WriteRequestDeletes.OnMissingEnum.Error, capturedRequest.Deletes.OnMissing); + } + + /// + /// Test WriteTuples convenience method with conflict options + /// + [Fact] + public async Task WriteTuples_WithConflictOptions_ShouldPassOptionToApi() { + WriteRequest? capturedRequest = null; + HttpResponseMessage? responseMsg = null; + var mockHandler = new Mock(MockBehavior.Strict); + mockHandler.Protected() + .Setup>( + "SendAsync", + ItExpr.Is(req => + req.RequestUri == new Uri($"{_config.BasePath}/stores/{_config.StoreId}/write") && + req.Method == HttpMethod.Post), + ItExpr.IsAny() + ) + .ReturnsAsync(() => { + responseMsg = new HttpResponseMessage() { + StatusCode = HttpStatusCode.OK, + Content = Utils.CreateJsonStringContent(new Object()), + }; + return responseMsg; + }) + .Callback((req, _) => { + var content = req.Content!.ReadAsStringAsync().Result; + capturedRequest = JsonSerializer.Deserialize(content); + }); + + var httpClient = new HttpClient(mockHandler.Object); + var fgaClient = new OpenFgaClient(_config, httpClient); + + var tuples = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }; + + try { + await fgaClient.WriteTuples(tuples, new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", + Conflict = new ConflictOptions { + OnDuplicateWrites = OnDuplicateWrites.Ignore + } + }); + + Assert.NotNull(capturedRequest); + Assert.NotNull(capturedRequest.Writes); + Assert.Equal(WriteRequestWrites.OnDuplicateEnum.Ignore, capturedRequest.Writes.OnDuplicate); + } + finally { + if (responseMsg != null) + responseMsg.Dispose(); + } + } + + /// + /// Test DeleteTuples convenience method with conflict options + /// + [Fact] + public async Task DeleteTuples_WithConflictOptions_ShouldPassOptionToApi() { + WriteRequest? capturedRequest = null; + HttpResponseMessage? httpResponse = null; + var mockHandler = new Mock(MockBehavior.Strict); + mockHandler.Protected() + .Setup>( + "SendAsync", + ItExpr.Is(req => + req.RequestUri == new Uri($"{_config.BasePath}/stores/{_config.StoreId}/write") && + req.Method == HttpMethod.Post), + ItExpr.IsAny() + ) + .ReturnsAsync(() => { + httpResponse = new HttpResponseMessage() { + StatusCode = HttpStatusCode.OK, + Content = Utils.CreateJsonStringContent(new Object()), + }; + return httpResponse; + }) + .Callback((req, _) => { + var content = req.Content!.ReadAsStringAsync().Result; + capturedRequest = JsonSerializer.Deserialize(content); + }); + + var httpClient = new HttpClient(mockHandler.Object); + var fgaClient = new OpenFgaClient(_config, httpClient); + + var tuples = new List { + new() { + User = "user:81684243-9356-4421-8fbf-a4f8d36aa31b", + Relation = "viewer", + Object = "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a", + } + }; + + await fgaClient.DeleteTuples(tuples, new ClientWriteOptions { + AuthorizationModelId = "01GXSA8YR785C4FYS3C0RTG7B1", + Conflict = new ConflictOptions { + OnMissingDeletes = OnMissingDeletes.Ignore + } + }); + + Assert.NotNull(capturedRequest); + Assert.NotNull(capturedRequest.Deletes); + Assert.Equal(WriteRequestDeletes.OnMissingEnum.Ignore, capturedRequest.Deletes.OnMissing); + + httpResponse?.Dispose(); + } + /// /// Test Read with custom headers /// @@ -2405,8 +2908,7 @@ public async Task ReadLatestAuthorizationModel_WithCustomHeaders_ShouldPropagate var options = new ClientWriteOptions { Headers = new Dictionary { { "X-Latest-Model", "latest-xyz" } - }, - Transaction = new TransactionOptions() + } }; var response = await client.ReadLatestAuthorizationModel(options); @@ -2879,4 +3381,4 @@ await client.Check( } #endregion -} \ No newline at end of file +} diff --git a/src/OpenFga.Sdk/Api/OpenFgaApi.cs b/src/OpenFga.Sdk/Api/OpenFgaApi.cs index 401e8477..8af5bed1 100644 --- a/src/OpenFga.Sdk/Api/OpenFgaApi.cs +++ b/src/OpenFga.Sdk/Api/OpenFgaApi.cs @@ -41,7 +41,7 @@ public OpenFgaApi( } /// - /// Send a list of `check` operations in a single request The `BatchCheck` API functions nearly identically to `Check`, but instead of checking a single user-object relationship BatchCheck accepts a list of relationships to check and returns a map containing `BatchCheckItem` response for each check it received. An associated `correlation_id` is required for each check in the batch. This ID is used to correlate a check to the appropriate response. It is a string consisting of only alphanumeric characters or hyphens with a maximum length of 36 characters. This `correlation_id` is used to map the result of each check to the item which was checked, so it must be unique for each item in the batch. We recommend using a UUID or ULID as the `correlation_id`, but you can use whatever unique identifier you need as long as it matches this regex pattern: `^[\\w\\d-]{1,36}$` NOTE: The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#OPENFGA_MAX_CHECKS_PER_BATCH_CHECK) environment variable. If `BatchCheck` is called using the SDK, the SDK can split the batch check requests for you. For more details on how `Check` functions, see the docs for `/check`. ### Examples #### A BatchCheckRequest ```json { \"checks\": [ { \"tuple_key\": { \"object\": \"document:2021-budget\" \"relation\": \"reader\", \"user\": \"user:anne\", }, \"contextual_tuples\": {...} \"context\": {} \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\" }, { \"tuple_key\": { \"object\": \"document:2021-budget\" \"relation\": \"reader\", \"user\": \"user:bob\", }, \"contextual_tuples\": {...} \"context\": {} \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\" } ] } ``` Below is a possible response to the above request. Note that the result map's keys are the `correlation_id` values from the checked items in the request: ```json { \"result\": { \"01JA8PMM6A90NV5ET0F28CYSZQ\": { \"allowed\": false, \"error\": {\"message\": \"\"} }, \"01JA8PM3QM7VBPGB8KMPK8SBD5\": { \"allowed\": true, \"error\": {\"message\": \"\"} } } ``` + /// Send a list of `check` operations in a single request The `BatchCheck` API functions nearly identically to `Check`, but instead of checking a single user-object relationship BatchCheck accepts a list of relationships to check and returns a map containing `BatchCheckItem` response for each check it received. An associated `correlation_id` is required for each check in the batch. This ID is used to correlate a check to the appropriate response. It is a string consisting of only alphanumeric characters or hyphens with a maximum length of 36 characters. This `correlation_id` is used to map the result of each check to the item which was checked, so it must be unique for each item in the batch. We recommend using a UUID or ULID as the `correlation_id`, but you can use whatever unique identifier you need as long as it matches this regex pattern: `^[\\w\\d-]{1,36}$` NOTE: The maximum number of checks that can be passed in the `BatchCheck` API is configurable via the [OPENFGA_MAX_CHECKS_PER_BATCH_CHECK](https://openfga.dev/docs/getting-started/setup-openfga/configuration#OPENFGA_MAX_CHECKS_PER_BATCH_CHECK) environment variable. If `BatchCheck` is called using the SDK, the SDK can split the batch check requests for you. For more details on how `Check` functions, see the docs for `/check`. ### Examples #### A BatchCheckRequest ```json { \"checks\": [ { \"tuple_key\": { \"object\": \"document:2021-budget\" \"relation\": \"reader\", \"user\": \"user:anne\", }, \"contextual_tuples\": {...} \"context\": {} \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\" }, { \"tuple_key\": { \"object\": \"document:2021-budget\" \"relation\": \"reader\", \"user\": \"user:bob\", }, \"contextual_tuples\": {...} \"context\": {} \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\" } ] } ``` Below is a possible response to the above request. Note that the result map's keys are the `correlation_id` values from the checked items in the request: ```json { \"result\": { \"01JA8PMM6A90NV5ET0F28CYSZQ\": { \"allowed\": false, \"error\": {\"message\": \"\"} }, \"01JA8PM3QM7VBPGB8KMPK8SBD5\": { \"allowed\": true, \"error\": {\"message\": \"\"} } } ``` /// /// Thrown when fails to make API call /// @@ -74,7 +74,7 @@ public async Task BatchCheck(string storeId, BatchCheckReque } /// - /// Check whether a user is authorized to access an object The Check API returns whether a given user has a relationship with a given object in a given store. The `user` field of the request can be a specific target, such as `user:anne`, or a userset (set of users) such as `group:marketing#member` or a type-bound public access `user:*`. To arrive at a result, the API uses: an authorization model, explicit tuples written through the Write API, contextual tuples present in the request, and implicit tuples that exist by virtue of applying set theory (such as `document:2021-budget#viewer@document:2021-budget#viewer`; the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`). A `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an associated `condition`. You may also provide an `authorization_model_id` in the body. This will be used to assert that the input `tuple_key` is valid for the model specified. If not specified, the assertion will be made against the latest authorization model ID. It is strongly recommended to specify authorization model id for better performance. You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly. By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency. The response will return whether the relationship exists in the field `allowed`. Some exceptions apply, but in general, if a Check API responds with `{allowed: true}`, then you can expect the equivalent ListObjects query to return the object, and viceversa. For example, if `Check(user:anne, reader, document:2021-budget)` responds with `{allowed: true}`, then `ListObjects(user:anne, reader, document)` may include `document:2021-budget` in the response. ## Examples ### Querying with contextual tuples In order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple ```json { \"user\": \"user:anne\", \"relation\": \"member\", \"object\": \"time_slot:office_hours\" } ``` the Check API can be used with the following request body: ```json { \"tuple_key\": { \"user\": \"user:anne\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"contextual_tuples\": { \"tuple_keys\": [ { \"user\": \"user:anne\", \"relation\": \"member\", \"object\": \"time_slot:office_hours\" } ] }, \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ``` ### Querying usersets Some Checks will always return `true`, even without any tuples. For example, for the following authorization model ```python model schema 1.1 type user type document relations define reader: [user] ``` the following query ```json { \"tuple_key\": { \"user\": \"document:2021-budget#reader\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" } } ``` will always return `{ \"allowed\": true }`. This is because usersets are self-defining: the userset `document:2021-budget#reader` will always have the `reader` relation with `document:2021-budget`. ### Querying usersets with difference in the model A Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model ```python model schema 1.1 type user type group relations define member: [user] type document relations define blocked: [user] define reader: [group#member] but not blocked ``` the following query ```json { \"tuple_key\": { \"user\": \"group:finance#member\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"contextual_tuples\": { \"tuple_keys\": [ { \"user\": \"user:anne\", \"relation\": \"member\", \"object\": \"group:finance\" }, { \"user\": \"group:finance#member\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, { \"user\": \"user:anne\", \"relation\": \"blocked\", \"object\": \"document:2021-budget\" } ] }, } ``` will return `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object. ### Requesting higher consistency By default, the Check API caches results for a short time to optimize performance. You may request higher consistency to inform the server that higher consistency should be preferred at the expense of increased latency. Care should be taken when requesting higher consistency due to the increased latency. ```json { \"tuple_key\": { \"user\": \"group:finance#member\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"consistency\": \"HIGHER_CONSISTENCY\" } ``` + /// Check whether a user is authorized to access an object The Check API returns whether a given user has a relationship with a given object in a given store. The `user` field of the request can be a specific target, such as `user:anne`, or a userset (set of users) such as `group:marketing#member` or a type-bound public access `user:*`. To arrive at a result, the API uses: an authorization model, explicit tuples written through the Write API, contextual tuples present in the request, and implicit tuples that exist by virtue of applying set theory (such as `document:2021-budget#viewer@document:2021-budget#viewer`; the set of users who are viewers of `document:2021-budget` are the set of users who are the viewers of `document:2021-budget`). A `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an associated `condition`. You may also provide an `authorization_model_id` in the body. This will be used to assert that the input `tuple_key` is valid for the model specified. If not specified, the assertion will be made against the latest authorization model ID. It is strongly recommended to specify authorization model id for better performance. You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly. By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency. The response will return whether the relationship exists in the field `allowed`. Some exceptions apply, but in general, if a Check API responds with `{allowed: true}`, then you can expect the equivalent ListObjects query to return the object, and viceversa. For example, if `Check(user:anne, reader, document:2021-budget)` responds with `{allowed: true}`, then `ListObjects(user:anne, reader, document)` may include `document:2021-budget` in the response. ## Examples ### Querying with contextual tuples In order to check if user `user:anne` of type `user` has a `reader` relationship with object `document:2021-budget` given the following contextual tuple ```json { \"user\": \"user:anne\", \"relation\": \"member\", \"object\": \"time_slot:office_hours\" } ``` the Check API can be used with the following request body: ```json { \"tuple_key\": { \"user\": \"user:anne\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"contextual_tuples\": { \"tuple_keys\": [ { \"user\": \"user:anne\", \"relation\": \"member\", \"object\": \"time_slot:office_hours\" } ] }, \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ``` ### Querying usersets Some Checks will always return `true`, even without any tuples. For example, for the following authorization model ```python model schema 1.1 type user type document relations define reader: [user] ``` the following query ```json { \"tuple_key\": { \"user\": \"document:2021-budget#reader\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" } } ``` will always return `{ \"allowed\": true }`. This is because usersets are self-defining: the userset `document:2021-budget#reader` will always have the `reader` relation with `document:2021-budget`. ### Querying usersets with difference in the model A Check for a userset can yield results that must be treated carefully if the model involves difference. For example, for the following authorization model ```python model schema 1.1 type user type group relations define member: [user] type document relations define blocked: [user] define reader: [group#member] but not blocked ``` the following query ```json { \"tuple_key\": { \"user\": \"group:finance#member\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"contextual_tuples\": { \"tuple_keys\": [ { \"user\": \"user:anne\", \"relation\": \"member\", \"object\": \"group:finance\" }, { \"user\": \"group:finance#member\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, { \"user\": \"user:anne\", \"relation\": \"blocked\", \"object\": \"document:2021-budget\" } ] }, } ``` will return `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object. ### Requesting higher consistency By default, the Check API caches results for a short time to optimize performance. You may request higher consistency to inform the server that higher consistency should be preferred at the expense of increased latency. Care should be taken when requesting higher consistency due to the increased latency. ```json { \"tuple_key\": { \"user\": \"group:finance#member\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"consistency\": \"HIGHER_CONSISTENCY\" } ``` /// /// Thrown when fails to make API call /// @@ -164,7 +164,7 @@ await _apiClient.SendRequestAsync(requestBuilder, } /// - /// Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship The Expand API will return all users and usersets that have certain relationship with an object in a certain store. This is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned. Body parameters `tuple_key.object` and `tuple_key.relation` are all required. A `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an associated `condition`. The response will return a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes. ## Example To expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body ```json { \"tuple_key\": { \"object\": \"document:2021-budget\", \"relation\": \"reader\" }, \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ``` OpenFGA's response will be a userset tree of the users and usersets that have read access to the document. ```json { \"tree\":{ \"root\":{ \"type\":\"document:2021-budget#reader\", \"union\":{ \"nodes\":[ { \"type\":\"document:2021-budget#reader\", \"leaf\":{ \"users\":{ \"users\":[ \"user:bob\" ] } } }, { \"type\":\"document:2021-budget#reader\", \"leaf\":{ \"computed\":{ \"userset\":\"document:2021-budget#writer\" } } } ] } } } } ``` The caller can then call expand API for the `writer` relationship for the `document:2021-budget`. ### Expand Request with Contextual Tuples Given the model ```python model schema 1.1 type user type folder relations define owner: [user] type document relations define parent: [folder] define viewer: [user] or writer define writer: [user] or owner from parent ``` and the initial tuples ```json [{ \"user\": \"user:bob\", \"relation\": \"owner\", \"object\": \"folder:1\" }] ``` To expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be ```json { \"tuple_key\": { \"object\": \"document:1\", \"relation\": \"writer\" }, \"contextual_tuples\": { \"tuple_keys\": [ { \"user\": \"folder:1\", \"relation\": \"parent\", \"object\": \"document:1\" } ] } } ``` this returns: ```json { \"tree\": { \"root\": { \"name\": \"document:1#writer\", \"union\": { \"nodes\": [ { \"name\": \"document:1#writer\", \"leaf\": { \"users\": { \"users\": [] } } }, { \"name\": \"document:1#writer\", \"leaf\": { \"tupleToUserset\": { \"tupleset\": \"document:1#parent\", \"computed\": [ { \"userset\": \"folder:1#owner\" } ] } } } ] } } } } ``` This tells us that the `owner` of `folder:1` may also be a writer. So our next call could be to find the `owners` of `folder:1` ```json { \"tuple_key\": { \"object\": \"folder:1\", \"relation\": \"owner\" } } ``` which gives ```json { \"tree\": { \"root\": { \"name\": \"folder:1#owner\", \"leaf\": { \"users\": { \"users\": [ \"user:bob\" ] } } } } } ``` + /// Expand all relationships in userset tree format, and following userset rewrite rules. Useful to reason about and debug a certain relationship The Expand API will return all users and usersets that have certain relationship with an object in a certain store. This is different from the `/stores/{store_id}/read` API in that both users and computed usersets are returned. Body parameters `tuple_key.object` and `tuple_key.relation` are all required. A `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an associated `condition`. The response will return a tree whose leaves are the specific users and usersets. Union, intersection and difference operator are located in the intermediate nodes. ## Example To expand all users that have the `reader` relationship with object `document:2021-budget`, use the Expand API with the following request body ```json { \"tuple_key\": { \"object\": \"document:2021-budget\", \"relation\": \"reader\" }, \"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\" } ``` OpenFGA's response will be a userset tree of the users and usersets that have read access to the document. ```json { \"tree\":{ \"root\":{ \"type\":\"document:2021-budget#reader\", \"union\":{ \"nodes\":[ { \"type\":\"document:2021-budget#reader\", \"leaf\":{ \"users\":{ \"users\":[ \"user:bob\" ] } } }, { \"type\":\"document:2021-budget#reader\", \"leaf\":{ \"computed\":{ \"userset\":\"document:2021-budget#writer\" } } } ] } } } } ``` The caller can then call expand API for the `writer` relationship for the `document:2021-budget`. ### Expand Request with Contextual Tuples Given the model ```python model schema 1.1 type user type folder relations define owner: [user] type document relations define parent: [folder] define viewer: [user] or writer define writer: [user] or owner from parent ``` and the initial tuples ```json [{ \"user\": \"user:bob\", \"relation\": \"owner\", \"object\": \"folder:1\" }] ``` To expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be ```json { \"tuple_key\": { \"object\": \"document:1\", \"relation\": \"writer\" }, \"contextual_tuples\": { \"tuple_keys\": [ { \"user\": \"folder:1\", \"relation\": \"parent\", \"object\": \"document:1\" } ] } } ``` this returns: ```json { \"tree\": { \"root\": { \"name\": \"document:1#writer\", \"union\": { \"nodes\": [ { \"name\": \"document:1#writer\", \"leaf\": { \"users\": { \"users\": [] } } }, { \"name\": \"document:1#writer\", \"leaf\": { \"tupleToUserset\": { \"tupleset\": \"document:1#parent\", \"computed\": [ { \"userset\": \"folder:1#owner\" } ] } } } ] } } } } ``` This tells us that the `owner` of `folder:1` may also be a writer. So our next call could be to find the `owners` of `folder:1` ```json { \"tuple_key\": { \"object\": \"folder:1\", \"relation\": \"owner\" } } ``` which gives ```json { \"tree\": { \"root\": { \"name\": \"folder:1#owner\", \"leaf\": { \"users\": { \"users\": [ \"user:bob\" ] } } } } } ``` /// /// Thrown when fails to make API call /// @@ -261,7 +261,7 @@ public async Task ListObjects(string storeId, ListObjectsRe } /// - /// List all stores Returns a paginated list of OpenFGA stores and a continuation token to get additional stores. The continuation token will be empty if there are no more stores. + /// List all stores Returns a paginated list of OpenFGA stores and a continuation token to get additional stores. The continuation token will be empty if there are no more stores. /// /// Thrown when fails to make API call /// (optional) @@ -330,7 +330,7 @@ public async Task ListUsers(string storeId, ListUsersRequest } /// - /// Get tuples from the store that matches a query, without following userset rewrite rules The Read API will return the tuples for a certain store that match a query filter specified in the body of the request. The API doesn't guarantee order by any field. It is different from the `/stores/{store_id}/expand` API in that it only returns relationship tuples that are stored in the system and satisfy the query. In the body: 1. `tuple_key` is optional. If not specified, it will return all tuples in the store. 2. `tuple_key.object` is mandatory if `tuple_key` is specified. It can be a full object (e.g., `type:object_id`) or type only (e.g., `type:`). 3. `tuple_key.user` is mandatory if tuple_key is specified in the case the `tuple_key.object` is a type only. If tuple_key.user is specified, it needs to be a full object (e.g., `type:user_id`). ## Examples ### Query for all objects in a type definition To query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of ```json { \"tuple_key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:\" } } ``` The API will return tuples and a continuation token, something like ```json { \"tuples\": [ { \"key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-06T15:32:11.128Z\" } ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } ``` This means that `user:bob` has a `reader` relationship with 1 document `document:2021-budget`. Note that this API, unlike the List Objects API, does not evaluate the tuples in the store. The continuation token will be empty if there are no more tuples to query. ### Query for all stored relationship tuples that have a particular relation and object To query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of ```json { \"tuple_key\": { \"object\": \"document:2021-budget\", \"relation\": \"reader\" } } ``` The API will return something like ```json { \"tuples\": [ { \"key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-06T15:32:11.128Z\" } ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } ``` This means that `document:2021-budget` has 1 `reader` (`user:bob`). Note that, even if the model said that all `writers` are also `readers`, the API will not return writers such as `user:anne` because it only returns tuples and does not evaluate them. ### Query for all users with all relationships for a particular document To query for all users that have any relationship with `document:2021-budget`, call read API with body of ```json { \"tuple_key\": { \"object\": \"document:2021-budget\" } } ``` The API will return something like ```json { \"tuples\": [ { \"key\": { \"user\": \"user:anne\", \"relation\": \"writer\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-05T13:42:12.356Z\" }, { \"key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-06T15:32:11.128Z\" } ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } ``` This means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`). + /// Get tuples from the store that matches a query, without following userset rewrite rules The Read API will return the tuples for a certain store that match a query filter specified in the body of the request. The API doesn't guarantee order by any field. It is different from the `/stores/{store_id}/expand` API in that it only returns relationship tuples that are stored in the system and satisfy the query. In the body: 1. `tuple_key` is optional. If not specified, it will return all tuples in the store. 2. `tuple_key.object` is mandatory if `tuple_key` is specified. It can be a full object (e.g., `type:object_id`) or type only (e.g., `type:`). 3. `tuple_key.user` is mandatory if tuple_key is specified in the case the `tuple_key.object` is a type only. If tuple_key.user is specified, it needs to be a full object (e.g., `type:user_id`). ## Examples ### Query for all objects in a type definition To query for all objects that `user:bob` has `reader` relationship in the `document` type definition, call read API with body of ```json { \"tuple_key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:\" } } ``` The API will return tuples and a continuation token, something like ```json { \"tuples\": [ { \"key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-06T15:32:11.128Z\" } ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } ``` This means that `user:bob` has a `reader` relationship with 1 document `document:2021-budget`. Note that this API, unlike the List Objects API, does not evaluate the tuples in the store. The continuation token will be empty if there are no more tuples to query. ### Query for all stored relationship tuples that have a particular relation and object To query for all users that have `reader` relationship with `document:2021-budget`, call read API with body of ```json { \"tuple_key\": { \"object\": \"document:2021-budget\", \"relation\": \"reader\" } } ``` The API will return something like ```json { \"tuples\": [ { \"key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-06T15:32:11.128Z\" } ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } ``` This means that `document:2021-budget` has 1 `reader` (`user:bob`). Note that, even if the model said that all `writers` are also `readers`, the API will not return writers such as `user:anne` because it only returns tuples and does not evaluate them. ### Query for all users with all relationships for a particular document To query for all users that have any relationship with `document:2021-budget`, call read API with body of ```json { \"tuple_key\": { \"object\": \"document:2021-budget\" } } ``` The API will return something like ```json { \"tuples\": [ { \"key\": { \"user\": \"user:anne\", \"relation\": \"writer\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-05T13:42:12.356Z\" }, { \"key\": { \"user\": \"user:bob\", \"relation\": \"reader\", \"object\": \"document:2021-budget\" }, \"timestamp\": \"2021-10-06T15:32:11.128Z\" } ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } ``` This means that `document:2021-budget` has 1 `reader` (`user:bob`) and 1 `writer` (`user:anne`). /// /// Thrown when fails to make API call /// @@ -363,7 +363,7 @@ public async Task Read(string storeId, ReadRequest body, IRequestO } /// - /// Read assertions for an authorization model ID The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. + /// Read assertions for an authorization model ID The ReadAssertions API will return, for a given authorization model id, all the assertions stored for it. /// /// Thrown when fails to make API call /// @@ -433,7 +433,7 @@ public async Task ReadAuthorizationModel(string } /// - /// Return all the authorization models for a particular store The ReadAuthorizationModels API will return all the authorization models for a certain store. OpenFGA's response will contain an array of all authorization models, sorted in descending order of creation. ## Example Assume that a store's authorization model has been configured twice. To get all the authorization models that have been created in this store, call GET authorization-models. The API will return a response that looks like: ```json { \"authorization_models\": [ { \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\", \"type_definitions\": [...] }, { \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\", \"type_definitions\": [...] }, ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } ``` If there are no more authorization models available, the `continuation_token` field will be empty ```json { \"authorization_models\": [ { \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\", \"type_definitions\": [...] }, { \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\", \"type_definitions\": [...] }, ], \"continuation_token\": \"\" } ``` + /// Return all the authorization models for a particular store The ReadAuthorizationModels API will return all the authorization models for a certain store. OpenFGA's response will contain an array of all authorization models, sorted in descending order of creation. ## Example Assume that a store's authorization model has been configured twice. To get all the authorization models that have been created in this store, call GET authorization-models. The API will return a response that looks like: ```json { \"authorization_models\": [ { \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\", \"type_definitions\": [...] }, { \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\", \"type_definitions\": [...] }, ], \"continuation_token\": \"eyJwayI6IkxBVEVTVF9OU0NPTkZJR19hdXRoMHN0b3JlIiwic2siOiIxem1qbXF3MWZLZExTcUoyN01MdTdqTjh0cWgifQ==\" } ``` If there are no more authorization models available, the `continuation_token` field will be empty ```json { \"authorization_models\": [ { \"id\": \"01G50QVV17PECNVAHX1GG4Y5NC\", \"type_definitions\": [...] }, { \"id\": \"01G4ZW8F4A07AKQ8RHSVG9RW04\", \"type_definitions\": [...] }, ], \"continuation_token\": \"\" } ``` /// /// Thrown when fails to make API call /// @@ -472,7 +472,7 @@ public async Task ReadAuthorizationModel(string } /// - /// Return a list of all the tuple changes The ReadChanges API will return a paginated list of tuple changes (additions and deletions) that occurred in a given store, sorted by ascending time. The response will include a continuation token that is used to get the next set of changes. If there are no changes after the provided continuation token, the same token will be returned in order for it to be used when new changes are recorded. If the store never had any tuples added or removed, this token will be empty. You can use the `type` parameter to only get the list of tuple changes that affect objects of that type. When reading a write tuple change, if it was conditioned, the condition will be returned. When reading a delete tuple change, the condition will NOT be returned regardless of whether it was originally conditioned or not. + /// Return a list of all the tuple changes The ReadChanges API will return a paginated list of tuple changes (additions and deletions) that occurred in a given store, sorted by ascending time. The response will include a continuation token that is used to get the next set of changes. If there are no changes after the provided continuation token, the same token will be returned in order for it to be used when new changes are recorded. If the store never had any tuples added or removed, this token will be empty. You can use the `type` parameter to only get the list of tuple changes that affect objects of that type. When reading a write tuple change, if it was conditioned, the condition will be returned. When reading a delete tuple change, the condition will NOT be returned regardless of whether it was originally conditioned or not. /// /// Thrown when fails to make API call /// @@ -520,7 +520,7 @@ public async Task ReadAuthorizationModel(string } /// - /// 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 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\" } } ``` + /// 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 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\" } } ``` /// /// Thrown when fails to make API call /// @@ -590,7 +590,7 @@ await _apiClient.SendRequestAsync(requestBuilder, } /// - /// Create a new authorization model The WriteAuthorizationModel API will add a new authorization model to a store. Each item in the `type_definitions` array is a type definition as specified in the field `type_definition`. The response will return the authorization model's ID in the `id` field. ## Example To add an authorization model with `user` and `document` type definitions, call POST authorization-models API with the body: ```json { \"type_definitions\":[ { \"type\":\"user\" }, { \"type\":\"document\", \"relations\":{ \"reader\":{ \"union\":{ \"child\":[ { \"this\":{} }, { \"computedUserset\":{ \"object\":\"\", \"relation\":\"writer\" } } ] } }, \"writer\":{ \"this\":{} } } } ] } ``` OpenFGA's response will include the version id for this authorization model, which will look like ``` {\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"} ``` + /// Create a new authorization model The WriteAuthorizationModel API will add a new authorization model to a store. Each item in the `type_definitions` array is a type definition as specified in the field `type_definition`. The response will return the authorization model's ID in the `id` field. ## Example To add an authorization model with `user` and `document` type definitions, call POST authorization-models API with the body: ```json { \"type_definitions\":[ { \"type\":\"user\" }, { \"type\":\"document\", \"relations\":{ \"reader\":{ \"union\":{ \"child\":[ { \"this\":{} }, { \"computedUserset\":{ \"object\":\"\", \"relation\":\"writer\" } } ] } }, \"writer\":{ \"this\":{} } } } ] } ``` OpenFGA's response will include the version id for this authorization model, which will look like ``` {\"authorization_model_id\": \"01G50QVV17PECNVAHX1GG4Y5NC\"} ``` /// /// Thrown when fails to make API call /// @@ -626,4 +626,4 @@ public async Task WriteAuthorizationModel(strin public void Dispose() { _apiClient.Dispose(); } -} \ No newline at end of file +} diff --git a/src/OpenFga.Sdk/ApiClient/ApiClient.cs b/src/OpenFga.Sdk/ApiClient/ApiClient.cs index 81f4d276..c30393c3 100644 --- a/src/OpenFga.Sdk/ApiClient/ApiClient.cs +++ b/src/OpenFga.Sdk/ApiClient/ApiClient.cs @@ -230,4 +230,4 @@ private async Task> Retry(Func _baseClient.Dispose(); -} \ No newline at end of file +} diff --git a/src/OpenFga.Sdk/Client/Client.cs b/src/OpenFga.Sdk/Client/Client.cs index fb697a28..f5738208 100644 --- a/src/OpenFga.Sdk/Client/Client.cs +++ b/src/OpenFga.Sdk/Client/Client.cs @@ -224,6 +224,20 @@ private string GetStoreId(StoreIdOptions? options) { return authorizationModelId; } + private static WriteRequestWrites.OnDuplicateEnum MapOnDuplicateWrites(OnDuplicateWrites? behavior) { + if (behavior == null) return WriteRequestWrites.OnDuplicateEnum.Error; + return behavior.Value == OnDuplicateWrites.Error + ? WriteRequestWrites.OnDuplicateEnum.Error + : WriteRequestWrites.OnDuplicateEnum.Ignore; + } + + private static WriteRequestDeletes.OnMissingEnum MapOnMissingDeletes(OnMissingDeletes? behavior) { + if (behavior == null) return WriteRequestDeletes.OnMissingEnum.Error; + return behavior.Value == OnMissingDeletes.Error + ? WriteRequestDeletes.OnMissingEnum.Error + : WriteRequestDeletes.OnMissingEnum.Ignore; + } + /********** * Stores * **********/ @@ -353,10 +367,16 @@ public async Task Write(ClientWriteRequest body, IClientWri AuthorizationModelId = authorizationModelId }; if (body.Writes?.Count > 0) { - requestBody.Writes = new WriteRequestWrites(body.Writes.ConvertAll(key => key.ToTupleKey())); + requestBody.Writes = new WriteRequestWrites( + body.Writes.ConvertAll(key => key.ToTupleKey()), + MapOnDuplicateWrites(options?.Conflict?.OnDuplicateWrites) + ); } if (body.Deletes?.Count > 0) { - requestBody.Deletes = new WriteRequestDeletes(body.Deletes.ConvertAll(key => key.ToTupleKeyWithoutCondition())); + requestBody.Deletes = new WriteRequestDeletes( + body.Deletes.ConvertAll(key => key.ToTupleKeyWithoutCondition()), + MapOnMissingDeletes(options?.Conflict?.OnMissingDeletes) + ); } await api.Write(GetStoreId(options), requestBody, options, cancellationToken); @@ -372,7 +392,12 @@ public async Task Write(ClientWriteRequest body, IClientWri }; } - var clientWriteOpts = new ClientWriteOptions() { StoreId = StoreId, AuthorizationModelId = authorizationModelId, Headers = options?.Headers }; + var clientWriteOpts = new ClientWriteOptions() { + StoreId = GetStoreId(options), + AuthorizationModelId = authorizationModelId, + Headers = options?.Headers, + Conflict = options?.Conflict + }; var writeChunks = body.Writes?.Chunk(maxPerChunk).ToList() ?? new List(); var writeResponses = new ConcurrentBag(); diff --git a/src/OpenFga.Sdk/Client/ClientConfiguration.cs b/src/OpenFga.Sdk/Client/ClientConfiguration.cs index 2a91e4f9..dd56e682 100644 --- a/src/OpenFga.Sdk/Client/ClientConfiguration.cs +++ b/src/OpenFga.Sdk/Client/ClientConfiguration.cs @@ -11,6 +11,11 @@ // +using OpenFga.Sdk.Client.Model; +using OpenFga.Sdk.Exceptions; +using System; +using System.Collections.Generic; +using System.Text.RegularExpressions; using OpenFga.Sdk.Client.Model; using OpenFga.Sdk.Exceptions; using System; @@ -93,4 +98,61 @@ public static bool IsWellFormedUlidString(string ulid) { var regex = new Regex("^[0-7][0-9A-HJKMNP-TV-Z]{25}$"); return regex.IsMatch(ulid); } -} \ No newline at end of file + + /// + /// Reserved HTTP headers that should not be overridden via custom headers. + /// Note: User-Agent is intentionally excluded as the SDK sets a default value + /// but allows users to customize it via DefaultHeaders. + /// + private static readonly HashSet ReservedHeaders = new HashSet(StringComparer.OrdinalIgnoreCase) { + "Authorization", + "Content-Type", + "Content-Length", + "Host", + "Accept", + "Accept-Encoding", + "Transfer-Encoding", + "Connection", + "Cookie", + "Set-Cookie", + "Date" + }; + + /// + /// Validates that HTTP headers are safe to use with HTTP requests + /// + /// The headers dictionary to validate + /// The parameter name for exception messages + /// Thrown when headers contain invalid data + internal static void ValidateHeaders(IDictionary? headers, string paramName = "headers") { + if (headers == null) { + return; + } + + foreach (var header in headers) { + if (string.IsNullOrWhiteSpace(header.Key)) { + throw new ArgumentException("Header name cannot be null, empty, or whitespace.", paramName); + } + + if (header.Value == null) { + throw new ArgumentException($"Header '{header.Key}' has a null value. Header values cannot be null.", paramName); + } + + // Prevent HTTP header injection attacks by checking for newline characters + if (header.Value.Contains("\r") || header.Value.Contains("\n")) { + throw new ArgumentException( + $"Header '{header.Key}' contains invalid characters (CR/LF). Header values cannot contain newline characters as this may lead to header injection vulnerabilities.", + paramName); + } + + // Warn about reserved headers that may cause unexpected behavior + if (ReservedHeaders.Contains(header.Key)) { + throw new ArgumentException( + $"Header '{header.Key}' is a reserved HTTP header and should not be set via custom headers. " + + $"Setting this header may cause authentication failures, request corruption, or other unexpected behavior. " + + $"Reserved headers include: {string.Join(", ", ReservedHeaders)}.", + paramName); + } + } + } +} diff --git a/src/OpenFga.Sdk/Client/Model/ClientRequestOptions.cs b/src/OpenFga.Sdk/Client/Model/ClientRequestOptions.cs index 1930a907..0bc337f5 100644 --- a/src/OpenFga.Sdk/Client/Model/ClientRequestOptions.cs +++ b/src/OpenFga.Sdk/Client/Model/ClientRequestOptions.cs @@ -42,4 +42,4 @@ public ClientRequestOptions(IDictionary? headers = default) { /// public IDictionary? Headers { get; set; } -} \ No newline at end of file +} diff --git a/src/OpenFga.Sdk/Client/Model/ClientWriteOptions.cs b/src/OpenFga.Sdk/Client/Model/ClientWriteOptions.cs index eb2865ea..5119a57d 100644 --- a/src/OpenFga.Sdk/Client/Model/ClientWriteOptions.cs +++ b/src/OpenFga.Sdk/Client/Model/ClientWriteOptions.cs @@ -11,10 +11,68 @@ // +using OpenFga.Sdk.Model; using System.Collections.Generic; namespace OpenFga.Sdk.Client.Model; +/// +/// Behavior for handling duplicate tuple writes +/// +public enum OnDuplicateWrites { + /// + /// Return an error when attempting to write a tuple that already exists (default) + /// + Error = 1, + + /// + /// Silently ignore duplicate tuple writes (no-op) + /// + Ignore = 2 +} + +/// +/// Behavior for handling missing tuple deletes +/// +public enum OnMissingDeletes { + /// + /// Return an error when attempting to delete a tuple that doesn't exist (default) + /// + Error = 1, + + /// + /// Silently ignore missing tuple deletes (no-op) + /// + Ignore = 2 +} + +/// +/// ConflictOptions - Controls behavior for duplicate writes and missing deletes +/// +public interface IConflictOptions { + /// + /// Controls behavior when writing a tuple that already exists + /// + OnDuplicateWrites? OnDuplicateWrites { get; set; } + + /// + /// Controls behavior when deleting a tuple that doesn't exist + /// + OnMissingDeletes? OnMissingDeletes { get; set; } +} + +public class ConflictOptions : IConflictOptions { + /// + /// Controls behavior when writing a tuple that already exists + /// + public OnDuplicateWrites? OnDuplicateWrites { get; set; } + + /// + /// Controls behavior when deleting a tuple that doesn't exist + /// + public OnMissingDeletes? OnMissingDeletes { get; set; } +} + /// /// TransactionOpts /// @@ -54,6 +112,7 @@ public class TransactionOptions : ITransactionOpts { public interface IClientWriteOptions : IClientRequestOptionsWithAuthZModelId { ITransactionOpts Transaction { get; set; } + IConflictOptions? Conflict { get; set; } } public class ClientWriteOptions : IClientWriteOptions { @@ -68,6 +127,9 @@ public class ClientWriteOptions : IClientWriteOptions { /// public ITransactionOpts Transaction { get; set; } + /// + public IConflictOptions? Conflict { get; set; } + /// public IDictionary? Headers { get; set; } } \ No newline at end of file diff --git a/src/OpenFga.Sdk/Configuration/Configuration.cs b/src/OpenFga.Sdk/Configuration/Configuration.cs index 384758bf..c7f80ed8 100644 --- a/src/OpenFga.Sdk/Configuration/Configuration.cs +++ b/src/OpenFga.Sdk/Configuration/Configuration.cs @@ -225,4 +225,4 @@ public string BasePath { public TelemetryConfig? Telemetry { get; set; } #endregion Properties -} \ No newline at end of file +} diff --git a/src/OpenFga.Sdk/Model/JsonStringEnumMemberConverter.cs b/src/OpenFga.Sdk/Model/JsonStringEnumMemberConverter.cs index b1b782da..85bff01d 100644 --- a/src/OpenFga.Sdk/Model/JsonStringEnumMemberConverter.cs +++ b/src/OpenFga.Sdk/Model/JsonStringEnumMemberConverter.cs @@ -30,7 +30,7 @@ public class JsonStringEnumMemberConverter : JsonConverter _stringToEnum = new Dictionary(); /// - /// Parsing and converting enum member + /// Parsing and converting enum member /// public JsonStringEnumMemberConverter() { var type = typeof(EnumTemplate); @@ -70,4 +70,4 @@ public override EnumTemplate Read(ref Utf8JsonReader reader, Type typeToConvert, return ((_stringToEnum.TryGetValue(stringValue, out var enumValue)) ? enumValue : default); } -} \ No newline at end of file +}