Documentation
¶
Overview ¶
Package celx provides utilities for working with CEL (Common Expression Language) expressions, including environment creation, expression compilation, evaluation, and conversion between CEL values and JSON-compatible types.
Index ¶
- Constants
- Variables
- func BoolResult(val ref.Val) (bool, error)
- func NewEnv(cfg EnvConfig, vars ...cel.EnvOption) (*cel.Env, error)
- func ToJSON(val ref.Val) (any, error)
- func ToJSONMap(val ref.Val) (map[string]any, error)
- type EnvConfig
- type EvalConfig
- type Evaluator
- func (e *Evaluator) Compile(expression string) (*cel.Ast, *cel.Issues)
- func (e *Evaluator) Evaluate(ctx context.Context, expression string, vars map[string]any) (ref.Val, *cel.EvalDetails, error)
- func (e *Evaluator) EvaluateBool(ctx context.Context, expression string, vars map[string]any) (bool, error)
- func (e *Evaluator) EvaluateJSONMap(ctx context.Context, expression string, vars map[string]any) (map[string]any, error)
- func (e *Evaluator) Program(ast *cel.Ast) (cel.Program, error)
- type NativeEntityEvaluator
Constants ¶
const ( // DefaultParserRecursionLimit caps CEL parser recursion depth for hardened environments DefaultParserRecursionLimit = 250 // DefaultParserExpressionSizeLimit caps CEL expression size (code points) for hardened environments DefaultParserExpressionSizeLimit = 100_000 // DefaultInterruptCheckFrequency controls how often CEL checks for interrupts during comprehensions DefaultInterruptCheckFrequency uint = 100 // DefaultEvalTimeout bounds the wall-clock time allowed for a single CEL evaluation DefaultEvalTimeout = 100 * time.Millisecond )
const ( // EntityVarTarget is the CEL variable bound to the candidate entity JSON in entity expressions EntityVarTarget = "target" // EntityVarSource is the CEL variable bound to the source entity JSON in entity expressions EntityVarSource = "source" // EntityVarNow is the CEL variable bound to the logical evaluation timestamp EntityVarNow = "now" )
Variables ¶
var ( // ErrJSONMapExpected indicates a CEL value could not be converted into a JSON object map ErrJSONMapExpected = errors.New("expected JSON object") // ErrNilOutput indicates a CEL evaluation returned a nil value ErrNilOutput = errors.New("CEL evaluation returned nil output") // ErrTypeMismatch indicates the CEL result type did not match the expected type ErrTypeMismatch = errors.New("CEL expression type mismatch") // ErrCompileFailed indicates a CEL expression failed to compile or type-check ErrCompileFailed = errors.New("CEL compilation failed") // ErrEntityDataInvalid indicates entity JSON could not be unmarshaled for expression evaluation ErrEntityDataInvalid = errors.New("failed to unmarshal entity data for evaluation") )
Functions ¶
func BoolResult ¶ added in v1.15.0
BoolResult extracts a boolean value from a CEL ref.Val. Returns ErrNilOutput if val is nil and ErrTypeMismatch if val is not a boolean type.
Types ¶
type EnvConfig ¶
type EnvConfig struct {
// ParserRecursionLimit caps the parser recursion depth, 0 uses CEL defaults
ParserRecursionLimit int
// ParserExpressionSizeLimit caps expression size (code points), 0 uses CEL defaults
ParserExpressionSizeLimit int
// ComprehensionNestingLimit caps nested comprehensions, 0 disables the check
ComprehensionNestingLimit int
// ExtendedValidations enables extra AST validations (regex, duration, timestamps, homogeneous aggregates)
ExtendedValidations bool
// OptionalTypes enables CEL optional types and optional field syntax
OptionalTypes bool
// IdentifierEscapeSyntax enables backtick escaped identifiers
IdentifierEscapeSyntax bool
// CrossTypeNumericComparisons enables comparisons across numeric types
CrossTypeNumericComparisons bool
// MacroCallTracking records macro calls in AST source info for debugging
MacroCallTracking bool
}
func StrictEnvConfig ¶ added in v1.27.11
func StrictEnvConfig() EnvConfig
StrictEnvConfig returns a hardened environment config with parser limits and extended validations enabled. Callers tweak the returned value for environment-specific options such as cross-type numeric comparisons
type EvalConfig ¶
type EvalConfig struct {
// Timeout is the maximum duration allowed for evaluating a CEL expression
Timeout time.Duration
// CostLimit caps the runtime cost of CEL evaluation, 0 disables the limit
CostLimit uint64
// InterruptCheckFrequency controls how often CEL checks for interrupts during comprehensions
InterruptCheckFrequency uint
// EvalOptimize enables evaluation-time optimizations for repeated program runs
EvalOptimize bool
// TrackState enables evaluation state tracking for debugging
TrackState bool
}
EvalConfig configures CEL evaluation behavior
func FastEvalConfig ¶ added in v1.27.11
func FastEvalConfig() EvalConfig
FastEvalConfig returns an evaluation config tuned for short, cached, repeatedly-run expressions
type Evaluator ¶
type Evaluator struct {
// contains filtered or unexported fields
}
Evaluator compiles and evaluates CEL expressions with caching
func NewEvaluator ¶
func NewEvaluator(env *cel.Env, config EvalConfig) *Evaluator
NewEvaluator creates a new CEL evaluator with the provided environment and configuration
func (*Evaluator) Compile ¶
Compile parses and type-checks a CEL expression using the evaluator environment
func (*Evaluator) Evaluate ¶
func (e *Evaluator) Evaluate(ctx context.Context, expression string, vars map[string]any) (ref.Val, *cel.EvalDetails, error)
Evaluate runs a CEL expression against the provided variables
func (*Evaluator) EvaluateBool ¶ added in v1.27.11
func (e *Evaluator) EvaluateBool(ctx context.Context, expression string, vars map[string]any) (bool, error)
EvaluateBool evaluates a CEL expression and extracts a boolean result
type NativeEntityEvaluator ¶ added in v1.27.11
type NativeEntityEvaluator struct {
// contains filtered or unexported fields
}
NativeEntityEvaluator evaluates boolean CEL expressions against typed entity values, binding the candidate entity to "target" and an optional source entity to "source" as native CEL struct types. Fields are accessed by their json tag (snake_case), so expressions like "target.identity_holder_id == source.id" resolve against the bound projection types directly, without decoding to a map[string]any. It satisfies the entityops ExpressionEvaluator and SourceAwareExpressionEvaluator method sets, so it is a drop-in for SelectTargets evaluation.
func NewNativeEntityEvaluator ¶ added in v1.27.11
func NewNativeEntityEvaluator(envCfg EnvConfig, evalCfg EvalConfig, targetType reflect.Type, sourceType reflect.Type) (*NativeEntityEvaluator, error)
NewNativeEntityEvaluator builds a typed entity evaluator whose "target" (and optional "source") variables are the native CEL types of targetType and sourceType. Pass a nil sourceType when the evaluator only needs the candidate entity exposed as "target"
func (*NativeEntityEvaluator) EvaluateBool ¶ added in v1.27.11
func (n *NativeEntityEvaluator) EvaluateBool(ctx context.Context, expression string, data json.RawMessage) (bool, error)
EvaluateBool evaluates the expression against the candidate entity JSON, exposing it as "target"
func (*NativeEntityEvaluator) EvaluateBoolWithSource ¶ added in v1.27.11
func (n *NativeEntityEvaluator) EvaluateBoolWithSource(ctx context.Context, expression string, targetData, sourceData json.RawMessage) (bool, error)
EvaluateBoolWithSource evaluates the expression against the target entity JSON with the source entity exposed as "source", so selectors like target.identity_holder_id == source.id work
Source Files