caveats

package
v1.57.1 Latest Latest
Warning

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

 Go to latest Published: Nov 10, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Overview

Package caveats contains code to evaluate a caveat with a given context.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func And added in v1.15.0 

func And(first *core.CaveatExpression, second *core.CaveatExpression) *core.CaveatExpression

And `&&`'s together two caveat expressions. If one expression is nil, the other is returned.

func BuildDebugInformation added in v1.35.0 

func BuildDebugInformation(exprResult ExpressionResult) (string, *structpb.Struct, error)

BuildDebugInformation returns a human-readable string representation of the given ExpressionResult and a Struct representation of the context values used in the expression.

func CaveatAsExpr added in v1.15.0 

func CaveatAsExpr(caveat *core.ContextualizedCaveat) *core.CaveatExpression

CaveatAsExpr wraps a contextualized caveat into a caveat expression.

func CaveatExprForTesting added in v1.15.0 

func CaveatExprForTesting(name string) *core.CaveatExpression

CaveatExprForTesting returns a CaveatExpression referencing a caveat with the given name and empty context.

func CaveatForTesting added in v1.15.0 

func CaveatForTesting(name string) *core.ContextualizedCaveat

CaveatForTesting returns a new ContextualizedCaveat for testing, with empty context.

func Invert added in v1.15.0 

func Invert(ce *core.CaveatExpression) *core.CaveatExpression

Invert returns the caveat expression with a `!` placed in front of it. If the expression is nil, returns nil.

func MustCaveatExprForTestingWithContext added in v1.35.0 

func MustCaveatExprForTestingWithContext(name string, context map[string]any) *core.CaveatExpression

MustCaveatExprForTestingWithContext returns a CaveatExpression referencing a caveat with the given name and given context.

func Or added in v1.15.0 

func Or(first *core.CaveatExpression, second *core.CaveatExpression) *core.CaveatExpression

Or `||`'s together two caveat expressions. If one expression is nil, the other is returned.

func ShortcircuitedOr added in v1.15.0 

func ShortcircuitedOr(first *core.CaveatExpression, second *core.CaveatExpression) *core.CaveatExpression

ShortcircuitedOr combines two caveat expressions via an `||`. If one of the expressions is nil, then the entire expression is *short-circuited*, and a nil is returned.

func Subtract added in v1.15.0 

func Subtract(caveat *core.CaveatExpression, subtracted *core.CaveatExpression) *core.CaveatExpression

Subtract returns a caveat expression representing the subtracted expression subtracted from the given expression.

Types

type CaveatDefinitionLookup added in v1.49.2 

type CaveatDefinitionLookup interface {
	LookupCaveatDefinitionsByNames(ctx context.Context, names []string) (map[string]datastore.CaveatDefinition, error)
}

CaveatDefinitionLookup is an interface for looking up caveat definitions by name. datalayer.SchemaReader satisfies this interface.

type CaveatRunner added in v1.40.0 

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

CaveatRunner is a helper for running caveats, providing a cache for deserialized caveats.

func NewCaveatRunner added in v1.40.0 

func NewCaveatRunner(ts *caveattypes.TypeSet) *CaveatRunner

NewCaveatRunner creates a new CaveatRunner.

func (*CaveatRunner) PopulateCaveatDefinitionsForExpr added in v1.40.0 

func (cr *CaveatRunner) PopulateCaveatDefinitionsForExpr(ctx context.Context, expr *core.CaveatExpression, reader CaveatDefinitionLookup) error

PopulateCaveatDefinitionsForExpr populates the CaveatRunner's cache with the definitions referenced in the given caveat expression.

func (*CaveatRunner) RunCaveatExpression added in v1.40.0 

func (cr *CaveatRunner) RunCaveatExpression(
	ctx context.Context,
	expr *core.CaveatExpression,
	context map[string]any,
	reader CaveatDefinitionLookup,
	debugOption RunCaveatExpressionDebugOption,
) (ExpressionResult, error)

RunCaveatExpression runs a caveat expression over the given context and returns the result.

type CompiledCaveatCache added in v1.55.0 

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

CompiledCaveatCache caches deserialized caveats (which embed a built CEL environment) by caveat name, for a single schema version. Deserializing a caveat rebuilds its CEL environment, which is expensive; caching it on the (shared) stored schema avoids paying that cost on every check.

func CompiledCaveatCacheFor added in v1.55.0 

func CompiledCaveatCacheFor(s *datastore.ReadOnlyStoredSchema) (*CompiledCaveatCache, error)

CompiledCaveatCacheFor returns the compiled-caveat cache tied to the given stored schema, building it lazily on first access.

func (*CompiledCaveatCache) GetOrCompile added in v1.55.0 

func (c *CompiledCaveatCache) GetOrCompile(name string, compile func() (*caveats.CompiledCaveat, error)) (*caveats.CompiledCaveat, error)

GetOrCompile returns the cached compiled caveat for name, or invokes compile and caches the result. compile is only called on a miss; concurrent misses may call compile more than once but only one result is retained.

type Condition added in v1.57.0 

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

