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

126 lines
4.1 KiB
Go

// Package experiments decides whether an experiment is enabled for a
// subject user. Each user-scoped experiment can have one stored rule that
// inherits the startup default, forces it on or off, or targets users with
// a CEL condition. Every error decides off (fail closed). Decisions gate
// features; they are not an authorization boundary.
package experiments
import (
"encoding/json"
"slices"
"time"
"github.com/google/uuid"
"golang.org/x/xerrors"
"github.com/coder/coder/v2/codersdk"
)
// Mode selects how a rule decides an experiment.
type Mode string
const (
// ModeInherit uses the startup --experiments default.
ModeInherit Mode = "inherit"
// ModeOn enables the experiment for every user.
ModeOn Mode = "on"
// ModeOff disables the experiment for every user, even when it is
// enabled at startup.
ModeOff Mode = "off"
// ModeCondition enables the experiment for users whose condition is
// true.
ModeCondition Mode = "condition"
)
// Rule is the decoded form of one stored experiment rule.
type Rule struct {
Mode Mode `json:"mode"`
// Condition is a CEL expression over `user`. It is set only when Mode
// is ModeCondition.
Condition string `json:"condition,omitempty"`
// Revision increases on every write. Stored rules have revision 1 or
// higher; a stored rule below 1 is malformed. The zero Rule, with
// revision 0, stands for no stored rule.
Revision int64 `json:"revision"`
UpdatedBy uuid.UUID `json:"updated_by"`
UpdatedAt time.Time `json:"updated_at"`
}
// StoredRule is the raw stored value of one experiment rule. It stays
// undecoded so that the Evaluator decides how undecodable values and
// unknown modes behave: they decide off.
type StoredRule struct {
Value json.RawMessage
}
// User holds the attributes a condition can read as `user`. Only string
// and []string fields are allowed. Fields carry `cel` tags and no `json`
// tags so that CEL exposes exactly these names.
type User struct {
ID string `cel:"id"`
Username string `cel:"username"`
// Email is compared as stored (case-sensitive).
Email string `cel:"email"`
// Roles are the explicit site roles. The implied member role and
// organization roles are not included.
Roles []string `cel:"roles"`
// Organizations are the names of organizations the user belongs to.
Organizations []string `cel:"organizations"`
// Groups are "<org>/<group>" names, including "<org>/Everyone".
Groups []string `cel:"groups"`
}
// IsUserScoped reports whether ex accepts runtime rules.
func IsUserScoped(ex codersdk.Experiment) bool {
return slices.Contains(codersdk.ExperimentsUserScoped, ex)
}
// ValidateRule checks that rule can be stored for ex. The returned error
// can contain full CEL diagnostics, which may quote the condition. Return
// it only to the rule author; never log it.
func ValidateRule(ex codersdk.Experiment, rule Rule) error {
if !IsUserScoped(ex) {
return xerrors.Errorf("experiment %q does not accept runtime rules", ex)
}
if err := checkShape(rule); err != nil {
return err
}
if rule.Mode != ModeCondition {
return nil
}
_, err := compileCondition(rule.Condition)
return err
}
// checkShape verifies the mode and that a condition is present only for
// ModeCondition.
func checkShape(rule Rule) error {
switch rule.Mode {
case ModeInherit, ModeOn, ModeOff:
if rule.Condition != "" {
return xerrors.Errorf("mode %q must not have a condition", rule.Mode)
}
case ModeCondition:
if rule.Condition == "" {
return xerrors.New("mode \"condition\" requires a condition")
}
default:
return xerrors.Errorf("unknown mode %q", rule.Mode)
}
return nil
}
// decodeRule decodes and checks a stored rule: its shape, and a revision of
// 1 or higher, which every write stores. Errors must not be logged because
// JSON errors can quote stored content.
func decodeRule(stored StoredRule) (Rule, error) {
var rule Rule
if err := json.Unmarshal(stored.Value, &rule); err != nil {
return Rule{}, xerrors.Errorf("decode rule: %w", err)
}
if rule.Revision < 1 {
return rule, xerrors.Errorf("stored rule has invalid revision %d", rule.Revision)
}
return rule, checkShape(rule)
}