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>
182 lines
5.4 KiB
Go
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
|
|
}
|