Documentation
¶
Overview ¶
Package cel provides a generic CEL expression engine for evaluating expressions against arbitrary data contexts.
Index ¶
Constants ¶
const ( // DefaultMaxExpressionLength is the maximum allowed length for a CEL expression. // This limit prevents DoS attacks via excessively long expressions. DefaultMaxExpressionLength = 10000 // DefaultCostLimit is the default runtime cost limit for CEL program evaluation. // This prevents DoS attacks via expensive operations in expressions. DefaultCostLimit = 1000000 )
Variables ¶
var ( // ErrExpressionCheck is returned when a CEL expression fails syntax or type checking. ErrExpressionCheck = errors.New("CEL expression check failed") // ErrEvaluation is returned when CEL expression evaluation fails. ErrEvaluation = errors.New("CEL expression evaluation failed") // ErrInvalidResult is returned when the CEL expression returns an unexpected type. ErrInvalidResult = errors.New("CEL expression returned invalid result type") )
Sentinel errors for CEL operations.
Functions ¶
This section is empty.
Types ¶
type CheckError ¶
type CheckError struct {
ErrDetails
// contains filtered or unexported fields
}
CheckError represents a CEL type checking error with location information.
func (*CheckError) Error ¶
func (ce *CheckError) Error() string
Error implements the error interface for CheckError.
func (*CheckError) Unwrap ¶
func (ce *CheckError) Unwrap() error
Unwrap returns the underlying error.
type CompiledExpression ¶
type CompiledExpression struct {
// contains filtered or unexported fields
}
CompiledExpression represents a pre-compiled CEL program ready for evaluation.
func (*CompiledExpression) Evaluate ¶
func (ce *CompiledExpression) Evaluate(ctx map[string]any) (any, error)
Evaluate executes the compiled expression against the provided context and returns the result. The context should contain values for all variables declared when creating the Engine.
Example:
ctx := map[string]any{"myVar": someValue}
func (*CompiledExpression) EvaluateBool ¶
func (ce *CompiledExpression) EvaluateBool(ctx map[string]any) (bool, error)
EvaluateBool executes the compiled expression and returns the result as a bool. Returns an error if the expression does not evaluate to a boolean.
func (*CompiledExpression) Source ¶
func (ce *CompiledExpression) Source() string
Source returns the original expression source string.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine provides CEL expression compilation and evaluation capabilities. It is safe for concurrent use from multiple goroutines.
func NewEngine ¶
NewEngine creates a new CEL engine with the specified variable declarations. The options are passed to cel.NewEnv to configure the CEL environment.
The engine is created with default limits for expression length and evaluation cost to prevent denial-of-service attacks. Use WithMaxExpressionLength and WithCostLimit to customize these limits if needed.
Example usage:
engine := cel.NewEngine(
cel.Variable("claims", cel.MapType(cel.StringType, cel.DynType)),
)
func (*Engine) Check ¶
Check verifies that a CEL expression is syntactically and semantically valid without creating a compiled program. This is useful for configuration validation.
Returns an error if the expression exceeds the maximum length, a ParseError if the expression has syntax errors, or a CheckError if the expression has type checking errors.
func (*Engine) Compile ¶
func (e *Engine) Compile(expr string) (*CompiledExpression, error)
Compile parses and compiles a CEL expression, returning a CompiledExpression that can be evaluated multiple times against different contexts.
Returns an error if the expression exceeds the maximum length, a ParseError if the expression has syntax errors, or a CheckError if the expression has type checking errors.
func (*Engine) WithCostLimit ¶
WithCostLimit sets the runtime cost limit for CEL program evaluation. Programs that exceed this cost during evaluation will return an error.
func (*Engine) WithMaxExpressionLength ¶
WithMaxExpressionLength sets the maximum allowed length for CEL expressions. Expressions exceeding this length will be rejected during compilation.
type ErrDetails ¶
type ErrDetails struct {
Errors []ErrInstance `json:"errors,omitempty"`
Source string `json:"source,omitempty"`
}
ErrDetails contains structured error information for CEL expressions.
func (*ErrDetails) AsJSON ¶
func (ed *ErrDetails) AsJSON() string
AsJSON returns the ErrDetails as a JSON string.
type ErrInstance ¶
type ErrInstance struct {
Line int `json:"line,omitempty"`
Col int `json:"col,omitempty"`
Msg string `json:"msg,omitempty"`
}
ErrInstance represents one occurrence of an error in a CEL expression.
type ParseError ¶
type ParseError struct {
ErrDetails
// contains filtered or unexported fields
}
ParseError represents a CEL syntax error with location information.
func (*ParseError) Error ¶
func (pe *ParseError) Error() string
Error implements the error interface for ParseError.
func (*ParseError) Unwrap ¶
func (pe *ParseError) Unwrap() error
Unwrap returns the underlying error.
Source Files