cel

Documentation

Overview

Package cel provides a generic CEL expression engine for compiling and evaluating expressions against arbitrary data contexts.

The engine provides lazy-initialized, thread-safe environment caching, expression compilation with structured parse and type-check error reporting, boolean and generic value evaluation helpers, and built-in safeguards against denial-of-service via configurable expression length and runtime cost limits.

Basic Usage

Create an engine with variable declarations, compile an expression, and evaluate it:

engine := cel.NewEngine(
    celgo.Variable("claims", celgo.MapType(celgo.StringType, celgo.DynType)),
)

expr, err := engine.Compile(`claims["sub"] == "user123"`)
if err != nil {
    // handle compilation error
}

ctx := map[string]any{"claims": map[string]any{"sub": "user123"}}
result, err := expr.EvaluateBool(ctx)
// result == true

Expression Validation

Use Check to validate an expression without creating a compiled program. This is useful for validating configuration at startup:

err := engine.Check(`claims["sub"] == "user123"`)
if err != nil {
    // expression is invalid
}

Error Handling

Compilation errors are returned as structured types with location information:

expr, err := engine.Compile(`claims["sub"`)
var parseErr *cel.ParseError
if errors.As(err, &parseErr) {
    fmt.Println(parseErr.Source)  // the original expression
    fmt.Println(parseErr.Errors) // line/column/message details
}

expr, err = engine.Compile(`undefined_var == "test"`)
var checkErr *cel.CheckError
if errors.As(err, &checkErr) {
    fmt.Println(checkErr.AsJSON()) // structured JSON error details
}

DoS Protection

The engine includes configurable safeguards against denial-of-service:

engine := cel.NewEngine(opts...).
    WithMaxExpressionLength(5000). // reject overly long expressions
    WithCostLimit(500000)          // limit runtime evaluation cost

Concurrency

The Engine and CompiledExpression types are safe for concurrent use. A compiled expression can be evaluated from multiple goroutines simultaneously.

Index

• Constants
• Variables
• type CheckError
  • func (ce *CheckError) Error() string
  • func (ce *CheckError) Unwrap() error
• type CompiledExpression
  • func (ce *CompiledExpression) Evaluate(ctx map[string]any) (any, error)
  • func (ce *CompiledExpression) EvaluateBool(ctx map[string]any) (bool, error)
  • func (ce *CompiledExpression) Source() string
• type Engine
  • func NewEngine(options ...cel.EnvOption) *Engine
  • func (e *Engine) Check(expr string) error
  • func (e *Engine) Compile(expr string) (*CompiledExpression, error)
  • func (e *Engine) WithCostLimit(limit uint64) *Engine
  • func (e *Engine) WithMaxExpressionLength(maxLen int) *Engine
• type ErrDetails
  • func (ed *ErrDetails) AsJSON() string
• type ErrInstance
• type ErrKind
• type ParseError
  • func (pe *ParseError) Error() string
  • func (pe *ParseError) Unwrap() error

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.

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

func NewEngine(options ...cel.EnvOption) *Engine

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

func (e *Engine) Check(expr string) error

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

func (e *Engine) WithCostLimit(limit uint64) *Engine

WithCostLimit sets the runtime cost limit for CEL program evaluation. Programs that exceed this cost during evaluation will return an error.

func (*Engine) WithMaxExpressionLength

func (e *Engine) WithMaxExpressionLength(maxLen int) *Engine

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 ErrKind

type ErrKind string

ErrKind is a string identifying the type of CEL error.

const (
	// ErrKindParse indicates a syntax error in the CEL expression.
	ErrKindParse ErrKind = "parse"
	// ErrKindCheck indicates a type checking error in the CEL expression.
	ErrKindCheck ErrKind = "check"
)

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.