Files
archie/internal/domain/eda/expr/expr.go
T

154 lines
5.7 KiB
Go

// Package expr is the CEL expression environment for the EDA playbook engine:
// one mechanism for both an action's `when` condition and its `args` values,
// per eda-playbook-engine.md's resolved open question 1 (CEL decision).
//
// The environment declares two context roots -- `event` (the triggering
// event's decoded payload) and `actions` (prior actions' results keyed by the
// action's declared id, `actions.<id>.result.<field>`) -- and applies a cost
// limit to every program. The same compile path serves the playbook loader
// (reject-at-load) and the lint tool, so author-time diagnostics and runtime
// evaluation cannot disagree.
//
// CEL is non-Turing-complete, side-effect-free, and panic-free by design (no
// recover() wrapper is needed; verified in the t2db.14 acceptance tests
// against hostile data). Anything the schema does not accept is a returned
// error here -- the reject-at-load philosophy of the parent design doc.
package expr
import (
"sort"
"cel.dev/cel-go/cel"
celast "cel.dev/cel-go/common/ast"
)
// DefaultCostLimit bounds evaluation of every playbook expression (J5 in the
// resolved doc: tunable, start here; linter and daemon share the same value).
const DefaultCostLimit = 100_000
// Env is the CEL environment for playbook expressions: the declared context
// roots and the default cost limit applied to every compiled program.
type Env struct {
celEnv *cel.Env
costLimit uint64
}
// Context is what an expression may read at dispatch time. Both maps are
// read-only from the expression's perspective; CEL enforces this.
type Context struct {
// Event is the triggering event's decoded payload (webhook body, forge
// issue, schedule tick). Declared dyn because its shape is unknown by
// design (schema-by-example); field-level typing is follow-up work once
// multi-action playbooks exist (per-kind generated Result structs
// declared as CEL types).
Event map[string]any
// Actions holds prior actions' results keyed by the action's id as
// declared in the playbook. Empty today (single-action playbooks have
// no prior actions); kept dyn for the same reason as Event.
Actions map[string]map[string]any
}
// NewEnv builds the CEL environment with the two context roots and the
// default cost limit.
func NewEnv() *Env {
celEnv, err := cel.NewEnv(
cel.Variable("event", cel.MapType(cel.StringType, cel.DynType)),
cel.Variable("actions", cel.MapType(cel.StringType, cel.DynType)),
)
if err != nil {
// cel.NewEnv with static variable declarations cannot fail in
// practice; a failure here is a programming error, not a playbook
// error. Panic is appropriate (package init-style invariant).
panic(err)
}
return &Env{celEnv: celEnv, costLimit: DefaultCostLimit}
}
// Compile parses and type-checks a playbook expression string against the
// declared context. A syntax error, an unknown root (anything other than
// event/actions), or a type error is a returned error -- never a panic.
// The returned Program is safe to evaluate concurrently (CEL programs are
// stateless once compiled).
//
// This is the reject-at-load entry point: the playbook loader and the lint
// tool call this at load time, so a bad expression drops the playbook with a
// reported error rather than failing at dispatch.
func (e *Env) Compile(src string) (*Program, error) {
ast, issues := e.celEnv.Compile(src)
if issues != nil && issues.Err() != nil {
return nil, issues.Err()
}
prg, err := e.celEnv.Program(ast, cel.CostLimit(e.costLimit))
if err != nil {
return nil, err
}
return &Program{prg: prg, actionIDs: referencedActionIDs(ast)}, nil
}
// referencedActionIDs walks the compiled AST and returns the sorted, de-
// duplicated set of action ids an expression reads through `actions.<id>`.
// `actions` is declared map(string,dyn), so CEL type-checking cannot reject
// an unknown id; the playbook loader compares this set against the ids of
// prior actions to reject unknown references at load (J1 in
// docs/prds/playbook-expression-syntax.md). The map-index form
// (`actions["notify"]`) is a runtime lookup, not a field selection, and is
// intentionally not collected here.
func referencedActionIDs(ast *cel.Ast) []string {
if ast == nil || ast.NativeRep() == nil {
return nil
}
seen := map[string]struct{}{}
visitor := celast.NewExprVisitor(func(e celast.Expr) {
if e.Kind() != celast.SelectKind {
return
}
sel := e.AsSelect()
operand := sel.Operand()
if operand.Kind() != celast.IdentKind || operand.AsIdent() != "actions" {
return
}
seen[sel.FieldName()] = struct{}{}
})
celast.PreOrderVisit(ast.NativeRep().Expr(), visitor)
ids := make([]string, 0, len(seen))
for id := range seen {
ids = append(ids, id)
}
sort.Strings(ids)
return ids
}
// Program is a compiled, cost-limited playbook expression.
type Program struct {
prg cel.Program
actionIDs []string
}
// ReferencedActionIDs returns the sorted, de-duplicated action ids the
// expression reads through `actions.<id>`. It is empty when the expression
// reads no prior-action result.
func (p *Program) ReferencedActionIDs() []string {
if p == nil {
return nil
}
return p.actionIDs
}
// Eval evaluates the program against a dispatch-time context. A missing
// field, a wrong type against a dyn value, or an exceeded cost limit is a
// returned error. CEL's own evaluation recovers panics internally (verified
// in cel-go's program.go: Eval wraps evaluation in recover), and its
// returned values implement ref.Val -- unwrapped here to the native Go value
// the caller expects.
func (e *Env) Eval(prg *Program, ctx Context) (any, error) {
data := map[string]any{
"event": ctx.Event,
"actions": ctx.Actions,
}
v, _, err := prg.prg.Eval(data)
if err != nil {
return nil, err
}
return v.Value(), nil
}