chore: rename all iterators to a consistent pattern (#2896)

Author: barakmich

pkg/query/README.md

@@ -0,0 +1,104 @@
+# Query Package
+
+The `query` package implements SpiceDB's query plan system for evaluating permissions and relationships. It provides a tree-based iterator architecture for efficient graph traversal and permission checking.
+
+## Overview
+
+Query plans are built from schema definitions and executed to answer three fundamental questions:
+
+1. **Check**: Does a specific subject have access to a resource?
+2. **IterSubjects**: Which subjects have access to a given resource?
+3. **IterResources**: Which resources can a given subject access?
+
+Each iterator in the tree implements these three methods, allowing complex permission queries to be evaluated by composing simple operations.
+
+## Iterator Types
+
+Iterators are organized into several categories based on their role in the query plan:
+
+| Iterator | Description |
+|----------|-------------|
+| **LEAF ITERATORS** | **Data source iterators with no subiterators** |
+| DatastoreIterator | Queries the datastore for stored relationships. The fundamental data source for all queries. |
+| FixedIterator | Contains pre-computed paths. Used in testing and as frontier in recursive queries. |
+| SelfIterator | Produces reflexive relations (object→object). Used for `self` keyword checks. |
+| RecursiveSentinelIterator | Placeholder marking recursion points during tree construction. Replaced at runtime. |
+| | |
+| **UNARY ITERATORS** | **Wrap a single child iterator** |
+| AliasIterator | Rewrites the relation field of paths. Maps computed permissions to their defining relation. |
+| | |
+| **BINARY ITERATORS** | **Combine two child iterators** |
+| ArrowIterator | Graph walk operator (`→`). Chains two iterators for path composition. |
+| IntersectionArrowIterator | Conditional intersection. Implements `all()` semantics - ALL left subjects must satisfy right. |
+| ExclusionIterator | Set difference (`-`). Removes excluded paths from main set. |
+| | |
+| **N-ARY ITERATORS** | **Combine multiple child iterators** |
+| UnionIterator | Logical OR (`\|`). Concatenates results from all children with deduplication. |
+| IntersectionIterator | Logical AND (`&`). Intersects results from all children. |
+| | |
+| **FILTER ITERATORS** | **Apply filtering conditions to results** |
+| CaveatIterator | Evaluates caveat conditions on paths. Filters results based on runtime context. |
+| | |
+| **CONTROL FLOW ITERATORS** | **Manage execution flow and recursion** |
+| RecursiveIterator | Manages recursive schema definitions with and represents the transitive closure operation. |
+
+## Key Concepts
+
+### Iterator Interface
+
+All iterators implement the `Iterator` interface with these core methods:
+
+```go
+type Iterator interface {
+    // Evaluation methods
+    CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (PathSeq, error)
+    IterSubjectsImpl(ctx *Context, resource Object, filterSubjectType ObjectType) (PathSeq, error)
+    IterResourcesImpl(ctx *Context, subject ObjectAndRelation, filterResourceType ObjectType) (PathSeq, error)
+
+    // Tree navigation
+    Clone() Iterator
+    Subiterators() []Iterator
+    ReplaceSubiterators(newSubs []Iterator) (Iterator, error)
+
+    // Metadata
+    ID() string
+    Explain() Explain
+    ResourceType() ([]ObjectType, error)
+    SubjectTypes() ([]ObjectType, error)
+}
+```
+
+### Path Sequences
+
+Results are returned as `PathSeq` (Go 1.23 iterators - `iter.Seq2[Path, error]`), allowing lazy evaluation and streaming of results without materializing entire result sets in memory.
+
+### Context
+
+The `Context` type carries execution state including:
+
+- Datastore reader
+- Optional trace logger for debugging
+- Execution depth tracking
+- Analysis/statistics collection
+
+## Usage Example
+
+```go
+// Build a query plan from schema
+it, err := BuildIteratorFromSchema(schema, "document", "viewer")
+
+// Create execution context
+ctx := NewContext(datastoreReader)
+
+// Execute a check query
+resources := []Object{NewObject("document", "doc1")}
+subject := NewObject("user", "alice").WithEllipses()
+
+pathSeq, err := ctx.Check(it, resources, subject)
+for path, err := range pathSeq {
+    if err != nil {
+        return err
+    }
+    // Process path...
+}
+```

pkg/query/alias.go

@@ -7,20 +7,20 @@ import (
 	"github.com/authzed/spicedb/pkg/datastore/options"
 )
 
-// Alias is an iterator that rewrites the Resource's Relation field of all paths
+// AliasIterator is an iterator that rewrites the Resource's Relation field of all paths
 // streamed from the sub-iterator to a specified alias relation.
-type Alias struct {
+type AliasIterator struct {
 	id       string
 	relation string
 	subIt    Iterator
 }
 
-var _ Iterator = &Alias{}
+var _ Iterator = &AliasIterator{}
 
-// NewAlias creates a new Alias iterator that rewrites paths from the sub-iterator
+// NewAliasIterator creates a new Alias iterator that rewrites paths from the sub-iterator
 // to use the specified relation name.
-func NewAlias(relation string, subIt Iterator) *Alias {
-	return &Alias{
+func NewAliasIterator(relation string, subIt Iterator) *AliasIterator {
+	return &AliasIterator{
 		id:       uuid.NewString(),
 		relation: relation,
 		subIt:    subIt,
@@ -29,7 +29,7 @@ func NewAlias(relation string, subIt Iterator) *Alias {
 
 // maybePrependSelfEdge checks if a self-edge should be added and combines it with the given sequence.
 // A self-edge is added when the resource with the alias relation matches the subject.
-func (a *Alias) maybePrependSelfEdge(resource Object, subSeq PathSeq, shouldAddSelfEdge bool) PathSeq {
+func (a *AliasIterator) maybePrependSelfEdge(resource Object, subSeq PathSeq, shouldAddSelfEdge bool) PathSeq {
 	if !shouldAddSelfEdge {
 		// No self-edge, just rewrite paths from sub-iterator
 		return func(yield func(Path, error) bool) {
@@ -84,7 +84,7 @@ func (a *Alias) maybePrependSelfEdge(resource Object, subSeq PathSeq, shouldAddS
 	return DeduplicatePathSeq(combined)
 }
 
-func (a *Alias) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (PathSeq, error) {
+func (a *AliasIterator) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (PathSeq, error) {
 	// Get relations from sub-iterator
 	subSeq, err := ctx.Check(a.subIt, resources, subject)
 	if err != nil {
@@ -105,7 +105,7 @@ func (a *Alias) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRel
 	return DeduplicatePathSeq(a.maybePrependSelfEdge(Object{}, subSeq, false)), nil
 }
 
-func (a *Alias) IterSubjectsImpl(ctx *Context, resource Object, filterSubjectType ObjectType) (PathSeq, error) {
+func (a *AliasIterator) IterSubjectsImpl(ctx *Context, resource Object, filterSubjectType ObjectType) (PathSeq, error) {
 	subSeq, err := ctx.IterSubjects(a.subIt, resource, filterSubjectType)
 	if err != nil {
 		return nil, err
@@ -125,7 +125,7 @@ func (a *Alias) IterSubjectsImpl(ctx *Context, resource Object, filterSubjectTyp
 // This matches the dispatcher's identity check behavior: if resource#relation appears as
 // a subject anywhere in the datastore (expired or not), and the filter allows it, we
 // include a self-edge in the results.
-func (a *Alias) shouldIncludeSelfEdge(ctx *Context, resource Object, filterSubjectType ObjectType) bool {
+func (a *AliasIterator) shouldIncludeSelfEdge(ctx *Context, resource Object, filterSubjectType ObjectType) bool {
 	// First check: does the filter allow this resource type as a subject?
 	typeMatches := filterSubjectType.Type == "" || filterSubjectType.Type == resource.ObjectType
 	relationMatches := filterSubjectType.Subrelation == "" || filterSubjectType.Subrelation == a.relation
@@ -146,7 +146,7 @@ func (a *Alias) shouldIncludeSelfEdge(ctx *Context, resource Object, filterSubje
 
 // resourceExistsAsSubject queries the datastore to check if the given resource appears
 // as a subject in any relationship, including expired relationships.
-func (a *Alias) resourceExistsAsSubject(ctx *Context, resource Object) (bool, error) {
+func (a *AliasIterator) resourceExistsAsSubject(ctx *Context, resource Object) (bool, error) {
 	filter := datastore.RelationshipsFilter{
 		OptionalSubjectsSelectors: []datastore.SubjectsSelector{{
 			OptionalSubjectType: resource.ObjectType,
@@ -174,7 +174,7 @@ func (a *Alias) resourceExistsAsSubject(ctx *Context, resource Object) (bool, er
 	return false, nil
 }
 
-func (a *Alias) IterResourcesImpl(ctx *Context, subject ObjectAndRelation, filterResourceType ObjectType) (PathSeq, error) {
+func (a *AliasIterator) IterResourcesImpl(ctx *Context, subject ObjectAndRelation, filterResourceType ObjectType) (PathSeq, error) {
 	subSeq, err := ctx.IterResources(a.subIt, subject, filterResourceType)
 	if err != nil {
 		return nil, err
@@ -210,38 +210,38 @@ func (a *Alias) IterResourcesImpl(ctx *Context, subject ObjectAndRelation, filte
 	return a.maybePrependSelfEdge(GetObject(subject), subSeq, shouldAddSelfEdge), nil
 }
 
-func (a *Alias) Clone() Iterator {
-	return &Alias{
+func (a *AliasIterator) Clone() Iterator {
+	return &AliasIterator{
 		id:       uuid.NewString(),
 		relation: a.relation,
 		subIt:    a.subIt.Clone(),
 	}
 }
 
-func (a *Alias) Explain() Explain {
+func (a *AliasIterator) Explain() Explain {
 	return Explain{
 		Name:       "Alias",
 		Info:       "Alias(" + a.relation + ")",
 		SubExplain: []Explain{a.subIt.Explain()},
 	}
 }
 
-func (a *Alias) Subiterators() []Iterator {
+func (a *AliasIterator) Subiterators() []Iterator {
 	return []Iterator{a.subIt}
 }
 
-func (a *Alias) ReplaceSubiterators(newSubs []Iterator) (Iterator, error) {
-	return &Alias{id: uuid.NewString(), relation: a.relation, subIt: newSubs[0]}, nil
+func (a *AliasIterator) ReplaceSubiterators(newSubs []Iterator) (Iterator, error) {
+	return &AliasIterator{id: uuid.NewString(), relation: a.relation, subIt: newSubs[0]}, nil
 }
 
-func (a *Alias) ID() string {
+func (a *AliasIterator) ID() string {
 	return a.id
 }
 
-func (a *Alias) ResourceType() ([]ObjectType, error) {
+func (a *AliasIterator) ResourceType() ([]ObjectType, error) {
 	return a.subIt.ResourceType()
 }
 
-func (a *Alias) SubjectTypes() ([]ObjectType, error) {
+func (a *AliasIterator) SubjectTypes() ([]ObjectType, error) {
 	return a.subIt.SubjectTypes()
 }