Add Duplicate Writes documentation #1105
Conversation
- Create new duplicate-writes.mdx file with comprehensive documentation - Document on_duplicate and on_missing parameters for Write API - Include practical examples showing default vs permissive behavior - Add API parameter reference with CURL examples - Update WriteRequestViewer component to support writeOptions and deleteOptions - Implement pretty-printed JSON formatting in CURL examples - Update transactional-writes.mdx to reference new duplicate writes feature - Add duplicate-writes to sidebar navigation - Document use cases for data synchronization and idempotent operations - Include important concepts about atomicity and race conditions - Add detailed explanations for tuple conditions and conflict scenarios
- Create new duplicate-writes.mdx file with comprehensive documentation - Document on_duplicate and on_missing parameters for Write API - Include practical examples showing default vs permissive behavior - Add API parameter reference with CURL examples - Update WriteRequestViewer component to support writeOptions and deleteOptions - Implement pretty-printed JSON formatting in CURL examples - Update transactional-writes.mdx to reference new duplicate writes feature - Add duplicate-writes to sidebar navigation - Document use cases for data synchronization and idempotent operations - Include important concepts about atomicity and race conditions - Add detailed explanations for tuple conditions and conflict scenarios
- Replace 'any' type with proper RequestBody interface - Use eslint-disable-next-line for unused _description variables - Add proper TypeScript types for request body structure
- Fix error message example to match the actual tuple (writer vs reader)
- Correct relation in first WriteRequestViewer example (writer vs reader)
- Add line break for better formatting in 'Best effort' ignore section
- Update RelatedSection description for clarity
- Fix title in related links (Write API vs {ProductName} API)
- Add new card for Duplicate Writes in the interacting section overview - Position it after Transactional Writes since they are related concepts - Include descriptive text about handling duplicate writes and missing deletes
…ent docs - Delete write-api.mdx, transactional-writes.mdx, and duplicate-writes.mdx - Rename update-tuples.mdx to add-tuples.mdx with enhanced content - Add section 04 for combined write/delete operations in same request - Add section 05 for ignoring duplicate tuples and missing deletes - Update all references throughout documentation to point to add-tuples.mdx - Remove deleted files from sidebar navigation and overview pages - Update README.md, llms.txt, and all cross-references - Ensure clean build with no broken links - Replace document:Z examples with document:123 for consistency
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the WalkthroughRenamed “Update Relationship Tuples” to “Add Relationship Tuples” across docs, added/deepened guidance on atomic writes and duplicate handling, removed the “Transactional Writes” doc and references, updated OpenFGA configuration docs to v1.10.0 with new iterator/planner options, and refactored WriteRequestViewer CLI payload construction with new write/delete options. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant U as User
participant W as WriteRequestViewer
participant C as CLI Payload Builder
participant A as OpenFGA Write API
U->>W: Provide relationshipTuples, deleteRelationshipTuples<br/>+ writeOptions.on_duplicate?<br/>+ deleteOptions.on_missing?<br/>+ authorization_model_id?
W->>C: Build RequestBody { authorization_model_id, writes?, deletes? }
Note over C: Sanitize tuple_keys (drop _description)
C->>C: Include writes.on_duplicate (error|ignore)?<br/>Include deletes.on_missing (error|ignore)?
C-->>W: Pretty-printed JSON payload
W->>A: curl -X POST /stores/.../write -d '{...}'
alt Success
A-->>W: 200 OK
else Conflict/Error
A-->>W: 4xx with details (e.g., 409 on conflicts)
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (17)
docs/content/getting-started/overview.mdx (1)
49-52: Rename card title to match the new guide.The link was updated to add-tuples, but the card title still says “Update Relationship Tuples”. Align the title for consistency.
- title: 'Update Relationship Tuples', + title: 'Add Relationship Tuples',docs/content/getting-started/perform-check.mdx (1)
39-41: Wording nit: “updated” vs “added”.Consider aligning with the new page name: “…and added the relationship tuples…”.
-3. You have [configured the _authorization model_](./configure-model.mdx) and [updated the _relationship tuples_](./add-tuples.mdx). +3. You have [configured the _authorization model_](./configure-model.mdx) and [added the _relationship tuples_](./add-tuples.mdx).docs/content/getting-started/perform-list-objects.mdx (1)
111-112: Minor copy fixes for clarity and consistency.
- Line 111: remove double space after “that”.
- Line 115: say “List Objects API” (not “check API”).
- Line 157: capitalize “List Objects”.
- Assume that you want to list all objects of type document that user `anne` ... + Assume that you want to list all objects of type document that user `anne` ... -Before calling the check API, you will need to configure the API client. +Before calling the List Objects API, you will need to configure the API client. -### 02. Calling list objects API +### 02. Calling List Objects APIAlso applies to: 115-116, 157-159
src/components/Docs/SnippetViewer/WriteRequestViewer.tsx (3)
68-80: Tighten RequestBody types and deletes tuple_key type.
- Type on_duplicate/on_missing as a specific union.
- Match deletes.tuple_keys to RelationshipTupleWithoutCondition.
- interface RequestBody { - writes?: { - tuple_keys: Array<Omit<RelationshipTuple, '_description'>>; - on_duplicate?: string; - }; - deletes?: { - tuple_keys: Array<Omit<RelationshipTuple, '_description'>>; - on_missing?: string; - }; - authorization_model_id?: string; - } + type OnDuplicate = 'error' | 'ignore'; + type OnMissing = 'error' | 'ignore'; + interface RequestBody { + writes?: { + tuple_keys: Array<Omit<RelationshipTuple, '_description'>>; + on_duplicate?: OnDuplicate; + }; + deletes?: { + tuple_keys: Array<Omit<RelationshipTupleWithoutCondition, '_description'>>; + on_missing?: OnMissing; + }; + authorization_model_id?: string; + }
114-118: Safer cURL payload quoting.Single-quoting JSON can break when tuple values contain apostrophes. Prefer a heredoc or @-.
- -d '${prettyJson}'`; + --data @- <<'JSON' +${prettyJson} +JSON`;
40-66: CLI doesn't support a single transactional /write (writes+deletes) or on_duplicate/on_missing — use Write API/SDK or document the limitationThe OpenFGA Write API supports combined transactional writes+deletes and on_* options, but the CLI only exposes per-tuple
fga tuple write/fga tuple deleteand cannot emit an arbitrary writes+deletes JSON body.
- Either replace the CLI snippet with a direct POST example (curl or SDK) to /stores/{store_id}/write that mirrors the cURL body, or explicitly document that the CLI snippet only shows per-tuple commands and cannot express on_duplicate/on_missing.
- Location: src/components/Docs/SnippetViewer/WriteRequestViewer.tsx (lines 40–66)
docs/content/getting-started/setup-openfga/configuration.mdx (1)
191-197: Call out “new in v1.10.0” for newly added options.Consider marking new options (secondary datastore, iterator caches, planner) with a short “New in v1.10.0” note to aid upgraders.
Also applies to: 202-207, 137-141
docs/content/getting-started/add-tuples.mdx (3)
204-214: Fix article grammar (“an editor”, “a reader”).User-facing polish.
-... remove `user:anne` as a `editor` ... updating `user:anne` as an `reader` ... +... remove `user:anne` as an `editor` ... updating `user:anne` as a `reader` ...
90-91: Tighten phrasing of the scenario sentence.Minor clarity improvement.
-Assume that you want to add user `user:anne` to have relationship `reader` with object `document:123` +Assume you want to add a tuple granting `user:anne` the `reader` relationship to `document:123`.
235-236: End sentence with a period.Small punctuation fix.
-This approach ensures that both operations succeed or fail together, maintaining transactional data consistency +This approach ensures that both operations succeed or fail together, maintaining transactional data consistency.docs/content/interacting/managing-user-access.mdx (1)
146-150: Align link text with renamed guide.Card still says “How to update relationship tuples” but now links to “Add Relationship Tuples”.
- title: 'How to update relationship tuples', - description: 'Learn about how to update relationship tuples in SDK.', + title: 'How to add relationship tuples', + description: 'Learn how to add and delete relationship tuples with the SDK and API.', link: '../getting-started/add-tuples', id: '../getting-started/add-tuples',docs/content/getting-started/perform-list-users.mdx (6)
38-39: Match wording with the new guide name.Replace “updated the relationship tuples” with “added the relationship tuples” (or “added/deleted”), per the rename.
-3. You have [configured the _authorization model_](./configure-model.mdx) and [updated the _relationship tuples_](./add-tuples.mdx). +3. You have [configured the _authorization model_](./configure-model.mdx) and [added the _relationship tuples_](./add-tuples.mdx).
47-48: Same phrasing tweak for GO tab.-3. You have [configured the _authorization model_](./configure-model.mdx) and [updated the _relationship tuples_](./add-tuples.mdx). +3. You have [configured the _authorization model_](./configure-model.mdx) and [added the _relationship tuples_](./add-tuples.mdx).
56-57: Same phrasing tweak for .NET tab.-3. You have [configured the _authorization model_](./configure-model.mdx) and [updated the _relationship tuples_](./add-tuples.mdx). +3. You have [configured the _authorization model_](./configure-model.mdx) and [added the _relationship tuples_](./add-tuples.mdx).
65-66: Same phrasing tweak for Python tab.-3. You have [configured the _authorization model_](./configure-model.mdx) and [updated the _relationship tuples_](./add-tuples.mdx). +3. You have [configured the _authorization model_](./configure-model.mdx) and [added the _relationship tuples_](./add-tuples.mdx).
74-75: Same phrasing tweak for Java tab.-3. You have [configured the _authorization model_](./configure-model.mdx) and [updated the _relationship tuples_](./add-tuples.mdx). +3. You have [configured the _authorization model_](./configure-model.mdx) and [added the _relationship tuples_](./add-tuples.mdx).
90-91: Same phrasing tweak for cURL tab.-2. You have [configured the _authorization model_](./configure-model.mdx) and [updated the _relationship tuples_](./add-tuples.mdx). +2. You have [configured the _authorization model_](./configure-model.mdx) and [added the _relationship tuples_](./add-tuples.mdx).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (17)
docs/README.md(0 hunks)docs/content/getting-started/add-tuples.mdx(7 hunks)docs/content/getting-started/framework.mdx(2 hunks)docs/content/getting-started/overview.mdx(1 hunks)docs/content/getting-started/perform-check.mdx(6 hunks)docs/content/getting-started/perform-list-objects.mdx(6 hunks)docs/content/getting-started/perform-list-users.mdx(6 hunks)docs/content/getting-started/setup-openfga/configuration.mdx(4 hunks)docs/content/getting-started/tuples-api-best-practices.mdx(1 hunks)docs/content/interacting/managing-user-access.mdx(1 hunks)docs/content/interacting/overview.mdx(0 hunks)docs/content/interacting/read-tuple-changes.mdx(2 hunks)docs/content/interacting/transactional-writes.mdx(0 hunks)docs/content/modeling/migrating/migrating-relations.mdx(0 hunks)docs/sidebars.js(1 hunks)src/components/Docs/SnippetViewer/WriteRequestViewer.tsx(2 hunks)static/llms.txt(1 hunks)
💤 Files with no reviewable changes (4)
- docs/content/modeling/migrating/migrating-relations.mdx
- docs/content/interacting/overview.mdx
- docs/README.md
- docs/content/interacting/transactional-writes.mdx
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Run Checks
🔇 Additional comments (11)
static/llms.txt (1)
48-49: LGTM: link text + path updated.The Getting Started entry now points to add-tuples consistently.
docs/content/getting-started/perform-check.mdx (1)
39-41: LGTM: prerequisites now reference add-tuples.All language tabs correctly target getting-started/add-tuples.mdx.
Also applies to: 48-50, 57-59, 66-68, 75-77, 91-93
docs/content/getting-started/perform-list-objects.mdx (1)
37-38: LGTM: prerequisites now reference add-tuples.All language tabs correctly target getting-started/add-tuples.mdx.
Also applies to: 46-47, 55-56, 64-65, 73-74, 89-90
docs/content/getting-started/framework.mdx (1)
35-36: LGTM: references updated to add-tuples.Both JS and Go tabs now point at the consolidated guide.
Also applies to: 44-45
docs/sidebars.js (1)
103-105: LGTM: sidebar item renamed and re-id’d.Matches the new page (content/getting-started/add-tuples). Ensure the overview card title was updated as well (see comment in overview.mdx).
src/components/Docs/SnippetViewer/WriteRequestViewer.tsx (1)
28-34: Expose and validate new writeOptions/deleteOptions where usedWriteRequestViewer defines these options in src/components/Docs/SnippetViewer/WriteRequestViewer.tsx (exported from src/components/Docs/SnippetViewer/index.ts), but there are no call sites passing writeOptions or deleteOptions. Update consumers to accept/plumb and validate these options, and add documentation to the add-tuples page.
docs/content/getting-started/setup-openfga/configuration.mdx (2)
119-119: Confirm default change for resolveNodeBreadthLimit — verified (default = 10).
OpenFGA v1.10.0 docs/changelog confirm default is 10.
104-104: No change — v1.10.0 pin and schema link are correctv1.10.0 is the latest OpenFGA release (released 2025-09-11); the docs' tag-specific raw URL to .config-schema.json matches the release and is appropriate.
docs/content/getting-started/add-tuples.mdx (1)
298-302: Verify API doc anchor resolves in built/deployed API docs. Source contains the link at docs/content/getting-started/add-tuples.mdx:301 and many repo references, but the repository has no built API HTML to confirm the generated anchor. Build the site or check the deployed /api/service page and confirm whether the anchor is "#Relationship%20Tuples/Write" or "#/Relationship%20Tuples/Write" and update the MDX if it differs.docs/content/interacting/read-tuple-changes.mdx (1)
35-36: Cross-link anchor verified — no action required.
Heading "02. Calling write API to add new relationship tuples" exists in docs/content/getting-started/add-tuples.mdx (line 144), so the slug add-tuples.mdx#02-calling-write-api-to-add-new-relationship-tuples is valid for the references (lines 35–36, 43–44, 75–76).docs/content/getting-started/tuples-api-best-practices.mdx (1)
34-35: LGTM on target switch to add-tuples.Reference now points to the consolidated page; consistent with the rest of the PR.
… consistency - Enhanced add-tuples.mdx with sections 04 & 05 covering combined operations and duplicate handling - Fixed relation consistency: changed editor→writer and can_view→reader to match authorization model - Updated README.md to reference add-tuples.mdx instead of update-tuples.mdx - Updated overview.mdx navigation - Fixed perform-check.mdx to use reader relation consistently with configured model - All examples now use document:Z for consistency - Build validation: Clean build with working internal links
tylernix
changed the title
…mentation This removes the OpenFGA v1.10.0 configuration updates to keep this PR focused solely on the tuple management documentation enhancements.
- Enhanced update-config-page.mjs to generate TypeScript constants file - Created src/constants/openfga-config.ts with all OpenFGA config defaults - Added ConfigValue React component for referencing config values in MDX - Updated update-tuples.mdx to use ConfigValue for MAX_TUPLES_PER_WRITE - Ensures documentation stays synchronized with actual OpenFGA configuration schema - Constants are auto-regenerated on each build from latest OpenFGA release
tylernix
changed the title
tylernix
changed the title
|
Split Dynamic config variables into a separate PR #1110 |
|
@aaguiarz @rhamzeh How do we clean up old "dead" links? Currently failing a check |
You don't, just merge it |
|
If you want to clean them up (can be a separate PR):
|
3 participants
Summary
This PR comprehensively enhances the write API documentation by including the new
on_duplicateandon_missingparameters and consolidating the transactional-writes.md document.📝 Enhanced Documentation
on_duplicate: 'ignore'andon_missing: 'ignore'parameterseditor→writerandcan_view→readerthroughout getting-started section🗑️ Removed Files
docs/content/interacting/transactional-writes.mdx(consolidated into update-tuples.mdx)🔗 Fixed References & Consistency
document:Z) and relations (reader,writer)✅ Validation & Quality
npm run build- no broken linksnpm run lint- all code style rules pass💡 Benefits Achieved
🔧 Implementation Details
Summary by CodeRabbit
Enhanced tuple management documentation with combined operations and duplicate handling
Documentation