docs: add documentation on Check algorithm #1360
Conversation
docs/check/overview.md
Outdated
|
|
||
| * **Subproblem** - an FGA query that is contingent on one or more evaluations of nested relationship evaluations (including itself). | ||
|
|
||
| * **Dispatch** - refers to the process of evaluating a nested subproblem in order to resolve some parent subproblem. |
There was a problem hiding this comment.
| * **Dispatch** - refers to the process of evaluating a nested subproblem in order to resolve some parent subproblem. | |
| * **Dispatch** - refers to the process of evaluating a nested subproblem in order to resolve one or more parent subproblems. |
i don't see a significant difference between expansion and dispatch's definitions. Suggest removing one of them and using one of both terms everywhere in this doc. And if you pick expand i suggest explaining in this doc the difference between Check API and Expand API
There was a problem hiding this comment.
The term "expansion" in the scope of this Check doc is not to be confused with the Expand API. I've added some more text that hopefully clarifies the distinction when it comes to the semantics of how we use the term "expand" vs "dispatch" when we talk about FGA queries. Let me know what you think with the updates 👍
docs/check/overview.md
Outdated
|
|
||
| > ℹ️ The term "permission" is used above, but from here forward we will formally refer to permissions simply as relationships. A users/subject has a permission if they have the relationship, and a relationship can be realized through one or more relationship rewrites. | ||
|
|
||
| ### Direct Relationships |
There was a problem hiding this comment.
| ### Direct Relationships | |
| ### Model with Direct Relationships. Example Check |
here and elsewhere. I skipped through all these thinking that they were going to explain what these terms meant, only to realize that these actually have examples of Check resolutions :)
There was a problem hiding this comment.
We do explain the term "Direct Relationships" below. Specifically, we say
If a relation can be directly assigned or given/shared with a specific user/subject, then we refer to it as a "direct relationship". Direct relationships are any of those relationships that, for a particular authorization model, can be written to an FGA Store using the Write API.
The content of the doc is organized by rewrite rule categories. There are 2 categories - direct rewrite rules and set rewrite rules. The set rewrite rules compose other set rewrite rules and/or direct rewrite rules. Self (e.g. direct relationships), computed userset, and TTU encompass the direct rewrite rules. Union, intersection, and exclusion encompass the set rewrite rules.
The purpose of this section was to a) outline the direct rewrite rules and what they do, specifically in this subsection for direct relationships and b) provide examples of them. I feel like the content as is adequately portrays the intent.
There was a problem hiding this comment.
Just starting to work on this doc. I'd rename this from overview.md to README.md as Github directly opens files named README when we enter the folder as shown here - https://github.com/openfga/openfga/tree/concurrency-controls-in-check-docs/docs/check
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #1360 +/- ##
==========================================
+ Coverage 86.20% 86.23% +0.03%
==========================================
Files 87 87
Lines 8259 8259
==========================================
+ Hits 7119 7121 +2
+ Misses 805 804 -1
+ Partials 335 334 -1 ☔ View full report in Codecov by Sentry. |
Description
This adds some documentation to our
docsthat describes how the internal Check resolution algorithm works inside of theinternal/graphpackage.References
Review Checklist
main