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
- Variables
- func IsBaseType(typ string) bool
- type BatchItem
- type BatchResult
- type CheckError
- type Engine
- func (en *Engine) BatchCan(ctx context.Context, subjType, subjID string, items []BatchItem) []BatchResult
- func (en *Engine) Check(ctx context.Context, objType, objID, rel, subjType, subjID string) (bool, error)
- func (en *Engine) CheckInCompany(ctx context.Context, objType, objID, rel, subjType, subjID, companyID string) (bool, error)
- type Expr
- type Model
- type TupleToUserset
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.
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 ¶
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).