engine

package
v0.1.4 Latest Latest
Warning

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

Go to latest
Published: Oct 21, 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.

func (*Engine) CheckInCompany added in v0.1.3

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

CheckInCompany is Check bound to one company: a position, group or member userset met while expanding resolves only if it belongs to companyID. A tuple that names another company's position as viewer of this company's object therefore grants nothing here, however the tuple got written. An empty companyID is plain Check.

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