query

type Alias ¶

type Alias struct {
	// contains filtered or unexported fields
}

Alias is an iterator that rewrites the Resource's Relation field of all relations streamed from the sub-iterator to a specified alias relation.

func NewAlias(relation string, subIt Iterator) *Alias

func (a *Alias) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (a *Alias) Clone() Iterator

func (a *Alias) Explain() Explain

func (a *Alias) IterResourcesImpl(ctx *Context, subject ObjectAndRelation) (RelationSeq, error)

func (a *Alias) IterSubjectsImpl(ctx *Context, resource Object) (RelationSeq, error)

type Arrow ¶

type Arrow struct {
	// contains filtered or unexported fields
}

Arrow is an iterator that represents the set of relations that follow from a walk in the graph.

Ex: `folder->owner` and `left->right`

func NewArrow(left, right Iterator) *Arrow

func (a *Arrow) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (a *Arrow) Clone() Iterator

func (a *Arrow) Explain() Explain

func (a *Arrow) IterResourcesImpl(ctx *Context, subject ObjectAndRelation) (RelationSeq, error)

func (a *Arrow) IterSubjectsImpl(ctx *Context, resource Object) (RelationSeq, error)

type Context ¶

type Context struct {
	context.Context
	Executor  Executor
	Datastore datastore.ReadOnlyDatastore
	Revision  datastore.Revision
}

Context represents a single execution of a query. It is both a standard context.Context and all the query-time specific handles needed to evaluate a query, such as which datastore it is running against.

Context is the concrete type that contains the overall handles, and uses the executor as a strategy for continuing execution.

func (ctx *Context) Check(it Iterator, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (ctx *Context) IterResources(it Iterator, subject ObjectAndRelation) (RelationSeq, error)

func (ctx *Context) IterSubjects(it Iterator, resource Object) (RelationSeq, error)

type Exclusion ¶

type Exclusion struct {
	// contains filtered or unexported fields
}

Exclusion represents the set of relations that are in the mainSet but not in the excluded set. This is equivalent to `permission foo = bar - baz`

func NewExclusion(mainSet, excluded Iterator) *Exclusion

func (e *Exclusion) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (e *Exclusion) Clone() Iterator

func (e *Exclusion) Explain() Explain

func (e *Exclusion) IterResourcesImpl(ctx *Context, subject ObjectAndRelation) (RelationSeq, error)

func (e *Exclusion) IterSubjectsImpl(ctx *Context, resource Object) (RelationSeq, error)

type Executor ¶

type Executor interface {
	// Check tests if, for the underlying set of relationships (which may be a full expression or a basic lookup, depending on the iterator)
	// any of the `resources` are connected to `subject`.
	// Returns the sequence of matching relations, if they exist, at most `len(resources)`.
	Check(ctx *Context, it Iterator, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

	// IterSubjects returns a sequence of all the relations in this set that match the given resource.
	IterSubjects(ctx *Context, it Iterator, resource Object) (RelationSeq, error)

	// IterResources returns a sequence of all the relations in this set that match the given subject.
	IterResources(ctx *Context, it Iterator, subject ObjectAndRelation) (RelationSeq, error)
}

Executor as chooses how to proceed given an iterator -- perhaps in parallel, perhaps by RPC, etc -- and chooses how to process iteration from the subtree. The correctness logic for the results that are generated are up to each iterator, and each iterator may use statistics to choose the best, yet still correct, logical evaluation strategy. The Executor, meanwhile, makes that evaluation happen in the most convienent form, based on its implementation.

type Explain ¶

type Explain struct {
	Info       string
	SubExplain []Explain
}

Explain describes the state of an iterator tree, in a human-readable fashion, with an Info line at each node.

TODO: This can be extended with other interesting stats about the tree.

func (e Explain) IndentString(depth int) string

func (e Explain) String() string

type FaultyIterator ¶

type FaultyIterator struct {
	// contains filtered or unexported fields
}

FaultyIterator is a test helper that simulates iterator errors

func NewFaultyIterator(shouldFailOnCheck, shouldFailOnCollect bool) *FaultyIterator

func (f *FaultyIterator) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (f *FaultyIterator) Clone() Iterator

func (f *FaultyIterator) Explain() Explain

func (f *FaultyIterator) IterResourcesImpl(ctx *Context, subject ObjectAndRelation) (RelationSeq, error)

func (f *FaultyIterator) IterSubjectsImpl(ctx *Context, resource Object) (RelationSeq, error)

type FixedIterator ¶

type FixedIterator struct {
	// contains filtered or unexported fields
}

For example: document->folder->ownerGroup->user -- and we'd like to find all documents (IterResources) that traverse a known folder->ownerGroup relationship

func NewConflictingPermissionsFixedIterator() *FixedIterator

func NewDocumentAccessFixedIterator() *FixedIterator

func NewEmptyFixedIterator() *FixedIterator

func NewFixedIterator(rels ...Relation) *FixedIterator

func NewFolderHierarchyFixedIterator() *FixedIterator

func NewGroupMembershipFixedIterator() *FixedIterator

func NewLargeFixedIterator() *FixedIterator

func NewMultiRoleFixedIterator() *FixedIterator

func NewSingleUserFixedIterator(userID string) *FixedIterator

func (f *FixedIterator) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (f *FixedIterator) Clone() Iterator

func (f *FixedIterator) Explain() Explain

func (f *FixedIterator) IterResourcesImpl(ctx *Context, subject ObjectAndRelation) (RelationSeq, error)

func (f *FixedIterator) IterSubjectsImpl(ctx *Context, resource Object) (RelationSeq, error)

type Intersection ¶

type Intersection struct {
	// contains filtered or unexported fields
}

Intersection the set of relations that are in all of underlying subiterators. This is equivalent to `permission foo = bar & baz`

func NewIntersection() *Intersection

func (i *Intersection) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (i *Intersection) Clone() Iterator

func (i *Intersection) Explain() Explain

func (i *Intersection) IterResourcesImpl(ctx *Context, subject ObjectAndRelation) (RelationSeq, error)

func (i *Intersection) IterSubjectsImpl(ctx *Context, resource Object) (RelationSeq, error)

type Iterator ¶

type Iterator interface {
	Plan

	// Clone does a deep-copy to duplicate the iterator tree at this point.
	Clone() Iterator
}

Iterator is an interface for manipulating iterators to create more query plans.

A Plan is abstract and more limited, and easier to pass around.

An Iterator is what Iterators (even future datastore-specific ones) implement so that optimizations and reorderings and rebalancing can take place.

func BuildIteratorFromSchema(fullSchema *schema.Schema, definitionName string, relationName string) (Iterator, error)

type LocalExecutor ¶

type LocalExecutor struct{}

LocalExecutor is the simplest executor. It simply calls the iterator's implementation directly.

func (l LocalExecutor) Check(ctx *Context, it Iterator, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (l LocalExecutor) IterResources(ctx *Context, it Iterator, subject ObjectAndRelation) (RelationSeq, error)

func (l LocalExecutor) IterSubjects(ctx *Context, it Iterator, resource Object) (RelationSeq, error)

type Object ¶

type Object struct {
	ObjectID   string
	ObjectType string
}

Object represents a single object, without specifying the relation.

func GetObject(oar ObjectAndRelation) Object

func NewObject(objectType, objectID string) Object

func NewObjects(objectType string, objectIDs ...string) []Object

func (o Object) Equals(other Object) bool

func (o Object) WithEllipses() ObjectAndRelation

func (o Object) WithRelation(relation string) ObjectAndRelation

type ObjectAndRelation ¶

type ObjectAndRelation = tuple.ObjectAndRelation

func NewObjectAndRelation(objectID, objectType, relation string) ObjectAndRelation

type Plan ¶

type Plan interface {
	// CheckImpl tests if, for the underlying set of relationships (which may be a full expression or a basic lookup, depending on the iterator)
	// any of the `resourceIDs` are connected to `subjectID`.
	// Returns the sequence of matching relations, if they exist, at most `len(resourceIDs)`.
	CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

	// IterSubjectsImpl returns a sequence of all the relations in this set that match the given resourceID.
	IterSubjectsImpl(ctx *Context, resource Object) (RelationSeq, error)

	// IterResourcesImpl returns a sequence of all the relations in this set that match the given subjectID.
	IterResourcesImpl(ctx *Context, subject ObjectAndRelation) (RelationSeq, error)

	// Explain generates a human-readable tree that describes each iterator and its state.
	Explain() Explain
}

Plan is the external-facing notion of a query plan. These follow the general API for querying anything in the database as well as describing the plan.

type Relation ¶

type Relation = tuple.Relationship

Relation is the basic unit of connection

func CollectAll(seq RelationSeq) ([]Relation, error)

type RelationIterator ¶

type RelationIterator struct {
	// contains filtered or unexported fields
}

RelationIterator is a common leaf iterator. It represents the set of all relationships of the given schema.BaseRelation, ie, relations that have a known resource and subject type and may contain caveats or expiration.

The RelationIterator, being the leaf, generates this set by calling the datastore.

func NewRelationIterator(base *schema.BaseRelation) *RelationIterator

func (r *RelationIterator) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (r *RelationIterator) Clone() Iterator

func (r *RelationIterator) Explain() Explain

func (r *RelationIterator) IterResourcesImpl(ctx *Context, subject ObjectAndRelation) (RelationSeq, error)

func (r *RelationIterator) IterSubjectsImpl(ctx *Context, resource Object) (RelationSeq, error)

type RelationSeq ¶

type RelationSeq iter.Seq2[Relation, error]

RelationSeq is the intermediate iter closure that any of the planning calls return.

type Union ¶

type Union struct {
	// contains filtered or unexported fields
}

Union the set of relations that are in any of underlying subiterators. This is equivalent to `permission foo = bar | baz`

func NewUnion() *Union

func (u *Union) CheckImpl(ctx *Context, resources []Object, subject ObjectAndRelation) (RelationSeq, error)

func (u *Union) Clone() Iterator

func (u *Union) Explain() Explain

func (u *Union) IterResourcesImpl(ctx *Context, subject ObjectAndRelation) (RelationSeq, error)

func (u *Union) IterSubjectsImpl(ctx *Context, resource Object) (RelationSeq, error)