Condition is a canonical, order-independent representation of a caveat expression as a disjunctive normal form (DNF): an OR of conjuncts, where each conjunct is an AND of atoms. It exists so that recursive traversals can decide whether a newly-discovered path *weakens* the condition under which an object is reachable — the termination guarantee of the semi-naive fixpoint.

Two properties make that guarantee hold:

  • AND is idempotent and commutative: c1 ∧ c2 ∧ c1 collapses to {c1, c2}, so the set of distinct conjuncts is finite.
  • ⊤ (unconditional) is absorbing under OR: once an object is reachable unconditionally, no further path can weaken it.

The zero value is the "false" condition (no disjuncts); use Unconditional() for the unconditional condition and FromExpression to derive one from a caveat.

func FromExpression added in v1.57.0 

func FromExpression(expr *core.CaveatExpression) Condition

FromExpression converts a caveat expression into its canonical DNF. A nil expression is unconditional and yields Unconditional().

func Unconditional added in v1.57.0 

func Unconditional() Condition

Unconditional returns the unconditional (always-true) condition.

func (Condition) And added in v1.57.0 

func (c Condition) And(other Condition) Condition

And returns the canonical conjunction of the two conditions.

func (Condition) Disjuncts added in v1.57.0 

func (c Condition) Disjuncts() int

Disjuncts returns the number of DNF disjuncts (0 for unconditional or false).

func (Condition) Expression added in v1.57.0 

func (c Condition) Expression() *core.CaveatExpression

Expression rebuilds a caveat expression equivalent to this condition. Unconditional() (and the degenerate false condition) yield nil.

func (Condition) IsUnconditional added in v1.57.0 

func (c Condition) IsUnconditional() bool

IsUnconditional reports whether the condition is unconditional.

func (Condition) Or added in v1.57.0 

func (c Condition) Or(other Condition) (Condition, bool)

Or returns the canonical disjunction of the two conditions, and reports whether the result differs from the receiver — i.e. whether other *weakened* c.

func (Condition) String added in v1.57.0 

func (c Condition) String() string

String returns a deterministic, human-readable rendering of the DNF.

type EvaluationError added in v1.39.0 

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

EvaluationError is an error in evaluation of a caveat expression.

func NewEvaluationError added in v1.39.0 

func NewEvaluationError(caveatExpr *core.CaveatExpression, err caveats.EvaluationError) EvaluationError

func (EvaluationError) DetailsMetadata added in v1.39.0 

func (err EvaluationError) DetailsMetadata() map[string]string

DetailsMetadata returns the metadata for details for this error.

func (EvaluationError) GRPCStatus added in v1.39.0 

func (err EvaluationError) GRPCStatus() *status.Status

func (EvaluationError) MarshalZerologObject added in v1.39.0 

func (err EvaluationError) MarshalZerologObject(e *zerolog.Event)

MarshalZerologObject implements zerolog.LogObjectMarshaler

type ExpressionResult added in v1.15.0 

type ExpressionResult interface {
	// Value is the resolved value for the expression. For partially applied expressions, this value will be false.
	Value() bool

	// IsPartial returns whether the expression was only partially applied.
	IsPartial() bool

	// MissingVarNames returns the names of the parameters missing from the context.
	MissingVarNames() ([]string, error)
}

ExpressionResult is the result of a caveat expression being run. See also caveats.CaveatResult

func RunSingleCaveatExpression added in v1.40.0 

func RunSingleCaveatExpression(
	ctx context.Context,
	ts *caveattypes.TypeSet,
	expr *core.CaveatExpression,
	context map[string]any,
	reader CaveatDefinitionLookup,
	debugOption RunCaveatExpressionDebugOption,
) (ExpressionResult, error)

RunSingleCaveatExpression runs a caveat expression over the given context and returns the result. This instantiates its own CaveatRunner, and should therefore only be used in one-off situations.

type ParameterTypeError added in v1.16.2 

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

ParameterTypeError is a type error in constructing a parameter from a value.

func NewParameterTypeError added in v1.16.2 

func NewParameterTypeError(caveatExpr *core.CaveatExpression, err error) ParameterTypeError

func (ParameterTypeError) DetailsMetadata added in v1.16.2 

func (err ParameterTypeError) DetailsMetadata() map[string]string

DetailsMetadata returns the metadata for details for this error.

func (ParameterTypeError) GRPCStatus added in v1.16.2 

func (err ParameterTypeError) GRPCStatus() *status.Status

func (ParameterTypeError) MarshalZerologObject added in v1.16.2 

func (err ParameterTypeError) MarshalZerologObject(e *zerolog.Event)

MarshalZerologObject implements zerolog.LogObjectMarshaler

type RunCaveatExpressionDebugOption added in v1.15.0 

type RunCaveatExpressionDebugOption int

RunCaveatExpressionDebugOption are the options for running caveat expression evaluation with debugging enabled or disabled. 

const (
	// RunCaveatExpressionNoDebugging runs the evaluation without debugging enabled.
	RunCaveatExpressionNoDebugging RunCaveatExpressionDebugOption = 0

	// RunCaveatExpressionWithDebugInformation runs the evaluation with debugging enabled.
	RunCaveatExpressionWithDebugInformation RunCaveatExpressionDebugOption = 1
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.