engine

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 6, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package engine is the evaluator for the supported Zanzibar subset (this, computedUserset, tupleToUserset, union). vectors.json is the regression floor and model.json is the relations-JSON translation of internal/authz/harness/model.fga.

Index

Constants

View Source
const MaxDepth = 32

MaxDepth is the fail-closed recursion fence.

Variables

View Source
var BaseModel = mustLoadBaseModel()

BaseModel is the platform base authz model (company/company_module/module/system and every other type model.json defines), always loaded — see internal/authz/fragment.Load, which starts every effective-model build from BaseModel and merges active module fragments on top, never the reverse (module fragments may reference base relations; they may never redefine a base type — fragment.go's Load enforces this at merge time, modvalidate's validateFragment enforces the same rule at module-install time).

Functions

func IsBaseType

func IsBaseType(typ string) bool

IsBaseType reports whether typ is one of the platform base model's own object types — used by fragment.Load and modvalidate to refuse a module fragment that declares/redefines a base type, rather than silently letting the fragment's definition shadow (or be shadowed by) the base model's.

Types

type BatchItem

type BatchItem struct {
	ObjType, ObjID, Rel string
}

BatchItem is one (object,relation) pair evaluated for the batch's fixed subject.

type BatchResult

type BatchResult struct {
	Item    BatchItem
	Allowed bool
	Err     error
}

BatchResult is the outcome for one BatchItem, in request order (order is preserved even though evaluation is concurrent — each item's result is written to its own index).

type CheckError

type CheckError struct {
	Code string // UNKNOWN_TYPE | UNKNOWN_RELATION | DEPTH_EXCEEDED
	Msg  string
}

CheckError is a fail-closed evaluation error: unknown type, unknown relation, or recursion past MaxDepth. Never treated as allow by any caller.

func (*CheckError) Error

func (e *CheckError) Error() string

type Engine

type Engine struct {
	Pool  *pgxpool.Pool
	Model Model
}

Engine evaluates checks against a Model over authz.tuple, via a shared *pgxpool.Pool (the concurrent batchCan needs a pool with max conns >= 10, one pool shared by the worker goroutines).

func (*Engine) BatchCan

func (en *Engine) BatchCan(ctx context.Context, subjType, subjID string, items []BatchItem) []BatchResult

BatchCan evaluates every item against the SAME subject, concurrently across batchWorkers goroutines, sharing one syncMapMemo across the whole batch. Results are returned in the same order as items.

func (*Engine) Check

func (en *Engine) Check(ctx context.Context, objType, objID, rel, subjType, subjID string) (bool, error)

Check answers whether (subjType,subjID) has relation `rel` to (objType,objID). Fresh memo per call — see evalCtx doc.

type Expr

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

Expr is a relation-definition expression restricted to the supported subset. Any other OpenFGA construct (intersection, exclusion, wildcard, condition, ...) is rejected at json.Unmarshal time — the subset wall.

func (Expr) ComputedUsersetRel

func (e Expr) ComputedUsersetRel() string

ComputedUsersetRel returns the target relation name for a `computedUserset` leaf, or "" if e is not one.

func (Expr) IsThis

func (e Expr) IsThis() bool

IsThis reports whether e is a `this` leaf.

func (Expr) TupleToUsersetExpr

func (e Expr) TupleToUsersetExpr() *TupleToUserset

TupleToUsersetExpr returns the `tupleToUserset` payload, or nil if e is not one.

func (Expr) UnionChildren

func (e Expr) UnionChildren() []Expr

UnionChildren returns the `union` children, or nil if e is not one.

func (*Expr) UnmarshalJSON

func (e *Expr) UnmarshalJSON(data []byte) error

UnmarshalJSON enforces the subset wall: a relation expression object must carry exactly one recognized key. Any other key (including known-outside-subset names like "intersection", "exclusion", "wildcard", "condition") is rejected with the offending key named in the error, fail-closed.

type Model

type Model map[string]map[string]Expr

Model is object type -> relation name -> definition expression. Hand-translated from internal/authz/harness/model.fga into the module fragment "relations" JSON shape.

func LoadModel

func LoadModel(data []byte) (Model, error)

LoadModel parses and validates a model.json document. Validation beyond the per-expression subset wall (enforced during Unmarshal): every computedUserset target and every tupleToUserset.tupleset target must name a relation that exists on the SAME object type (both are same-object references — computedUserset always re-evaluates the current object; a tupleset is a relation on the current object holding parent/child refs). tupleToUserset's computedUserset half names a relation on whatever type the tupleset tuples happen to point at, which is only known at eval time from the tuple rows themselves — checked there, fail-closed on lookup miss (unknown type/relation).

func (Model) Merge

func (m Model) Merge(other Model) (Model, error)

Merge returns a new Model containing the receiver's types plus every type from other. A type declared on both sides is an error: two module fragments declaring one object type would otherwise resolve last-wins by row order, so the effective model could flip between loads. Callers name the offending modules.

func (Model) ValidateCompanyModuleAnchor

func (m Model) ValidateCompanyModuleAnchor() error

ValidateCompanyModuleAnchor enforces the module-contract rule every FRAGMENT model must meet (run on the fragment alone, never on the merged model — base types carry no anchor): each declared object type defines `company_module` as a direct (`{"this": true}`) relation. The decision layer binds every company-scope object check to the request's company through that relation, so a type without it could never be checked at all.

func (Model) ValidateTupleToUsersetTargets

func (m Model) ValidateTupleToUsersetTargets() error

ValidateTupleToUsersetTargets is the cross-type half LoadModel cannot do on a fragment alone: every tupleToUserset.computedUserset in m must name a relation defined on at least one type of m (the tupleset's tuples can only ever point at types in the effective model). Callers run it on the EFFECTIVE model (base + fragment) — internal/modvalidate at install time and internal/authz/fragment.Load after merge — so a fragment referencing e.g. `company_module#member` fails loudly there instead of as UNKNOWN_RELATION at eval time.

type TupleToUserset

type TupleToUserset struct {
	Tupleset        string `json:"tupleset"`
	ComputedUserset string `json:"computedUserset"`
}

TupleToUserset is the `X from tupleset` construct: for every tuple (obj, Tupleset, X), resolve check(X, ComputedUserset, subject).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL