From 179266c2b6b6d6d998f9b15d37fbdb4f1c796cb7 Mon Sep 17 00:00:00 2001 From: Kevin Tang <73975146+vt128@users.noreply.github.com> Date: Sun, 8 Nov 2026 10:56:44 +0800 Subject: [PATCH] [feat] add read-only Starlark evaluation (LET-35) --- README.md | 3 +- config.go | 3 + lib/starlark/README.md | 145 ++++++++++++ lib/starlark/snapshot.go | 207 +++++++++++++++++ lib/starlark/snapshot_test.go | 203 ++++++++++++++++ lib/starlark/source.go | 73 ++++++ lib/starlark/source_test.go | 107 +++++++++ lib/starlark/starlark.go | 358 +++++++++++++++++++++++++++++ lib/starlark/starlark_test.go | 419 ++++++++++++++++++++++++++++++++++ module_test.go | 37 ++- 10 files changed, 1553 insertions(+), 2 deletions(-) create mode 100644 lib/starlark/README.md create mode 100644 lib/starlark/snapshot.go create mode 100644 lib/starlark/snapshot_test.go create mode 100644 lib/starlark/source.go create mode 100644 lib/starlark/source_test.go create mode 100644 lib/starlark/starlark.go create mode 100644 lib/starlark/starlark_test.go diff --git a/README.md b/README.md index 35e693a..d2c448a 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ Inspired by the [*Starlight*](https://github.com/starlight-go/starlight) and [*S | [`regex`](/lib/regex) | [![godoc](https://pkg.go.dev/badge/github.com/1set/starlet/lib/regex.svg)](https://pkg.go.dev/github.com/1set/starlet/lib/regex) | Python-style regex (RE2) with Match objects, flags, named groups | | [`runtime`](/lib/runtime) | [![godoc](https://pkg.go.dev/badge/github.com/1set/starlet/lib/runtime.svg)](https://pkg.go.dev/github.com/1set/starlet/lib/runtime) | Provides Go and app runtime information | | [`serial`](/lib/serial) | [![godoc](https://pkg.go.dev/badge/github.com/1set/starlet/lib/serial.svg)](https://pkg.go.dev/github.com/1set/starlet/lib/serial) | Lossless data-value serialization (bytes/set/tuple/bigint/time) | +| [`starlark`](/lib/starlark) | [![godoc](https://pkg.go.dev/badge/github.com/1set/starlet/lib/starlark.svg)](https://pkg.go.dev/github.com/1set/starlet/lib/starlark) | Read-only data snapshots for Starlark expressions and structured try errors | | [`stats`](/lib/stats) | [![godoc](https://pkg.go.dev/badge/github.com/1set/starlet/lib/stats.svg)](https://pkg.go.dev/github.com/1set/starlet/lib/stats) | Statistics: mean/median/stddev, correlation, percentiles, etc. | | [`string`](/lib/string) | [![godoc](https://pkg.go.dev/badge/github.com/1set/starlet/lib/string.svg)](https://pkg.go.dev/github.com/1set/starlet/lib/string) | Constants and functions to manipulate strings | @@ -106,7 +107,7 @@ This may output: ``` Starlark: Hello, Starlet! Go: Hello, Starlet! -Modules: [atom base64 csv file go_idiomatic hashlib http json log math net path random re regex runtime serial stats string struct time] +Modules: [atom base64 csv file go_idiomatic hashlib http json log math net path random re regex runtime serial starlark stats string struct time] ``` Use CLI to interact with the read-eval-print loop (REPL): diff --git a/config.go b/config.go index b11ddac..bfe7eba 100644 --- a/config.go +++ b/config.go @@ -20,6 +20,7 @@ import ( libregex "github.com/1set/starlet/lib/regex" librt "github.com/1set/starlet/lib/runtime" libserial "github.com/1set/starlet/lib/serial" + libsl "github.com/1set/starlet/lib/starlark" libstat "github.com/1set/starlet/lib/stats" libstr "github.com/1set/starlet/lib/string" stdmath "go.starlark.net/lib/math" @@ -65,6 +66,7 @@ var allBuiltinModules = ModuleLoaderMap{ librt.ModuleName: librt.LoadModule, libserial.ModuleName: libserial.LoadModule, libstr.ModuleName: libstr.LoadModule, + libsl.ModuleName: libsl.LoadModule, libstat.ModuleName: libstat.LoadModule, } @@ -190,6 +192,7 @@ var builtinModuleCapabilities = map[string]ModuleCapability{ "regex": CapPure, "runtime": CapProcess, // exposes host identity, directories, process info "serial": CapPure, + "starlark": CapPure, // explicit data-only evaluation; no caller capabilities inherited "stats": CapPure, "string": CapPure, "struct": CapPure, diff --git a/lib/starlark/README.md b/lib/starlark/README.md new file mode 100644 index 0000000..b8ead02 --- /dev/null +++ b/lib/starlark/README.md @@ -0,0 +1,145 @@ +# starlark + +`starlark` evaluates a single **Starlark expression** against an explicit, +read-only data snapshot. It provides normal and tuple-returning error handling, +without inheriting caller functions, modules or host objects. + +The name identifies the language. It does not evaluate +[Expr-language](https://github.com/expr-lang/expr) syntax, and does not guess or +retry another language. `expr` is left available for a separate future adapter. + +## Functions + +| Function | Result | +| --- | --- | +| `eval(source, vars={})` | A frozen native data value; raises an error on failure. | +| `try_eval(source, vars={})` | `(value, None)` on success, or `(None, error_info)` on an ordinary evaluation failure. | + +`source` must be a string. `vars` must be a native dict whose keys are valid +Starlark identifiers. Omitting `vars` supplies an empty environment. The module +does not inspect caller locals or copy a Machine's implicit globals. + +```python +load("starlark", "eval", "try_eval") + +items = [2, 3] +result = eval( + '{"title": title.upper(), "values": [x * 2 for x in items]}', + vars={"title": "example", "items": items}, +) +# {"title": "EXAMPLE", "values": [4, 6]} + +value, error = try_eval("items.append(9)", vars={"items": items}) +# value == None; error["phase"] == "runtime" +items.append(4) # The original input was neither changed nor frozen. + +value, error = try_eval("None") +# (None, None): a valid None result is distinct from failure. +``` + +A preloaded module is also available as `starlark.eval(...)` and +`starlark.try_eval(...)`. When importing both this module and `json.eval`, use +explicit load aliases to distinguish the engines. + +## Data and method boundaries + +Inputs and results preserve native `None`, bool, int (including big integers), +float, string, bytes, list, dict, tuple and set values. Nested data is supported; +aliases are preserved within a copied graph. Reference cycles, nil values, +functions, bound methods, modules, iterators and custom or Go-backed values are +rejected with a data path. Convert a host object into an explicit native data +projection first; wrapping it with Starlight does not create a snapshot. + +Only private input copies are frozen. Native read methods such as `upper`, +`lower`, `get` and `index`, comprehensions and approved computational builtins +remain usable. Mutating a frozen input fails. Expressions may create and modify +their own temporary containers; results are checked, copied and frozen before +publication. Even a frozen lambda or bound method remains callable, so callable +results are rejected recursively. + +Caller functions and external modules are not inherited. Unapproved Universe +builtins, including `print`, are blocked without changing the global Universe or +calling the parent's Print handler. The standard computational builtin instances +are captured during package initialization; the embedding application's startup +must retain the standard definitions then. As upstream requires, do not modify +Universe concurrently with execution. This policy is independent of Starlet's +CapPure classification: random and clock sources are not automatically exposed. + +The source graph must be exclusively owned/synchronized during evaluation, or +already deeply frozen native data. A lack of writers alone is insufficient: +iterating an unfrozen native set can change its iterator bookkeeping. The helper +does not acquire a Machine or application data lock for the caller. + +## Errors and execution state + +`error_info` is a frozen dict with these fields: + +- `phase` and `kind`: the failing stage or policy category; +- `message`: a diagnostic string; +- `position`: `None` or `{file, line, column}`; +- `frames`: a tuple of `{file, line, column, name}` dicts; +- `truncated`: whether diagnostic text or frames were shortened. + +Stages distinguish arguments, input, source admission, parsing, name resolution, +runtime, policy and output checks. Messages are limited to 4096 bytes, the most +recent 32 frames are retained, and frame file/name text is bounded. + +Both functions execute on the caller's existing Thread. Its cancellation, +OnMaxSteps behavior and cumulative VM step count remain in force; no new step +allowance is installed or reset. Execution checkpoints also consume VM steps. +`try_eval` does **not** turn caller cancellation, exhausted total steps or a caller +panic into a successful tuple. It only handles errors occurring inside the call; +errors while evaluating the call's arguments still belong to the outer script. + +There is no rollback of host callback effects. Such callbacks are excluded from +the data boundary. Errors discard the private evaluation data. + +## Admission limits + +| Limit | Value | +| --- | --- | +| Source bytes | 4096 | +| Non-whitespace source bytes | 512 | +| AST depth / nodes | 64 / 512 | +| Each copied data graph's depth / visited edges | 64 / 4096 | +| Each copied graph's scalar/name payload | 1 MiB | +| Integer magnitude | At most 4096 bits | + +The pre-parser complexity count includes non-whitespace bytes in strings and +comments; only ASCII space, tab, CR and LF are excluded. Put large data in `vars`. +Input and output copying have separate graph quotas. Every visited edge counts, +including memo hits; payload accounting follows the copied graph rather than an +expanded JSON serialization. + +These are admission and result limits, **not hard RSS or CPU limits**. The pinned +parser's general recursion issue is not repaired here. VM steps do not account for +every operation inside a native builtin; an intermediate allocation can occur +before output admission. Configure the caller's execution limits, and use a +separately validated process boundary when stronger isolation is required. + +## Go usage + +```go +import ( + evalmod "github.com/1set/starlet/lib/starlark" + "go.starlark.net/starlark" +) + +thread := &starlark.Thread{Name: "expression"} +thread.SetMaxExecutionSteps(10000) +result, err := evalmod.Eval(thread, "qty * 2", starlark.StringDict{ + "qty": starlark.MakeInt(3), +}) +``` + +The caller owns the Thread and source graph. Direct Go callers must wire +cancellation to `Thread.Cancel` when cancellation during VM execution is needed; +a context stored in Thread.Local is checked at helper checkpoints, not a new +cancellation goroutine. Machine calls retain their existing cancellation bridge. +The Go helper returns `starlark.Value` and an error preserving parser, resolver and +EvalError causes through `errors.As`/`errors.Is`. It does not implicitly convert +the result to Go or JSON. + +The module is registered as CapPure because it grants no filesystem, network, +process or logging access. Downstream module sets still decide whether to expose +it; CapPure does not itself establish deterministic execution or a sandbox. diff --git a/lib/starlark/snapshot.go b/lib/starlark/snapshot.go new file mode 100644 index 0000000..d78d2dc --- /dev/null +++ b/lib/starlark/snapshot.go @@ -0,0 +1,207 @@ +package starlark + +import ( + "fmt" + "math/big" + "reflect" + + std "go.starlark.net/starlark" +) + +const ( + maxDataDepth = 64 + maxDataNodes = 4096 + maxDataBytes = 1 << 20 + maxIntBits = 4096 +) + +var integerBound = std.MakeBigInt(new(big.Int).Lsh(big.NewInt(1), maxIntBits)) +var negativeIntegerBound = std.MakeBigInt(new(big.Int).Neg(new(big.Int).Lsh(big.NewInt(1), maxIntBits))) + +type objectKey struct { + kind byte + ptr uintptr + len int +} + +type dataCopy struct { + thread *std.Thread + nodes int + bytes int + active map[objectKey]bool + memo map[objectKey]std.Value + height map[objectKey]int +} + +func newDataCopy(thread *std.Thread) *dataCopy { + return &dataCopy{thread: thread, active: make(map[objectKey]bool), memo: make(map[objectKey]std.Value), height: make(map[objectKey]int)} +} + +func (c *dataCopy) chargeBytes(n int, path string) error { + if n > maxDataBytes-c.bytes { + return fmt.Errorf("%s: data exceeds %d bytes", path, maxDataBytes) + } + c.bytes += n + return nil +} + +func (c *dataCopy) value(value std.Value, path string, depth int) (std.Value, error) { + c.nodes++ // Every edge counts, including an alias that hits the memo. + if c.nodes > maxDataNodes { + return nil, fmt.Errorf("%s: data exceeds %d nodes", path, maxDataNodes) + } + if depth > maxDataDepth { + return nil, fmt.Errorf("%s: data exceeds depth %d", path, maxDataDepth) + } + if c.nodes%64 == 0 { + if err := checkThread(c.thread); err != nil { + return nil, err + } + } + switch x := value.(type) { + case std.NoneType, std.Bool, std.Float: + return x, c.chargeBytes(8, path) + case std.Int: + upper, _ := x.Cmp(integerBound, 0) + lower, _ := x.Cmp(negativeIntegerBound, 0) + if upper >= 0 || lower <= 0 { + return nil, fmt.Errorf("%s: integer exceeds %d bits", path, maxIntBits) + } + return x, c.chargeBytes((x.BigInt().BitLen()+7)/8, path) + case std.String: + return x, c.chargeBytes(len(x), path) + case std.Bytes: + return x, c.chargeBytes(len(x), path) + case *std.List: + if x == nil { + return nil, fmt.Errorf("%s: nil list", path) + } + key := objectKey{kind: 'l', ptr: reflect.ValueOf(x).Pointer()} + if known, found, err := c.lookup(key, path, depth); found || err != nil { + return known, err + } + if x.Len() > maxDataNodes-c.nodes { + return nil, fmt.Errorf("%s: list exceeds node limit", path) + } + out := std.NewList(nil) + c.memo[key], c.active[key] = out, true + defer delete(c.active, key) + for i := 0; i < x.Len(); i++ { + item, err := c.value(x.Index(i), fmt.Sprintf("%s[%d]", path, i), depth+1) + if err != nil { + return nil, err + } + _ = out.Append(item) + c.childHeight(key, x.Index(i)) + } + return out, nil + case *std.Dict: + if x == nil { + return nil, fmt.Errorf("%s: nil dict", path) + } + key := objectKey{kind: 'd', ptr: reflect.ValueOf(x).Pointer()} + if known, found, err := c.lookup(key, path, depth); found || err != nil { + return known, err + } + if x.Len() > (maxDataNodes-c.nodes)/2 { + return nil, fmt.Errorf("%s: dict exceeds node limit", path) + } + out := std.NewDict(x.Len()) + c.memo[key], c.active[key] = out, true + defer delete(c.active, key) + for i, pair := range x.Items() { + k, err := c.value(pair[0], fmt.Sprintf("%s.key[%d]", path, i), depth+1) + if err != nil { + return nil, err + } + v, err := c.value(pair[1], fmt.Sprintf("%s.value[%d]", path, i), depth+1) + if err != nil { + return nil, err + } + if err := out.SetKey(k, v); err != nil { + return nil, fmt.Errorf("%s: %w", path, err) + } + c.childHeight(key, pair[0]) + c.childHeight(key, pair[1]) + } + return out, nil + case std.Tuple: + key := objectKey{kind: 't', ptr: reflect.ValueOf(x).Pointer(), len: len(x)} + if known, found, err := c.lookup(key, path, depth); found || err != nil { + return known, err + } + if len(x) > maxDataNodes-c.nodes { + return nil, fmt.Errorf("%s: tuple exceeds node limit", path) + } + out := make(std.Tuple, len(x)) + c.memo[key], c.active[key] = out, true + defer delete(c.active, key) + for i, item := range x { + v, err := c.value(item, fmt.Sprintf("%s[%d]", path, i), depth+1) + if err != nil { + return nil, err + } + out[i] = v + c.childHeight(key, item) + } + return out, nil + case *std.Set: + if x == nil { + return nil, fmt.Errorf("%s: nil set", path) + } + key := objectKey{kind: 's', ptr: reflect.ValueOf(x).Pointer()} + if known, found, err := c.lookup(key, path, depth); found || err != nil { + return known, err + } + if x.Len() > maxDataNodes-c.nodes { + return nil, fmt.Errorf("%s: set exceeds node limit", path) + } + out := std.NewSet(x.Len()) + c.memo[key], c.active[key] = out, true + defer delete(c.active, key) + it := x.Iterate() + defer it.Done() + var item std.Value + for i := 0; it.Next(&item); i++ { + v, err := c.value(item, fmt.Sprintf("%s[%d]", path, i), depth+1) + if err != nil { + return nil, err + } + if err := out.Insert(v); err != nil { + return nil, fmt.Errorf("%s: %w", path, err) + } + c.childHeight(key, item) + } + return out, nil + default: + return nil, fmt.Errorf("%s: unsupported data value %T", path, value) + } +} + +func (c *dataCopy) lookup(key objectKey, path string, depth int) (std.Value, bool, error) { + if c.active[key] { + return nil, false, fmt.Errorf("%s: reference cycle is unsupported", path) + } + v, found := c.memo[key] + if found && depth+c.height[key] > maxDataDepth { + return nil, false, fmt.Errorf("%s: aliased data exceeds depth %d", path, maxDataDepth) + } + return v, found, nil +} + +func (c *dataCopy) childHeight(parent objectKey, value std.Value) { + height := 1 + switch x := value.(type) { + case *std.List: + height += c.height[objectKey{kind: 'l', ptr: reflect.ValueOf(x).Pointer()}] + case *std.Dict: + height += c.height[objectKey{kind: 'd', ptr: reflect.ValueOf(x).Pointer()}] + case *std.Set: + height += c.height[objectKey{kind: 's', ptr: reflect.ValueOf(x).Pointer()}] + case std.Tuple: + height += c.height[objectKey{kind: 't', ptr: reflect.ValueOf(x).Pointer(), len: len(x)}] + } + if height > c.height[parent] { + c.height[parent] = height + } +} diff --git a/lib/starlark/snapshot_test.go b/lib/starlark/snapshot_test.go new file mode 100644 index 0000000..e20f003 --- /dev/null +++ b/lib/starlark/snapshot_test.go @@ -0,0 +1,203 @@ +package starlark_test + +// Sections: unsupported host values; cycles and aliases; data quotas. + +import ( + "errors" + "math/big" + "strings" + "testing" + + mod "github.com/1set/starlet/lib/starlark" + std "go.starlark.net/starlark" +) + +type hostileValue struct{ called *bool } + +func (v hostileValue) String() string { *v.called = true; panic("String called") } +func (v hostileValue) Type() string { *v.called = true; panic("Type called") } +func (v hostileValue) Freeze() { *v.called = true; panic("Freeze called") } +func (v hostileValue) Truth() std.Bool { *v.called = true; panic("Truth called") } +func (v hostileValue) Hash() (uint32, error) { *v.called = true; panic("Hash called") } + +func TestEvalRejectsUnsupportedInput(t *testing.T) { + var list *std.List + var dict *std.Dict + var set *std.Set + called := false + values := []std.Value{nil, list, dict, set, hostileValue{&called}, std.NewBuiltin("callback", nil)} + for _, v := range values { + _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": std.NewList([]std.Value{v})}) + var e *mod.Error + if !errors.As(err, &e) || e.Phase != "input" || !strings.Contains(err.Error(), "x") { + t.Fatalf("%T: %v", v, err) + } + } + if called { + t.Fatal("input inspection invoked host behavior") + } + for _, key := range []string{"", "1x", "try", "x.y"} { + if _, err := mod.Eval(&std.Thread{}, "1", std.StringDict{key: std.None}); err == nil { + t.Fatal("accepted bad name", key) + } + } + vars := std.NewDict(1) + _ = vars.SetKey(std.MakeInt(1), std.None) + if _, err := call(t, "eval", "1", vars); err == nil { + t.Fatal("accepted nonstring variable name") + } +} + +func TestEvalCyclesAliasesAndQuota(t *testing.T) { + list := std.NewList(nil) + _ = list.Append(list) + if _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": list}); err == nil { + t.Fatal("accepted cycle") + } + if err := list.Append(std.None); err != nil { + t.Fatal("rejected input was frozen") + } + shared := std.NewList([]std.Value{std.MakeInt(1)}) + v, err := mod.Eval(&std.Thread{}, "(a, b)", std.StringDict{"a": shared, "b": shared}) + if err != nil { + t.Fatal(err) + } + items := v.(std.Tuple) + if items[0] != items[1] || items[0] == shared { + t.Fatal("aliases not privately preserved") + } + bigValue := std.MakeBigInt(new(big.Int).Lsh(big.NewInt(1), 4096)) + for _, value := range []std.Value{std.String(strings.Repeat("x", (1<<20)+1)), bigValue, std.NewList(make([]std.Value, 4097))} { + if _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": value}); err == nil { + t.Fatalf("accepted oversized %T", value) + } + } + var deep std.Value = std.None + for i := 0; i < 65; i++ { + deep = std.NewList([]std.Value{deep}) + } + if _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": deep}); err == nil { + t.Fatal("accepted deep graph") + } + if _, err := mod.Eval(&std.Thread{}, `"x" * 1048577`, nil); err == nil { + t.Fatal("accepted oversized output") + } +} + +func TestEvalContainerGraphBoundaries(t *testing.T) { + dict := std.NewDict(1) + _ = dict.SetKey(std.String("self"), dict) + tuple := make(std.Tuple, 1) + tuple[0] = tuple + for _, value := range []std.Value{dict, tuple} { + if _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": value}); err == nil { + t.Fatal("accepted cycle") + } + } + var shared std.Value = std.None + for i := 0; i < 40; i++ { + shared = std.NewList([]std.Value{shared}) + } + longer := shared + for i := 0; i < 40; i++ { + longer = std.NewList([]std.Value{longer}) + } + if _, err := mod.Eval(&std.Thread{}, "1", std.StringDict{"a": shared, "b": longer}); err == nil { + t.Fatal("memo bypassed path depth") + } + containers := []std.Value{std.Tuple(make([]std.Value, 4097)), std.Bytes(strings.Repeat("x", (1<<20)+1))} + largeDict := std.NewDict(2050) + largeSet := std.NewSet(4097) + for i := 0; i < 4097; i++ { + _ = largeSet.Insert(std.MakeInt(i)) + if i < 2050 { + _ = largeDict.SetKey(std.MakeInt(i), std.None) + } + } + containers = append(containers, largeDict, largeSet) + for _, value := range containers { + if _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": value}); err == nil { + t.Fatalf("accepted oversized %T", value) + } + } + for _, src := range []string{`[0] * 5000`, `int("f" * 1025, 16)`, `(lambda x: (x.append(x), x)[1])([])`} { + _, err := mod.Eval(&std.Thread{}, src, nil) + var e *mod.Error + if !errors.As(err, &e) || e.Phase != "output" { + t.Fatalf("%s: %v", src, err) + } + } + variables := make(std.StringDict, 4097) + for i := 0; i < 4097; i++ { + variables[strings.Repeat("a", i+1)] = std.None + } + if _, err := mod.Eval(&std.Thread{}, "1", variables); err == nil { + t.Fatal("accepted too many variables") + } + if _, err := mod.Eval(&std.Thread{}, "1", std.StringDict{strings.Repeat("a", (1<<20)+1): std.None}); err == nil || len(err.Error()) > 5000 { + t.Fatal("unbounded variable name rejection") + } + if _, err := mod.Eval(&std.Thread{}, "1", std.StringDict{strings.Repeat("a", 513): std.None}); err == nil || len(err.Error()) > 5000 { + t.Fatal("unbounded invalid identifier") + } + // Host mutation of a tuple after insertion can invalidate a native key. + // Reject the malformed graph rather than panic or silently lose the item. + for _, kind := range []string{"dict", "set"} { + key := std.Tuple{std.MakeInt(1)} + var value std.Value + if kind == "dict" { + d := std.NewDict(1) + _ = d.SetKey(key, std.None) + value = d + } else { + s := std.NewSet(1) + _ = s.Insert(key) + value = s + } + key[0] = std.NewList(nil) + if _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": value}); err == nil { + t.Fatal("accepted malformed", kind) + } + } + called := false + for _, kind := range []string{"dict", "set"} { + key := std.Tuple{std.MakeInt(1)} + var value std.Value + if kind == "dict" { + d := std.NewDict(1) + _ = d.SetKey(key, std.None) + value = d + } else { + s := std.NewSet(1) + _ = s.Insert(key) + value = s + } + key[0] = hostileValue{&called} + if _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": value}); err == nil { + t.Fatal("accepted invalid native key", kind) + } + } + if called { + t.Fatal("key validation executed host behavior") + } + inside := std.NewDict(1) + _ = inside.SetKey(std.String("tuple"), std.Tuple{std.MakeInt(1)}) + if _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": std.NewList([]std.Value{inside})}); err != nil { + t.Fatal(err) + } + set := std.NewSet(1) + _ = set.Insert(std.MakeInt(1)) + if _, err := mod.Eval(&std.Thread{}, "(a,b)", std.StringDict{"a": set, "b": set}); err != nil { + t.Fatal(err) + } + if _, err := mod.Eval(&std.Thread{}, "1", std.StringDict{"a": std.String(strings.Repeat("x", (1<<20)-1)), "b": std.None}); err == nil { + t.Fatal("ignored names in total bytes") + } + full := make([]std.Value, 4094) + for i := range full { + full[i] = std.None + } + if _, err := mod.Eval(&std.Thread{}, "x", std.StringDict{"x": std.Tuple{std.NewList(full), std.None}}); err == nil { + t.Fatal("ignored later graph edge") + } +} diff --git a/lib/starlark/source.go b/lib/starlark/source.go new file mode 100644 index 0000000..44c2dd3 --- /dev/null +++ b/lib/starlark/source.go @@ -0,0 +1,73 @@ +package starlark + +import ( + "fmt" + + "go.starlark.net/syntax" +) + +const ( + maxSourceBytes = 4096 + maxSourceCodeBytes = 512 + maxSourceASTDepth = 64 + maxSourceASTNodes = 512 +) + +// parseSource admits a small source before invoking the pinned recursive +// parser, then checks the resulting tree before resolution and compilation. +// Counting literal and comment bytes too is deliberately conservative: large +// data belongs in vars. These limits are not a repair of the upstream parser +// or a hard process memory/CPU boundary. +func parseSource(source string) (syntax.Expr, string, error) { + if len(source) > maxSourceBytes { + return nil, "source", fmt.Errorf("source exceeds %d bytes", maxSourceBytes) + } + codeBytes := 0 + for i := 0; i < len(source); i++ { + switch source[i] { + case ' ', '\t', '\r', '\n': + default: + codeBytes++ + } + } + if codeBytes > maxSourceCodeBytes { + return nil, "source", fmt.Errorf("source exceeds %d non-whitespace bytes", maxSourceCodeBytes) + } + + opts := syntax.FileOptions{Set: true} + expr, err := opts.ParseExpr("", source, 0) + if err != nil { + return nil, "parse", err + } + if err := checkSourceAST(expr); err != nil { + return nil, "source", err + } + return expr, "", nil +} + +// checkSourceAST prunes traversal before descending past its own depth bound. +func checkSourceAST(expr syntax.Expr) error { + var guardErr error + depth, nodes := 0, 0 + syntax.Walk(expr, func(node syntax.Node) bool { + if node == nil { + depth-- + return false + } + if guardErr != nil { + return false + } + nodes++ + if nodes > maxSourceASTNodes { + guardErr = fmt.Errorf("source AST exceeds %d nodes", maxSourceASTNodes) + return false + } + if depth == maxSourceASTDepth { + guardErr = fmt.Errorf("source AST exceeds depth %d", maxSourceASTDepth) + return false + } + depth++ + return true + }) + return guardErr +} diff --git a/lib/starlark/source_test.go b/lib/starlark/source_test.go new file mode 100644 index 0000000..a5dbc0c --- /dev/null +++ b/lib/starlark/source_test.go @@ -0,0 +1,107 @@ +package starlark + +// Sections: accepted expressions; source admission limits; parse errors; +// independently bounded AST traversal. + +import ( + "errors" + "strings" + "testing" + + "go.starlark.net/syntax" +) + +func TestParseSourceAccepted(t *testing.T) { + tests := []struct { + name string + source string + }{ + {"number", "1"}, + {"total_bytes_boundary", "1" + strings.Repeat(" ", maxSourceBytes-1)}, + {"code_bytes_boundary", `"` + strings.Repeat("a", maxSourceCodeBytes-2) + `"`}, + {"unicode_bytes_boundary", `"` + strings.Repeat("é", (maxSourceCodeBytes-2)/2) + `"`}, + {"json_whitespace", " \t\r\n1 \t\r\n"}, + {"unicode_string", `"你好"`}, + {"unicode_identifier", "名字"}, + {"comments", "# comment\n1 # tail\n"}, + {"raw_string", `r"\n"`}, + {"bytes", `b"\x00"`}, + {"triple_string", "\"\"\"first\nsecond\"\"\""}, + {"lambda", "(lambda x: x + 1)(2)"}, + {"comprehension", "[x for x in items if x]"}, + {"compound_data", `({"x": [1, 2]}, items[1:], set([1]))`}, + {"depth_boundary", strings.Repeat("(", maxSourceASTDepth-1) + "1" + strings.Repeat(")", maxSourceASTDepth-1)}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + expr, phase, err := parseSource(tt.source) + if err != nil || phase != "" || expr == nil { + t.Fatalf("parseSource = (%T, %q, %v); want expression and no error", expr, phase, err) + } + }) + } +} + +func TestParseSourceAdmissionLimits(t *testing.T) { + tests := []struct { + name string + source string + want string + }{ + {"total_bytes", "1" + strings.Repeat(" ", maxSourceBytes), "4096 bytes"}, + {"code_bytes", strings.Repeat("a", maxSourceCodeBytes+1), "512 non-whitespace bytes"}, + {"literal_bytes", `"` + strings.Repeat("a", maxSourceCodeBytes-1) + `"`, "512 non-whitespace bytes"}, + {"comment_bytes", "#" + strings.Repeat("a", maxSourceCodeBytes) + "\n1", "512 non-whitespace bytes"}, + {"unicode_counts_bytes", `"` + strings.Repeat("é", maxSourceCodeBytes/2) + `"`, "512 non-whitespace bytes"}, + {"vertical_tab_is_not_exempt", strings.Repeat("\v", maxSourceCodeBytes+1), "512 non-whitespace bytes"}, + {"form_feed_is_not_exempt", strings.Repeat("\f", maxSourceCodeBytes+1), "512 non-whitespace bytes"}, + {"nbsp_is_not_exempt", strings.Repeat("\u00a0", maxSourceCodeBytes), "512 non-whitespace bytes"}, + // These are deliberately rejected before invoking the recursive parser. + {"not_chain", strings.Repeat("not ", maxSourceCodeBytes/3+1) + "1", "512 non-whitespace bytes"}, + {"minus_chain", strings.Repeat("-", maxSourceCodeBytes+1) + "1", "512 non-whitespace bytes"}, + {"plus_chain", strings.Repeat("+", maxSourceCodeBytes+1) + "1", "512 non-whitespace bytes"}, + {"tilde_chain", strings.Repeat("~", maxSourceCodeBytes+1) + "1", "512 non-whitespace bytes"}, + {"lambda_chain", strings.Repeat("lambda: ", maxSourceCodeBytes/7+1) + "1", "512 non-whitespace bytes"}, + {"ternary_chain", strings.Repeat("1 if 1 else ", maxSourceCodeBytes/8+1) + "0", "512 non-whitespace bytes"}, + {"paren_chain", strings.Repeat("(", maxSourceCodeBytes/2+1) + "1" + strings.Repeat(")", maxSourceCodeBytes/2+1), "512 non-whitespace bytes"}, + {"ast_depth", strings.Repeat("(", maxSourceASTDepth) + "1" + strings.Repeat(")", maxSourceASTDepth), "depth 64"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + expr, phase, err := parseSource(tt.source) + if err == nil || phase != "source" || expr != nil || !strings.Contains(err.Error(), tt.want) { + t.Fatalf("parseSource = (%T, %q, %v); want source error containing %q", expr, phase, err, tt.want) + } + }) + } +} + +func TestParseSourceParseErrors(t *testing.T) { + for _, source := range []string{"", " \t\r\n", "1 +", "x = 1", "1; 2", "'unterminated", "[(1]", "load(\"x\", \"a\")", string([]byte{0xff})} { + t.Run(source, func(t *testing.T) { + expr, phase, err := parseSource(source) + var syntaxErr syntax.Error + if expr != nil || phase != "parse" || !errors.As(err, &syntaxErr) { + t.Fatalf("parseSource = (%T, %q, %T %v); want original syntax.Error", expr, phase, err, err) + } + }) + } +} + +func TestCheckSourceASTNodeLimit(t *testing.T) { + // Construct a flat tree directly: the admission byte limit is tighter + // than most source spellings of this defensive AST node boundary. + for _, count := range []int{maxSourceASTNodes - 1, maxSourceASTNodes, maxSourceASTNodes + 1} { + expr := &syntax.ListExpr{List: make([]syntax.Expr, count)} + for i := range expr.List { + expr.List[i] = &syntax.Ident{Name: "item"} + } + err := checkSourceAST(expr) + if count == maxSourceASTNodes-1 && err != nil { + t.Fatalf("tree with exactly %d nodes rejected: %v", maxSourceASTNodes, err) + } + if count >= maxSourceASTNodes && (err == nil || !strings.Contains(err.Error(), "512 nodes")) { + t.Fatalf("tree over node bound = %v, want node-limit error", err) + } + } +} diff --git a/lib/starlark/starlark.go b/lib/starlark/starlark.go new file mode 100644 index 0000000..cd639f3 --- /dev/null +++ b/lib/starlark/starlark.go @@ -0,0 +1,358 @@ +// Package starlark provides data-only, read-only Starlark expression evaluation. +// It uses explicit variables, preserves their native types, and does not expose +// caller functions, modules, host wrappers, or resource handles. This is not a +// process sandbox or a hard allocation limit; the caller owns execution limits. +package starlark + +import ( + "context" + "errors" + "fmt" + "sync" + "unicode" + "unicode/utf8" + + "go.starlark.net/resolve" + std "go.starlark.net/starlark" + "go.starlark.net/starlarkstruct" + "go.starlark.net/syntax" +) + +// ModuleName is the Starlark module name. The name expr is reserved for a +// possible separate Expr-language adapter; this module executes Starlark only. +const ModuleName = "starlark" + +// Error identifies the stage of a failed expression evaluation. Cause retains +// parser/resolver errors and EvalError backtraces for errors.As/errors.Is. +type Error struct { + Phase string + Kind string + Cause error +} + +func (e *Error) Error() string { + message, _ := diagnosticText(e.Cause.Error(), maxErrorMessage) + return "starlark.eval: " + e.Phase + ": " + message +} +func (e *Error) Unwrap() error { return e.Cause } + +func evalError(phase string, cause error) *Error { + return &Error{Phase: phase, Kind: phase, Cause: cause} +} + +var ( + moduleOnce sync.Once + module std.StringDict + // Capture the standard, immutable builtin instances before evaluation. + // Like upstream, this package requires Universe not be mutated concurrently + // with execution. A later replacement of an allowed name is not trusted. + pureBuiltins = captureBuiltins() + probeOnce sync.Once + threadProbe *std.Function +) + +func captureBuiltins() std.StringDict { + names := []string{"None", "True", "False", "abs", "any", "all", "bool", "bytes", "chr", "dict", "dir", "enumerate", "fail", "float", "getattr", "hasattr", "hash", "int", "len", "list", "max", "min", "ord", "range", "repr", "reversed", "set", "sorted", "str", "tuple", "type", "zip"} + result := make(std.StringDict, len(names)) + for _, name := range names { + result[name] = std.Universe[name] + } + return result +} + +func makeThreadProbe() *std.Function { + f, err := std.ExprFuncOptions(&syntax.FileOptions{Set: true}, "", "0", nil) + if err != nil { + panic(err) // A fixed integer literal cannot fail to compile. + } + f.Freeze() + return f +} + +// checkThread runs a constant, closed expression on the caller's existing VM. +// This checks its private cancellation/step state without inspecting internals, +// resetting limits, or relying on the wording of an EvalError. In particular, +// an OnMaxSteps panic propagates unchanged to the caller's execution boundary. +func checkThread(thread *std.Thread) error { + if thread == nil { + return evalError("input", fmt.Errorf("thread is nil")) + } + if ctx, ok := thread.Local("context").(context.Context); ok && ctx != nil { + if err := ctx.Err(); err != nil { + return evalError("execution", err) + } + } + probeOnce.Do(func() { threadProbe = makeThreadProbe() }) + if _, err := std.Call(thread, threadProbe, nil, nil); err != nil { + return evalError("execution", err) + } + return nil +} + +// LoadModule returns the starlark module containing eval and try_eval. +// Initialization is concurrency-safe; the returned module is frozen. +func LoadModule() (std.StringDict, error) { + moduleOnce.Do(func() { + mod := &starlarkstruct.Module{Name: ModuleName, Members: std.StringDict{ + "eval": std.NewBuiltin("starlark.eval", evaluationBuiltin(false)), + "try_eval": std.NewBuiltin("starlark.try_eval", evaluationBuiltin(true)), + }} + mod.Freeze() + module = std.StringDict{ModuleName: mod} + }) + return module, nil +} + +// Eval evaluates one Starlark expression against an owned, frozen copy of vars. +// The caller must provide an active or exclusively owned Thread and either an +// exclusively owned/synchronized variables graph or already-frozen native +// data. Merely avoiding writes does not make an unfrozen set safe to share: +// native iteration updates its bookkeeping. Values and names are checked +// before interpretation; results are copied, frozen native data only. +// +// Eval preserves the caller's cancellation and cumulative step accounting. +// It does not set a new step limit, recover caller panics, or capture locals. +func Eval(thread *std.Thread, source string, vars std.StringDict) (std.Value, error) { + if err := checkThread(thread); err != nil { + return std.None, err + } + expr, phase, err := parseSource(source) + if err != nil { + return std.None, evalError(phase, err) + } + if len(vars) > maxDataNodes { + return std.None, evalError("input", fmt.Errorf("too many variables")) + } + nameBytes := 0 + for name := range vars { + if len(name) > maxDataBytes-nameBytes { + return std.None, evalError("input", fmt.Errorf("variable names exceed data byte limit")) + } + nameBytes += len(name) + } + copy := newDataCopy(thread) + env := make(std.StringDict, len(vars)+len(std.Universe)) + names := vars.Keys() + for _, name := range names { + if err := copy.chargeBytes(len(name), "vars"); err != nil { + return std.None, evalError("input", err) + } + if !validName(name) { + preview, _ := diagnosticText(name, 64) + return std.None, evalError("input", fmt.Errorf("invalid variable name %q (%d bytes)", preview, len(name))) + } + value, err := copy.value(vars[name], "vars."+name, 0) + if err != nil { + return std.None, wrapInputError(err) + } + env[name] = value + } + // Only private copies are frozen, after the full input graph was accepted. + env.Freeze() + for name := range std.Universe { + if _, exists := env[name]; exists { + continue + } + if value, approved := pureBuiltins[name]; approved { + env[name] = value + } else { + env[name] = deniedBuiltin(name) + } + } + // Approved instances remain usable even if another host replaced or removed + // a Universe entry before execution. Data variables keep normal shadowing. + for name, value := range pureBuiltins { + if _, exists := env[name]; !exists { + env[name] = value + } + } + if err := checkThread(thread); err != nil { + return std.None, err + } + value, err := std.EvalExprOptions(&syntax.FileOptions{Set: true}, thread, expr, env) + if err != nil { + if terminal := checkThread(thread); terminal != nil { + return std.None, terminal + } + var own *Error + if errors.As(err, &own) { + return std.None, &Error{Phase: own.Phase, Kind: own.Kind, Cause: err} + } + var unresolved resolve.ErrorList + if errors.As(err, &unresolved) { + return std.None, evalError("resolve", err) + } + return std.None, evalError("runtime", err) + } + result, err := newDataCopy(thread).value(value, "result", 0) + if err != nil { + var terminal *Error + if errors.As(err, &terminal) { + return std.None, err + } + return std.None, evalError("output", err) + } + if err := checkThread(thread); err != nil { + return std.None, err + } + result.Freeze() + return result, nil +} + +func wrapInputError(err error) error { + var execution *Error + if errors.As(err, &execution) { + return err + } + return evalError("input", err) +} + +func validName(name string) bool { + if len(name) == 0 || len(name) > 512 || !utf8.ValidString(name) { + return false + } + for i, r := range name { + if r != '_' && !unicode.IsLetter(r) && (i == 0 || !unicode.IsDigit(r)) { + return false + } + } + expr, err := (&syntax.FileOptions{}).ParseExpr("", name, 0) + if err != nil { + return false + } + ident, ok := expr.(*syntax.Ident) + return ok && ident.Name == name +} + +func deniedBuiltin(name string) *std.Builtin { + return std.NewBuiltin(name, func(*std.Thread, *std.Builtin, std.Tuple, []std.Tuple) (std.Value, error) { + return std.None, &Error{Phase: "policy", Kind: "capability", Cause: fmt.Errorf("builtin %q is unavailable", name)} + }) +} + +func evaluationBuiltin(try bool) func(*std.Thread, *std.Builtin, std.Tuple, []std.Tuple) (std.Value, error) { + return func(thread *std.Thread, fn *std.Builtin, args std.Tuple, kwargs []std.Tuple) (std.Value, error) { + if err := checkThread(thread); err != nil { + return std.None, err + } + var sourceValue std.Value + var varsValue std.Value + err := std.UnpackArgs(fn.Name(), args, kwargs, "source", &sourceValue, "vars?", &varsValue) + vars := make(std.StringDict) + source, sourceOK := sourceValue.(std.String) + if err != nil { + err = evalError("arguments", err) + } else if !sourceOK { + err = evalError("input", fmt.Errorf("source must be a native string, got %T", sourceValue)) + } else if varsValue != nil { + dict, ok := varsValue.(*std.Dict) + if !ok || dict == nil { + err = evalError("input", fmt.Errorf("vars must be a native dict")) + } else if dict.Len() > maxDataNodes { + err = evalError("input", fmt.Errorf("too many variables")) + } else { + for _, pair := range dict.Items() { + key, ok := pair[0].(std.String) + if !ok { + err = evalError("input", fmt.Errorf("vars keys must be strings")) + break + } + vars[string(key)] = pair[1] + } + } + } + value := std.Value(std.None) + if err == nil { + value, err = Eval(thread, string(source), vars) + } + if terminal := checkThread(thread); terminal != nil { + return std.None, terminal + } + if err != nil { + var execution *Error + if errors.As(err, &execution) && execution.Phase == "execution" { + // Preserve a terminal failure even if the owner concurrently + // cleared the Thread cancellation before the final probe. + return std.None, err + } + if try { + return std.Tuple{std.None, errorInfo(err)}, nil + } + return std.None, err + } + if try { + return std.Tuple{value, std.None}, nil + } + return value, nil + } +} + +const ( + maxErrorMessage = 4096 + maxErrorFrames = 32 +) + +func diagnosticText(text string, limit int) (string, bool) { + if len(text) <= limit { + return text, false + } + const suffix = "... (truncated)" + end := limit - len(suffix) + for end > 0 && !utf8.RuneStart(text[end]) { + end-- + } + return text[:end] + suffix, true +} + +func errorInfo(err error) *std.Dict { + phase, kind := "runtime", "runtime" + var own *Error + if errors.As(err, &own) { + phase, kind = own.Phase, own.Kind + } + position := std.Value(std.None) + frames := std.Tuple{} + message, truncated := diagnosticText(err.Error(), maxErrorMessage) + var parse syntax.Error + var unresolved resolve.ErrorList + var runtime *std.EvalError + if errors.As(err, &parse) { + position = positionInfo(parse.Pos) + truncated = truncated || len(parse.Pos.Filename()) > 512 + } else if errors.As(err, &unresolved) && len(unresolved) > 0 { + position = positionInfo(unresolved[0].Pos) + truncated = truncated || len(unresolved[0].Pos.Filename()) > 512 + } else if errors.As(err, &runtime) { + start := 0 + if len(runtime.CallStack) > maxErrorFrames { + start = len(runtime.CallStack) - maxErrorFrames + truncated = true + } + for _, frame := range runtime.CallStack[start:] { + f := positionInfo(frame.Pos) + truncated = truncated || len(frame.Pos.Filename()) > 512 + name, shortened := diagnosticText(frame.Name, 256) + truncated = truncated || shortened + _ = f.SetKey(std.String("name"), std.String(name)) + frames = append(frames, f) + if frame.Pos.IsValid() && frame.Pos.Filename() != "" { + position = positionInfo(frame.Pos) + } + } + } + info := std.NewDict(6) + for _, pair := range []std.Tuple{{std.String("phase"), std.String(phase)}, {std.String("kind"), std.String(kind)}, {std.String("message"), std.String(message)}, {std.String("position"), position}, {std.String("frames"), frames}, {std.String("truncated"), std.Bool(truncated)}} { + _ = info.SetKey(pair[0], pair[1]) + } + info.Freeze() + return info +} + +func positionInfo(pos syntax.Position) *std.Dict { + d := std.NewDict(3) + file, _ := diagnosticText(pos.Filename(), 512) + _ = d.SetKey(std.String("file"), std.String(file)) + _ = d.SetKey(std.String("line"), std.MakeInt(int(pos.Line))) + _ = d.SetKey(std.String("column"), std.MakeInt(int(pos.Col))) + return d +} diff --git a/lib/starlark/starlark_test.go b/lib/starlark/starlark_test.go new file mode 100644 index 0000000..0eccb08 --- /dev/null +++ b/lib/starlark/starlark_test.go @@ -0,0 +1,419 @@ +package starlark_test + +// Sections: data isolation; result boundaries; errors; caller execution state. + +import ( + "context" + "errors" + "strings" + "sync" + "testing" + + mod "github.com/1set/starlet/lib/starlark" + std "go.starlark.net/starlark" + "go.starlark.net/syntax" +) + +func builtin(t *testing.T, name string) std.Value { + t.Helper() + m, err := mod.LoadModule() + if err != nil { + t.Fatal(err) + } + v, err := m[mod.ModuleName].(std.HasAttrs).Attr(name) + if err != nil || v == nil { + t.Fatalf("%s: %v", name, err) + } + return v +} + +func call(t *testing.T, name, source string, vars std.Value) (std.Value, error) { + t.Helper() + return std.Call(&std.Thread{}, builtin(t, name), std.Tuple{std.String(source), vars}, nil) +} + +func TestEvalReadOnlyData(t *testing.T) { + items := std.NewList([]std.Value{std.MakeInt(1), std.MakeInt(2)}) + vars := std.StringDict{"items": items, "name": std.String("Ada")} + v, err := mod.Eval(&std.Thread{}, `{"name": name.upper(), "values": [n * 2 for n in items]}`, vars) + if err != nil || v.String() != `{"name": "ADA", "values": [2, 4]}` { + t.Fatalf("%v, %v", v, err) + } + if err := items.Append(std.MakeInt(3)); err != nil { + t.Fatalf("parent was frozen: %v", err) + } + if v.String() != `{"name": "ADA", "values": [2, 4]}` { + t.Fatalf("result shares parent: %v", v) + } + if err := v.(*std.Dict).SetKey(std.String("bad"), std.None); err == nil { + t.Fatal("result must be frozen") + } + for _, src := range []string{`items.append(9)`, `items.clear()`} { + if _, err := mod.Eval(&std.Thread{}, src, vars); err == nil { + t.Fatal("accepted input mutation", src) + } + } + if items.String() != "[1, 2, 3]" { + t.Fatal(items) + } + v, err = mod.Eval(&std.Thread{}, `(lambda xs: (xs.append(8), xs))([7])`, nil) + if err != nil || v.String() != "(None, [7, 8])" { + t.Fatalf("private intermediate: %v, %v", v, err) + } +} + +func TestEvalResultBoundary(t *testing.T) { + for _, src := range []string{`lambda: 1`, `"abc".upper`, `{"nested": [len]}`} { + _, err := mod.Eval(&std.Thread{}, src, nil) + var e *mod.Error + if !errors.As(err, &e) || e.Phase != "output" { + t.Fatalf("%q: %v", src, err) + } + } + v, err := mod.Eval(&std.Thread{}, `(123456789012345678901234567890, b"abc", set([1, 2]), None)`, nil) + if err != nil { + t.Fatal(err) + } + tuple, ok := v.(std.Tuple) + if !ok || len(tuple) != 4 || tuple[0].Type() != "int" || tuple[1].Type() != "bytes" || tuple[2].Type() != "set" || tuple[3] != std.None { + t.Fatal(v) + } +} + +func TestEvalErrors(t *testing.T) { + for _, tc := range []struct{ source, phase string }{{"1 +", "parse"}, {"missing + 1", "resolve"}, {"1 // 0", "runtime"}} { + _, err := mod.Eval(&std.Thread{}, tc.source, nil) + var e *mod.Error + if !errors.As(err, &e) || e.Phase != tc.phase { + t.Fatalf("%q: %v", tc.source, err) + } + v, err := call(t, "try_eval", tc.source, std.NewDict(0)) + if err != nil { + t.Fatal(err) + } + pair, ok := v.(std.Tuple) + if !ok || len(pair) != 2 || pair[0] != std.None { + t.Fatalf("%v", v) + } + info, ok := pair[1].(*std.Dict) + if !ok { + t.Fatalf("not error data: %v", v) + } + phase, found, err := info.Get(std.String("phase")) + if err != nil || !found || phase != std.String(tc.phase) { + t.Fatal(info, err) + } + if err := info.SetKey(std.String("x"), std.None); err == nil { + t.Fatal("mutable error") + } + } + v, err := call(t, "try_eval", "None", std.NewDict(0)) + if err != nil || v.String() != "(None, None)" { + t.Fatalf("%v, %v", v, err) + } + if _, err := call(t, "eval", "1 // 0", std.NewDict(0)); err == nil { + t.Fatal("eval swallowed error") + } + if _, err := mod.Eval(nil, "1", nil); err == nil { + t.Fatal("accepted nil thread") + } + if _, err := call(t, "eval", "1", std.NewList(nil)); err == nil { + t.Fatal("accepted non-dict vars") + } +} + +func TestEvalBuiltinPolicy(t *testing.T) { + prints, touches := 0, 0 + thread := &std.Thread{Print: func(*std.Thread, string) { prints++ }} + for _, src := range []string{`print("bad")`, `getattr("abc", "upper")() if False else print("bad")`} { + if _, err := mod.Eval(thread, src, nil); err == nil { + t.Fatal("allowed print") + } + } + if prints != 0 { + t.Fatal("called parent Print") + } + std.Universe["dangerous_eval_test"] = std.NewBuiltin("dangerous_eval_test", func(*std.Thread, *std.Builtin, std.Tuple, []std.Tuple) (std.Value, error) { + touches++ + return std.None, nil + }) + defer delete(std.Universe, "dangerous_eval_test") + if _, err := mod.Eval(&std.Thread{}, "dangerous_eval_test()", nil); err == nil || touches != 0 { + t.Fatalf("dangerous builtin: %v/%d", err, touches) + } + v, err := mod.Eval(&std.Thread{}, `getattr("abc", "upper")()`, nil) + if err != nil || v != std.String("ABC") { + t.Fatalf("native getattr: %v, %v", v, err) + } + v, err = mod.Eval(&std.Thread{}, "len", std.StringDict{"len": std.MakeInt(7)}) + if err != nil || v.String() != "7" { + t.Fatalf("data shadow: %v, %v", v, err) + } + original := std.Universe["len"] + std.Universe["len"] = std.NewBuiltin("len", func(*std.Thread, *std.Builtin, std.Tuple, []std.Tuple) (std.Value, error) { + touches++ + return std.None, nil + }) + v, err = mod.Eval(&std.Thread{}, "len([1])", nil) + std.Universe["len"] = original + if err != nil || v.String() != "1" || touches != 0 { + t.Fatalf("replaced builtin: %v, %v, %d", v, err, touches) + } + delete(std.Universe, "len") + v, err = mod.Eval(&std.Thread{}, "len([1])", nil) + std.Universe["len"] = original + if err != nil || v.String() != "1" { + t.Fatalf("removed builtin: %v, %v", v, err) + } +} + +func TestEvalPreservesCallerState(t *testing.T) { + thread := &std.Thread{} + if _, err := mod.Eval(thread, "1 + 2", nil); err != nil { + t.Fatal(err) + } + steps := thread.ExecutionSteps() + if _, err := mod.Eval(thread, "3 + 4", nil); err != nil { + t.Fatal(err) + } + if thread.ExecutionSteps() <= steps { + t.Fatal("steps reset") + } + thread.Cancel("caller cancelled") + _, err := std.Call(thread, builtin(t, "try_eval"), std.Tuple{std.String("1 +")}, nil) + if err == nil || !strings.Contains(err.Error(), "caller cancelled") { + t.Fatalf("try swallowed cancellation: %v", err) + } + ctx, cancel := context.WithCancel(context.Background()) + cancel() + ctxThread := &std.Thread{} + ctxThread.SetLocal("context", ctx) + _, err = std.Call(ctxThread, builtin(t, "try_eval"), std.Tuple{std.String("1")}, nil) + if !errors.Is(err, context.Canceled) { + t.Fatalf("context cancellation: %v", err) + } + limitThread := &std.Thread{} + limitThread.SetMaxExecutionSteps(1) + _, err = std.Call(limitThread, builtin(t, "try_eval"), std.Tuple{std.String("1")}, nil) + if err == nil || !strings.Contains(err.Error(), "too many steps") { + t.Fatalf("try swallowed limit: %v", err) + } + panics := &std.Thread{} + panics.SetMaxExecutionSteps(1) + panics.OnMaxSteps = func(*std.Thread) { panic("parent limit") } + func() { + defer func() { + if recover() != "parent limit" { + t.Error("parent panic swallowed") + } + }() + _, _ = mod.Eval(panics, "1", nil) + }() +} + +func TestEvalArgumentsAndDiagnostics(t *testing.T) { + called := false + var list *std.List + for _, name := range []string{"eval", "try_eval"} { + for _, source := range []std.Value{nil, list, hostileValue{&called}, std.MakeInt(1)} { + v, err := std.Call(&std.Thread{}, builtin(t, name), std.Tuple{source}, nil) + if name == "eval" && err == nil || name == "try_eval" && (err != nil || v.(std.Tuple)[0] != std.None) { + t.Fatalf("%s(%T): %v, %v", name, source, v, err) + } + } + } + if called { + t.Fatal("source rejection executed host behavior") + } + for _, args := range []std.Tuple{nil, {std.String("1"), std.NewDict(0), std.None}} { + v, err := std.Call(&std.Thread{}, builtin(t, "try_eval"), args, nil) + if err != nil || v.(std.Tuple)[0] != std.None { + t.Fatalf("argument error: %v, %v", v, err) + } + } + v, err := std.Call(&std.Thread{}, builtin(t, "eval"), std.Tuple{std.String("2 + 3")}, nil) + if err != nil || v.String() != "5" { + t.Fatalf("omitted vars: %v, %v", v, err) + } + vars := std.NewDict(1) + _ = vars.SetKey(std.String("n"), std.MakeInt(5)) + v, err = std.Call(&std.Thread{}, builtin(t, "eval"), std.Tuple{std.String("n * 2")}, []std.Tuple{{std.String("vars"), vars}}) + if err != nil || v.String() != "10" { + t.Fatalf("keyword vars: %v, %v", v, err) + } + tooMany := std.NewDict(4097) + for i := 0; i < 4097; i++ { + _ = tooMany.SetKey(std.String(strings.Repeat("x", i+1)), std.None) + } + if _, err := call(t, "eval", "1", tooMany); err == nil { + t.Fatal("accepted too many dict variables") + } + v, err = call(t, "try_eval", `fail("é" * 10000)`, std.NewDict(0)) + if err != nil { + t.Fatal(err) + } + info := v.(std.Tuple)[1].(*std.Dict) + message, _, _ := info.Get(std.String("message")) + truncated, _, _ := info.Get(std.String("truncated")) + if len(string(message.(std.String))) > 4096 || truncated != std.True || !strings.Contains(string(message.(std.String)), "truncated") { + t.Fatal("unbounded diagnostic") + } + depth := 0 + var outer *std.Builtin + try := builtin(t, "try_eval") + outer = std.NewBuiltin("outer", func(th *std.Thread, _ *std.Builtin, _ std.Tuple, _ []std.Tuple) (std.Value, error) { + if depth < 64 { + depth++ + defer func() { depth-- }() + return std.Call(th, outer, nil, nil) + } + return std.Call(th, try, std.Tuple{std.String("1 // 0")}, nil) + }) + v, err = std.Call(&std.Thread{}, outer, nil, nil) + if err != nil { + t.Fatal(err) + } + info = v.(std.Tuple)[1].(*std.Dict) + frames, _, _ := info.Get(std.String("frames")) + truncated, _, _ = info.Get(std.String("truncated")) + if len(frames.(std.Tuple)) != 32 || truncated != std.True { + t.Fatal("unbounded call frames") + } + _, err = std.ExecFileOptions(&syntax.FileOptions{Set: true}, &std.Thread{}, strings.Repeat("p", 1024), `result = evaluator("1 // 0")`, std.StringDict{"evaluator": try}) + if err != nil { + t.Fatal(err) + } + // Inspect through a capturing wrapper so the outer filename is part of + // the diagnostic while the error itself remains inside try_eval. + var captured std.Value + capture := std.NewBuiltin("capture", func(_ *std.Thread, _ *std.Builtin, a std.Tuple, _ []std.Tuple) (std.Value, error) { + captured = a[0] + return std.None, nil + }) + _, err = std.ExecFileOptions(&syntax.FileOptions{Set: true}, &std.Thread{}, strings.Repeat("p", 1024), `capture(evaluator("1 // 0"))`, std.StringDict{"evaluator": try, "capture": capture}) + if err != nil { + t.Fatal(err) + } + info = captured.(std.Tuple)[1].(*std.Dict) + truncated, _, _ = info.Get(std.String("truncated")) + if truncated != std.True { + t.Fatal("long filename truncation not marked") + } +} + +func TestEvalConcurrentFrozenData(t *testing.T) { + set := std.NewSet(2) + _ = set.Insert(std.MakeInt(1)) + _ = set.Insert(std.MakeInt(2)) + vars := std.StringDict{"items": std.NewList([]std.Value{std.MakeInt(2), std.MakeInt(3)}), "tags": set} + vars.Freeze() + var group sync.WaitGroup + for i := 0; i < 8; i++ { + group.Add(1) + go func() { + defer group.Done() + v, err := mod.Eval(&std.Thread{}, `(sorted(tags), [n * 2 for n in items])`, vars) + if err != nil || v.String() != "([1, 2], [4, 6])" { + t.Errorf("%v, %v", v, err) + } + }() + } + group.Wait() +} + +func TestEvalBudgetBoundaries(t *testing.T) { + // Across entry, copy, execution and result publication checkpoints, a + // depleted caller budget must never turn into a successful try tuple. + for limit := uint64(1); limit <= 40; limit++ { + for _, source := range []string{"1 // 0", "list(range(100))"} { + thread := &std.Thread{} + thread.SetMaxExecutionSteps(limit) + value, err := std.Call(thread, builtin(t, "try_eval"), std.Tuple{std.String(source)}, nil) + if err != nil && !strings.Contains(err.Error(), "too many steps") { + t.Fatal(err) + } + if err == nil && value == nil { + t.Fatal("nil success") + } + } + } + thread := &std.Thread{} + thread.SetMaxExecutionSteps(3) + items := make([]std.Value, 100) + for i := range items { + items[i] = std.None + } + _, err := mod.Eval(thread, "x", std.StringDict{"x": std.NewList(items)}) + if err == nil || !strings.Contains(err.Error(), "too many steps") { + t.Fatalf("copy budget: %v", err) + } + t.Run("owner_clears_cancellation_after_failure", func(t *testing.T) { + caller := &std.Thread{} + caller.SetMaxExecutionSteps(1) + checkpoints := 0 + cleared := false + caller.OnMaxSteps = func(thread *std.Thread) { + checkpoints++ + // The fixed VM's closed integer probe has two instructions. + // Let the entry probe finish, cancel during Eval's next probe, + // then let the owner clear that state at the final checkpoint. + // try_eval must retain the error that has already occurred. + if checkpoints == 3 { + thread.Cancel("owner checkpoint cancellation") + } else if checkpoints > 3 { + thread.Uncancel() + cleared = true + } + } + value, err := std.Call(caller, builtin(t, "try_eval"), std.Tuple{std.String("1")}, nil) + var execution *mod.Error + if !cleared || value != std.None || !errors.As(err, &execution) || execution.Phase != "execution" || !strings.Contains(err.Error(), "owner checkpoint cancellation") { + t.Fatalf("lost prior execution error after owner reset: value=%v error=%v cleared=%v checkpoints=%d", value, err, cleared, checkpoints) + } + // The owner's reset is real: a later evaluation may succeed. It + // does not retroactively turn the failed try_eval into a tuple. + value, err = mod.Eval(caller, "7", nil) + if err != nil || value.String() != "7" { + t.Fatalf("owner did not clear cancellation: %v, %v", value, err) + } + }) +} + +func BenchmarkEval(b *testing.B) { + for _, name := range []string{"Scalar", "Nested", "TryError"} { + b.Run(name, func(b *testing.B) { + thread := &std.Thread{} + vars := std.StringDict{"qty": std.MakeInt(3), "items": std.NewList([]std.Value{std.MakeInt(1), std.MakeInt(2), std.MakeInt(3)})} + if name == "Scalar" { + vars = std.StringDict{"qty": std.MakeInt(3)} + } + module, err := mod.LoadModule() + if err != nil { + b.Fatal(err) + } + try, err := module[mod.ModuleName].(std.HasAttrs).Attr("try_eval") + if err != nil { + b.Fatal(err) + } + if _, err := mod.Eval(thread, "0", nil); err != nil { + b.Fatal(err) + } + b.ReportAllocs() + b.ResetTimer() + for i := 0; i < b.N; i++ { + var err error + switch name { + case "Scalar": + _, err = mod.Eval(thread, "qty * 2", vars) + case "Nested": + _, err = mod.Eval(thread, `{"values": [x * qty for x in items]}`, vars) + case "TryError": + _, err = std.Call(thread, try, std.Tuple{std.String("1 // 0")}, nil) + } + if err != nil { + b.Fatal(err) + } + } + }) + } +} diff --git a/module_test.go b/module_test.go index c7bbff4..278a1f4 100644 --- a/module_test.go +++ b/module_test.go @@ -18,7 +18,7 @@ import ( ) var ( - builtinModules = []string{"atom", "base64", "csv", "file", "go_idiomatic", "hashlib", "http", "json", "log", "math", "net", "path", "random", "re", "regex", "runtime", "serial", "stats", "string", "struct", "time"} + builtinModules = []string{"atom", "base64", "csv", "file", "go_idiomatic", "hashlib", "http", "json", "log", "math", "net", "path", "random", "re", "regex", "runtime", "serial", "starlark", "stats", "string", "struct", "time"} ) func TestListBuiltinModules(t *testing.T) { @@ -1446,3 +1446,38 @@ func TestDocCoverage(t *testing.T) { t.Errorf("%d module member(s) are not documented in their README — see the report above", len(missing)) } } + +// Starlark expression evaluation is an explicitly registered builtin module. +func TestBuiltinStarlarkEvaluation(t *testing.T) { + loader := starlet.GetBuiltinModule("starlark") + if loader == nil { + t.Fatal("starlark module is not registered") + } + cap, ok := starlet.GetBuiltinModuleCapability("starlark") + if !ok || cap != starlet.CapPure { + t.Fatalf("starlark capability = %v, %v; want CapPure", cap, ok) + } + mac := starlet.NewWithNames(nil, nil, []string{"starlark"}) + mac.SetMaxExecutionSteps(10000) + out, err := mac.RunScript([]byte(` +load("starlark", "eval", "try_eval") +items = [1, 2] +result = eval("{\"n\": len(items), \"text\": text.upper()}", vars={"items": items, "text": "ok"}) +_, failure = try_eval("items.append(3)", vars={"items": items}) +items.append(4) +value, success = try_eval("None") +`), nil) + if err != nil { + t.Fatal(err) + } + result, ok := out["result"].(map[interface{}]interface{}) + if !ok || result["n"] != int64(2) || result["text"] != "OK" { + t.Fatalf("unexpected expression result: %#v", out["result"]) + } + if out["failure"] == nil || out["success"] != nil || out["value"] != nil { + t.Fatalf("unexpected try results: %#v", out) + } + if !reflect.DeepEqual(out["items"], []interface{}{int64(1), int64(2), int64(4)}) { + t.Fatalf("parent items = %#v", out["items"]) + } +}