refactor: improve example to demonstrate computed relations

daniel-jonathan · daniel-jonathan · commit 2f4d4264903d · 2025-11-12T21:40:39.000-06:00
- Update authorization model to show owner/viewer/can_read pattern - Write tuples to base relations (owner, viewer) - Query computed relation (can_read = owner OR viewer) - Demonstrates OpenFGA's value: derived permissions from base relations - Update CHANGELOG to be brief with link to README (per @rhamzeh feedback) - Remove OPENFGA_LIST_OBJECTS_DEADLINE from manually-written docs - Clarify no pagination limit vs server timeout in all documentation - Add detailed explanation of computed relations in example README Addresses feedback from @aaguiarz and @SoulPancake: - openfga/js-sdk#280 (comment) - Shows why StreamedListObjects is valuable for computed relations All tests passing. Example builds successfully.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,13 +2,7 @@
 
 ## [Unreleased](https://github.com/openfga/dotnet-sdk/compare/v0.8.0...HEAD)
 
-- feat: add support for [StreamedListObjects](https://openfga.dev/api/service#/Relationship%20Queries/StreamedListObjects)
-  - New `StreamedListObjects` method that returns `IAsyncEnumerable<StreamedListObjectsResponse>`
-  - Streams objects as they are received instead of waiting for complete response
-  - No pagination limits - only constrained by server timeout (OPENFGA_LIST_OBJECTS_DEADLINE)
-  - Supports all ListObjects parameters: authorization model ID, consistency, contextual tuples, context
-  - Proper resource cleanup on early termination and cancellation
-  - See [example](example/StreamedListObjectsExample) for usage
+- feat: add support for [StreamedListObjects](https://openfga.dev/api/service#/Relationship%20Queries/StreamedListObjects). See [documentation](#streamed-list-objects)
 - fix: ApiToken credentials no longer cause reserved header exception (#146)
 
 ## v0.8.0
diff --git a/README.md b/README.md
@@ -786,10 +786,13 @@ var response = await fgaClient.ListObjects(body, options);
 
 ##### Streamed List Objects
 
-The Streamed ListObjects API is very similar to the ListObjects API, with two differences:
+List objects of a particular type that the user has access to, using the streaming API.
 
-1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected.
-2. The number of results returned is only limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE`.
+The Streamed ListObjects API is very similar to the ListObjects API, with two key differences:
+1. **Streaming Results**: Instead of collecting all objects before returning a response, it streams them to the client as they are collected.
+2. **No Pagination Limit**: Returns all results without the 1000-object limit of the standard ListObjects API.
+
+This is particularly useful when querying **computed relations** that may return large result sets.
 
 [API Documentation](https://openfga.dev/api/service#/Relationship%20Queries/StreamedListObjects)
 
diff --git a/example/StreamedListObjectsExample/README.md b/example/StreamedListObjectsExample/README.md
@@ -7,9 +7,9 @@ Demonstrates using `StreamedListObjects` to retrieve objects via the streaming A
 The Streamed ListObjects API is very similar to the ListObjects API, with two key differences:
 
 1. **Streaming Results**: Instead of collecting all objects before returning a response, it streams them to the client as they are collected.
-2. **No Pagination Limit**: The number of results returned is only limited by the execution timeout specified in the flag `OPENFGA_LIST_OBJECTS_DEADLINE`.
+2. **No Pagination Limit**: Returns all results without the 1000-object limit of the standard ListObjects API.
 
-This makes it ideal for scenarios where you need to retrieve large numbers of objects without being constrained by pagination limits.
+This makes it ideal for scenarios where you need to retrieve large numbers of objects, especially when querying computed relations.
 
 ## Prerequisites
 
@@ -30,12 +30,41 @@ dotnet run
 ## What it does
 
 - Creates a temporary store
-- Writes a simple authorization model
-- Adds 2000 tuples
-- Streams results via `StreamedListObjects`
+- Writes an authorization model with **computed relations**
+- Adds 2000 tuples (1000 owners + 1000 viewers)
+- Queries the **computed `can_read` relation** via `StreamedListObjects`
+- Shows all 2000 results (demonstrating computed relations)
 - Shows progress (first 3 objects and every 500th)
 - Cleans up the store
 
+## Authorization Model
+
+The example demonstrates OpenFGA's **computed relations**:
+
+```
+type user
+
+type document
+  relations
+    define owner: [user]
+    define viewer: [user]
+    define can_read: owner or viewer  ← COMPUTED RELATION
+```
+
+**Why this matters:**
+- We write tuples to `owner` and `viewer` (base permissions)
+- We query `can_read` (computed from owner OR viewer)
+- This shows OpenFGA's power: derived permissions from base relations
+- Without OpenFGA, you'd need to duplicate data or run multiple queries
+
+**Example flow:**
+1. Write: `user:anne owner document:1-1000`
+2. Write: `user:anne viewer document:1001-2000`
+3. Query: `StreamedListObjects(user:anne, relation:can_read, type:document)`
+4. Result: All 2000 documents (because `can_read = owner OR viewer`)
+
+This demonstrates why `StreamedListObjects` is valuable - computed relations can return large result sets!
+
 ## Key Features Demonstrated
 
 ### IAsyncEnumerable Pattern
diff --git a/example/StreamedListObjectsExample/StreamedListObjectsExample.cs b/example/StreamedListObjectsExample/StreamedListObjectsExample.cs
@@ -32,19 +32,54 @@ public static async Task Main() {
                         Type = "document",
                         Relations = new Dictionary<string, Userset> {
                             {
-                                "can_read", new Userset {
+                                "owner", new Userset {
+                                    This = new object()
+                                }
+                            },
+                            {
+                                "viewer", new Userset {
                                     This = new object()
                                 }
+                            },
+                            {
+                                "can_read", new Userset {
+                                    Union = new Usersets {
+                                        Child = new List<Userset> {
+                                            new() {
+                                                ComputedUserset = new ObjectRelation {
+                                                    Relation = "owner"
+                                                }
+                                            },
+                                            new() {
+                                                ComputedUserset = new ObjectRelation {
+                                                    Relation = "viewer"
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
                             }
                         },
                         Metadata = new Metadata {
                             Relations = new Dictionary<string, RelationMetadata> {
                                 {
-                                    "can_read", new RelationMetadata {
+                                    "owner", new RelationMetadata {
                                         DirectlyRelatedUserTypes = new List<RelationReference> {
                                             new() { Type = "user" }
                                         }
                                     }
+                                },
+                                {
+                                    "viewer", new RelationMetadata {
+                                        DirectlyRelatedUserTypes = new List<RelationReference> {
+                                            new() { Type = "user" }
+                                        }
+                                    }
+                                },
+                                {
+                                    "can_read", new RelationMetadata {
+                                        DirectlyRelatedUserTypes = new List<RelationReference>()
+                                    }
                                 }
                             }
                         }
@@ -58,24 +93,36 @@ public static async Task Main() {
                 AuthorizationModelId = authModel.AuthorizationModelId
             });
 
-            Console.WriteLine("Writing tuples");
+            Console.WriteLine("Writing tuples (1000 as owner, 1000 as viewer)");
             var tuples = new List<ClientTupleKey>();
-            for (int i = 1; i <= 2000; i++) {
+            
+            // Write 1000 documents where anne is the owner
+            for (int i = 1; i <= 1000; i++) {
+                tuples.Add(new ClientTupleKey {
+                    User = "user:anne",
+                    Relation = "owner",
+                    Object = $"document:{i}"
+                });
+            }
+            
+            // Write 1000 documents where anne is a viewer
+            for (int i = 1001; i <= 2000; i++) {
                 tuples.Add(new ClientTupleKey {
                     User = "user:anne",
-                    Relation = "can_read",
+                    Relation = "viewer",
                     Object = $"document:{i}"
                 });
             }
+            
             await fga.WriteTuples(tuples);
             Console.WriteLine($"Wrote {tuples.Count} tuples");
 
-            Console.WriteLine("Streaming objects...");
+            Console.WriteLine("Streaming objects via computed 'can_read' relation...");
             var count = 0;
             await foreach (var response in fga.StreamedListObjects(
                 new ClientListObjectsRequest {
                     User = "user:anne",
-                    Relation = "can_read",
+                    Relation = "can_read",  // Computed: owner OR viewer
                     Type = "document"
                 },
                 new ClientListObjectsOptions {
diff --git a/src/OpenFga.Sdk/Client/Client.cs b/src/OpenFga.Sdk/Client/Client.cs
@@ -504,9 +504,11 @@ public async Task<ListObjectsResponse> ListObjects(IClientListObjectsRequest bod
     /**
      * StreamedListObjects - Stream all objects of a particular type that the user has a certain relation to (evaluates)
      * 
-     * The Streamed ListObjects API is very similar to the ListObjects API, with two differences:
-     * 1. Instead of collecting all objects before returning a response, it streams them to the client as they are collected.
-     * 2. The number of results returned is only limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE.
+     * The Streamed ListObjects API is very similar to the ListObjects API, with two key differences:
+     * 1. Streaming Results: Instead of collecting all objects before returning a response, it streams them to the client as they are collected.
+     * 2. No Pagination Limit: Returns all results without the 1000-object limit of the standard ListObjects API.
+     * 
+     * This is particularly useful when querying computed relations that may return large result sets.
      * 
      * Returns an async enumerable that yields StreamedListObjectsResponse objects as they are received from the server.
      */
