Feat/grouping userset ttus #493

yissellokta · 2025-09-10T18:44:44Z

To simplify graph operations, the system now introduces logical nodes (LogicalUsersetNode, LogicalTTUNode) to group related edges together. 🤝

Previously, multiple direct user assignments or multiple "tuple-to-userset" (TTU) edges were treated individually, which complicated algorithms, especially during algebraic operations.

Now, these new "union" nodes are created dynamically to consolidate multiple edges into a single logical unit, significantly reducing complexity for core processes like Check and ListObjects.

Description

The Challenge: Simplifying Complex Edge Relationships
The previous weighted graph model did not inherently group multiple direct userset assignments or multiple "tuple-to-userset" (TTU) edges, even when they originated from the same definition. This created significant implementation challenges for core algorithms in OpenFGA, especially when performing algebraic operations. Essentially, the system failed to treat multiple direct edges or multiple TTU edges as a single logical union, unnecessarily increasing complexity.

The Solution: Introducing Logical Nodes and Edges
To reduce complexity in the Check, ListObjects, and indexer compilation algorithms, we are introducing two new types of "union" nodes and two corresponding "rewrite" edges. These new structures help group related edges into single, manageable units.

New Node Types:
LogicalUsersetNode: Consolidates multiple direct user assignments.
LogicalTTUNode: Consolidates multiple TTU edges that belong to the same definition.

New Edge Types:
DirectLogicalEdge: A rewrite edge connecting to a LogicalUsersetNode.
TTULogicalEdge: A rewrite edge connecting to a LogicalTTUNode.

How It Works: Creation Logic
These new logical nodes are created dynamically under specific conditions:

A LogicalUsersetNode is created when an algebraic operation involves more than one direct edge. All relevant direct edges are then extracted and connected to this new logical node.

A LogicalTTUNode is created when an algebraic operation involves more than one TTU edge from the same definition. These TTU edges are then extracted and grouped under the new logical node.

What problem is being solved?

References

Review Checklist

I have clicked on "allow edits by maintainers".
I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
The correct base branch is being used, if not main
I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

New Features
- Introduces logical grouping nodes for userset and tuple-to-userset relations, yielding clearer intermediate structure in graphs.
- Adds logical edge types to represent these groupings.
- Graphs may display additional intermediate nodes/edges where multiple relations are grouped.
Refactor
- Unifies handling of unions, cycles, and weight assignment across logical operators for consistent behavior.
- Error messages updated to reference logical userset/TTU scenarios.
Tests
- Updated and expanded tests to validate new logical nodes and adjusted graph sizes and structures.

coderabbitai · 2025-09-10T18:44:53Z

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Adds new logical node and edge types, updates weighted-graph algorithms to treat them as logical/union operators, and modifies the builder to insert grouping nodes (LogicalUserset, LogicalTTU) that consolidate multiple related edges. Tests are updated to reflect new intermediate nodes, edge routing, and revised error messages.

Changes

Cohort / File(s)	Summary
Edge types `pkg/go/graph/graph_edge.go`	Adds DirectLogicalEdge (4) and TTULogicalEdge (5) to EdgeType. Attributes() unchanged; new types fall through to default.
Node types `pkg/go/graph/graph_node.go`	Adds LogicalUserset (4) and LogicalTTU (5) to NodeType; comments/examples added.
Weighted graph algorithms `pkg/go/graph/weighted_graph.go`	Introduces isLogicalOperator and isLogicalUnionOperator; updates AssignWeights and cycle/union checks to use them. Reworks calculateNodeWeightWithMixedStrategy (requires exactly two edges, merge by max). Simplifies calculateNodeWeightWithEnforceTypeStrategy to derive/prune rewrite weights from edges. Updates validation to permit logical unions.
Graph builder (grouping nodes) `pkg/go/graph/weighted_graph_builder.go`	Adds LogicalTTU and LogicalUserset grouping nodes when multiple related entries exist. Routes parent→group via TTULogicalEdge/DirectLogicalEdge; downstream edges originate from grouping node. Adjusts HasEdge/UpsertEdge sources and labels accordingly.
Tests `pkg/go/graph/weighted_graph_builder_test.go`	Updates expectations: additional nodes/edges due to LogicalUserset; verifies presence and outgoing edges from logical nodes; adjusts error assertions and model formatting.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant P as Parent Node
  participant B as Builder
  participant LU as LogicalUserset (group)
  participant LT as LogicalTTU (group)
  participant C as Child Nodes

  rect rgba(90,120,180,0.08)
  note over B: Direct relation grouping
  B->>B: Detect multiple directlyRelated entries
  B->>LU: Create LogicalUserset node
  P-->>LU: Upsert DirectLogicalEdge
  LU-->>C: Upsert DirectEdge to each target
  end

  rect rgba(120,90,180,0.08)
  note over B: TTU relation grouping
  B->>B: Detect multiple type tupleset relations
  B->>LT: Create LogicalTTU node
  P-->>LT: Upsert TTULogicalEdge (labeled by tupleset relation)
  LT-->>C: Upsert TTUEdge to each target
  end

sequenceDiagram
  autonumber
  participant WG as WeightedGraph
  participant N as Node
  participant E as Edges

  rect rgba(90,180,120,0.08)
  note over WG: AssignWeights / traversal
  WG->>N: Visit node
  alt isLogicalOperator(N)
    WG-->>N: Defer weight assignment
  else
    WG->>E: calculateNodeWeightFromTheEdges
    alt isLogicalUnionOperator(N)
      WG-->>N: Union-based cycle/weight handling
    else
      WG-->>N: Standard edge-based weights
    end
  end
  end

  rect rgba(180,140,90,0.08)
  note over WG: Strategies
  WG->>N: MixedStrategy
  N->>E: Require exactly two edges
  E-->>N: Merge weights by key (max)

  WG->>N: EnforceTypeStrategy
  E-->>N: Derive rewriteWeights from common keys across edges
  WG-->>N: Assign pruned rewriteWeights
  end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

Differentiating "recursive" cycles from tuple cycles #454 — Also changes weight assignment and cycle detection, introducing recursive-vs-tuple cycle metadata; overlaps conceptually with expanded logical operator handling.
Fix: correctly assign weights for intersections with multiple direct types #455 — Modifies calculateNodeWeightWithEnforceTypeStrategy, similar area affected by this PR’s rewrite/pruning approach.