Files
Thomas Kosiewski 84fe2dda92 feat: add per-user experiment rule evaluator (#29869)
Slice 1 of 4 for runtime experiment rules: adds an internal evaluator
that decides whether an experiment is enabled for a given user, based on
a stored rule and that user's attributes. The package has no storage,
API, or callers yet, so behavior does not change.

## What's in it

- `coderd/experiments`: `Evaluator` with `New(logger, store, static)`,
`Enabled(ctx, userID, ex)` and `EnabledExperiments(ctx, userID)`. It
also adds the `Store` interface, the `Rule`/`StoredRule`/`User` models
and `ValidateRule`.
- Rule modes: `inherit` (use the startup `--experiments` default), `on`,
`off` (a kill switch that wins over a static on), and `condition` (a CEL
expression over `user.id`, `user.username`, `user.email`, `user.roles`,
`user.organizations`, `user.groups`).
- **Fail closed:** the decision is off for a rules-read error, a
malformed rule (including a stored revision below 1) or unknown mode, a
failed attribute load, a compile or eval error, a cost overrun, a
cancelled context, or a `uuid.Nil` subject. This holds even when the
experiment is enabled statically. `New` rejects a nil store, so there is
no fallback.
- **Diagnostics:** only errors returned to the caller carry full CEL
diagnostics. Logs record the experiment, revision, error category and
line:column, never condition text or CEL message text.
- Limits: 4096 code points, cost limit 10,000, and evaluation stops when
the context is cancelled. Compiled programs go in a bounded,
concurrency-safe cache keyed by exact source text. Decisions are never
cached.
- `codersdk.ExperimentsUserScoped = {example}`. Only experiments listed
there accept rules.
- `coderd/experiments/experimentstest`: a fake `Store` for tests.

## Dependency

Adds `cel.dev/cel-go v0.32.0` (plus indirect `antlr4-go/antlr/v4
v4.13.1`). `cel.dev/cel-go` is the module path that
`github.com/google/cel-go` now declares. GHSA-gcjh-h69q-9w9g
(GO-2026-6094) is fixed in 0.29.0. `govulncheck
./coderd/experiments/...` reports nothing against either new module. Its
remaining findings are go1.26.5 standard-library issues, fixed in
go1.26.6, plus existing dependencies, and they show up on unrelated
packages too.

## Stack

1. **This PR:** evaluator library
2. Storage and audit types (`site_configs` rows, revisions, `WriteRule`)
3. Enforcement and discovery (`/api/v2/experiments`, meta tag, chatd
`mcp-tool-search`, ruleguard)
4. Control plane (experimental API, `coder exp experiment-rules` CLI,
docs)

Remote dogfood UAT through Coder Agents passed. `/api/v2/experiments` is
unchanged for admin and member with and without `--experiments=example`,
and the package tests pass with and without `-race`.

> [!NOTE]
> This PR was written by an AI agent (Xum).

---
_Generated with [`xum`](https://github.com/coder/xum) • Model:
`anthropic:claude-opus-5-5` • Thinking: `high`_

---------

Signed-off-by: Thomas Kosiewski <tk@coder.com>
2026-09-29 12:22:59 +00:00

182 lines
5.4 KiB
Go

package experiments
import (
"context"
"errors"
"reflect"
"sync"
"unicode/utf8"
"cel.dev/cel-go/cel"
"cel.dev/cel-go/ext"
"cel.dev/cel-go/interpreter"
"golang.org/x/xerrors"
)
const (
// MaxConditionSize is the maximum condition length in code points.
MaxConditionSize = 4096
// maxConditionCost bounds the runtime cost of one evaluation.
maxConditionCost = 10_000
// interruptCheckFrequency is how many comprehension iterations run
// between context cancellation checks.
interruptCheckFrequency = 100
// maxCachedPrograms bounds the compiled program cache.
maxCachedPrograms = 256
)
// errorCategory names a failure class. Categories are the only error
// detail written to server logs.
type errorCategory string
const (
categorySyntax errorCategory = "syntax"
categoryType errorCategory = "type"
categorySize errorCategory = "size"
categoryCost errorCategory = "cost"
categoryEval errorCategory = "eval"
categoryCancelled errorCategory = "canceled"
categoryMalformed errorCategory = "malformed"
categoryRead errorCategory = "read"
)
// conditionError is a compile or evaluation failure. Error returns the
// full CEL diagnostics, which can quote the condition, so loggers must use
// only category, line and column.
type conditionError struct {
category errorCategory
// line is 1-based and column is 1-based. Zero means unknown.
line int
column int
diag error
}
func (e *conditionError) Error() string { return e.diag.Error() }
func (e *conditionError) Unwrap() error { return e.diag }
// celEnv is shared by every compile. A *cel.Env is safe for concurrent
// use.
var celEnv = sync.OnceValues(func() (*cel.Env, error) {
// The user variable's type name is "<package>.<type>", as named by
// ext.NativeTypes.
return cel.NewEnv(
ext.NativeTypes(reflect.TypeFor[User](), ext.ParseStructTags(true)),
cel.Variable("user", cel.ObjectType("experiments.User")),
cel.ParserExpressionSizeLimit(MaxConditionSize),
)
})
// compileCondition parses, type-checks and plans source. It requires a
// bool result.
func compileCondition(source string) (cel.Program, error) {
if utf8.RuneCountInString(source) > MaxConditionSize {
return nil, &conditionError{
category: categorySize,
diag: xerrors.Errorf("condition exceeds %d characters", MaxConditionSize),
}
}
env, err := celEnv()
if err != nil {
return nil, xerrors.Errorf("create CEL environment: %w", err)
}
parsed, iss := env.Parse(source)
if iss.Err() != nil {
return nil, issuesError(categorySyntax, iss)
}
checked, iss := env.Check(parsed)
if iss.Err() != nil {
return nil, issuesError(categoryType, iss)
}
if !checked.OutputType().IsExactType(cel.BoolType) {
return nil, &conditionError{
category: categoryType,
diag: xerrors.Errorf("condition must return bool, got %s", checked.OutputType()),
}
}
prg, err := env.Program(checked,
cel.CostLimit(maxConditionCost),
cel.InterruptCheckFrequency(interruptCheckFrequency),
)
if err != nil {
return nil, &conditionError{category: categoryType, diag: xerrors.Errorf("plan condition: %w", err)}
}
return prg, nil
}
func issuesError(category errorCategory, iss *cel.Issues) *conditionError {
cerr := &conditionError{category: category, diag: iss.Err()}
if errs := iss.Errors(); len(errs) > 0 && errs[0].Location != nil {
cerr.line = errs[0].Location.Line()
cerr.column = errs[0].Location.Column() + 1
}
return cerr
}
// evalCondition runs prg for user. The context cancels evaluation.
func evalCondition(ctx context.Context, prg cel.Program, user User) (bool, error) {
if err := ctx.Err(); err != nil {
return false, &conditionError{category: categoryCancelled, diag: err}
}
out, _, err := prg.ContextEval(ctx, map[string]any{"user": user})
if err != nil {
var canceled interpreter.EvalCancelledError
switch {
case errors.As(err, &canceled) && canceled.Cause == interpreter.CostLimitExceeded:
return false, &conditionError{category: categoryCost, diag: err}
case errors.As(err, &canceled), ctx.Err() != nil:
return false, &conditionError{category: categoryCancelled, diag: err}
default:
return false, &conditionError{category: categoryEval, diag: err}
}
}
result, ok := out.Value().(bool)
if !ok {
return false, &conditionError{category: categoryEval, diag: xerrors.Errorf("condition returned %s, not bool", out.Type())}
}
return result, nil
}
// compiled is one cache entry. Compile failures are cached too, so a
// broken stored condition is not recompiled on every call.
type compiled struct {
prg cel.Program
err error
}
// programCache holds compiled conditions keyed by exact source text. It
// is bounded and safe for concurrent use.
type programCache struct {
mu sync.Mutex
programs map[string]compiled
}
func newProgramCache() *programCache {
return &programCache{programs: make(map[string]compiled)}
}
func (c *programCache) get(source string) (cel.Program, error) {
c.mu.Lock()
entry, ok := c.programs[source]
c.mu.Unlock()
if ok {
return entry.prg, entry.err
}
// Compile outside the lock. Concurrent misses for the same source
// may compile twice; the results are equivalent.
prg, err := compileCondition(source)
c.mu.Lock()
defer c.mu.Unlock()
if _, ok := c.programs[source]; !ok && len(c.programs) >= maxCachedPrograms {
// Evict an arbitrary entry to stay within the bound.
for k := range c.programs {
delete(c.programs, k)
break
}
}
c.programs[source] = compiled{prg: prg, err: err}
return prg, err
}