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 ¶
const MaxDepth = 32
MaxDepth is the fail-closed recursion fence.
Variables ¶
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 ¶
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 ¶
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 ¶
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.
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 ¶
ComputedUsersetRel returns the target relation name for a `computedUserset` leaf, or "" if e is not one.
func (Expr) TupleToUsersetExpr ¶
func (e Expr) TupleToUsersetExpr() *TupleToUserset
TupleToUsersetExpr returns the `tupleToUserset` payload, or nil if e is not one.
func (Expr) UnionChildren ¶
UnionChildren returns the `union` children, or nil if e is not one.
func (*Expr) UnmarshalJSON ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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).