commit 0627d49425cfb576fa014cdb9d255adf9d5c12ad Author: what Date: Sat Sep 5 22:11:55 2026 +0800 feat: 嵌入式 JS 脚本引擎核心 用 goja 承载业务回调，让业务逻辑变更不必重新编译发布 Go 程序。脚本用 ESM + TypeScript 写，Go 侧按名字把它们当普通对象实例化并调用方法。 主要组成： - Engine 编译脚本、管配置，公开 API 不暴露任何 goja 类型 - Script 一份编译好的脚本 + 它的 VM 池，热更新时整体顶替 - Instance 独占一个 VM 的实例，状态留在 JS 侧 - Caller 自定义调用约定，把脚本函数适配成 Go 侧要的签名 - Scope 让同一个 ctx 下的多个脚本共享 Go 侧对象 - Extension 扩展接口：给脚本添全局对象，配套 TS 类型 - Overlay 多层 Loader 叠加，后面的盖前面的 几个关键取舍： - 源码一律先过 esbuild 打包成 ESM，再改写成立即执行函数。goja 不认 import/export，而业务脚本要能拆文件、用 TypeScript。 - VM 池化复用，但每个 VM 单线程。goja 的 Runtime 不是 goroutine 安全的。 - Go 侧函数返回的 error 在脚本里表现为抛异常，不占返回值位置。 - 脚本能看见的全局只有白名单放行的那些，且注入是惰性的——没读到的 全局根本不会被转换。 diff --git a/bundle.go b/bundle.go new file mode 100644 index 0000000..504aa4d --- /dev/null +++ b/bundle.go @@ -0,0 +1,161 @@ +package jscriptx + +import ( + "fmt" + "strings" + + "github.com/evanw/esbuild/pkg/api" +) + +// BundleOption 配置源码的打包方式。 +type BundleOption func(*bundleOptions) + +type bundleOptions struct { + resolveDir string + target api.Target + define map[string]string + nodePaths []string + alias map[string]string +} + +// WithResolveDir 给源码一个解析 import 的基准目录。不设时源码里不能有 import +// （单段源码没有文件系统上下文，esbuild 解析不了相对路径）。 +func WithResolveDir(dir string) BundleOption { + return func(o *bundleOptions) { o.resolveDir = dir } +} + +// WithBundleTarget 设置输出的 ECMAScript 版本，默认 ES2017。 +func WithBundleTarget(t api.Target) BundleOption { + return func(o *bundleOptions) { o.target = t } +} + +// WithBundleDefine 设置编译期常量替换。 +func WithBundleDefine(define map[string]string) BundleOption { + return func(o *bundleOptions) { o.define = define } +} + +// WithNodePaths 指定额外的 node_modules 搜索目录，相当于 Node 的 NODE_PATH。 +// 传进来的目录本身相当于一个 node_modules：包直接放在它下面，不要再套一层。 +// +// 没有同时配 WithResolveDir 时，会拿当前工作目录当解析起点——esbuild 需要一个起点 +// 才会启动模块解析，真正的查找仍然走这里给的目录。 +func WithNodePaths(paths ...string) BundleOption { + return func(o *bundleOptions) { o.nodePaths = append(o.nodePaths, paths...) } +} + +// WithAlias 把模块名映射到具体的文件或目录，绕过 node_modules 查找。 +func WithAlias(alias map[string]string) BundleOption { + return func(o *bundleOptions) { + if o.alias == nil { + o.alias = map[string]string{} + } + for k, v := range alias { + o.alias[k] = v + } + } +} + +// Bundle 把一段 ESM/TypeScript 源码打包成本库能直接执行的形式。 +// +// goja 没有 ES module 支持，也不认识 TypeScript，所有脚本都要先过这一步。 +// Engine.Compile 内部就是调它；自定义 Loader 如果返回的是原始源码，也用它处理。 +// +// filename 是这段源码的文件名，有两个实际作用：**扩展名决定按什么语法解析** +// （.ts/.mts 按 TypeScript，.json 按 JSON，其余按 TypeScript——它是 JS 的超集， +// 普通 JS 照样能过），以及作为 sourcemap 和报错里显示的位置。 +// +// 打包后的代码是自包含的 IIFE，模块导出挂在 ModuleGlobal 上，末尾补一句入口表达式。 +// 因为产物是 IIFE，**脚本必须有 export**——没有导出的顶层代码会被当成死代码摇掉。 +func Bundle(filename, source string, opts ...BundleOption) (string, error) { + o := &bundleOptions{target: api.ES2017} + for _, opt := range opts { + opt(o) + } + if o.resolveDir == "" && len(o.nodePaths) > 0 { + // NodePaths 是"额外去哪儿找"，esbuild 仍然需要一个起点才会启动解析流程， + // 没有起点时连 NodePaths 都不查。用当前工作目录当锚点，真正的查找还是走 + // NodePaths。（Alias 是直接映射，不受这个限制。） + o.resolveDir = "." + } + + res := api.Build(api.BuildOptions{ + Stdin: &api.StdinOptions{ + Contents: source, + Sourcefile: filename, + Loader: loaderFor(filename), + ResolveDir: o.resolveDir, + }, + Bundle: true, + // 用 ESM 格式而不是 IIFE：IIFE 会附带一整套 CommonJS interop helper， + // 每建一个 VM 都要重跑一遍。拿到 ESM 产物后由 FinalizeBundle 自己包成 + // 立即执行函数，见 esmwrap.go。 + Format: api.FormatESModule, + Target: o.target, + Define: o.define, + NodePaths: o.nodePaths, + Alias: o.alias, + Write: false, + Sourcemap: api.SourceMapInline, + SourcesContent: api.SourcesContentExclude, + LogLevel: api.LogLevelSilent, + }) + if len(res.Errors) > 0 { + return "", bundleError(filename, res.Errors, o.resolveDir) + } + if len(res.OutputFiles) == 0 { + return "", fmt.Errorf("打包 %s 没有产出", filename) + } + return FinalizeBundle(string(res.OutputFiles[0].Contents)), nil +} + +// FinalizeBundle 把 esbuild 的 ESM 产物改写成本库能直接执行的形式：一个立即执行函数， +// 完成值就是脚本的导出（default 优先，只有命名导出时是整个模块对象）。 +// +// 自定义 Loader 自己调 esbuild 打包时，产物也要过这一步，格式才对得上。 +// 怎么改写、为什么不直接用 esbuild 的 IIFE 格式，见 esmwrap.go。 +func FinalizeBundle(code string) string { + const marker = "//# sourceMappingURL=" + i := strings.LastIndex(code, marker) + if i < 0 { + return wrapESM(code) + } + // sourcemap 注释留在最后，包装只作用于代码部分 + return wrapESM(strings.TrimRight(code[:i], "\n")) + code[i:] +} + +// loaderFor 按文件名的扩展名挑解析方式。 +func loaderFor(filename string) api.Loader { + switch { + case strings.HasSuffix(filename, ".ts"), strings.HasSuffix(filename, ".mts"): + return api.LoaderTS + case strings.HasSuffix(filename, ".json"): + return api.LoaderJSON + default: + // 没有扩展名或是 .js 时按 TS 解析：TS 是 JS 的超集，普通 JS 照样能过， + // 顺便让不带扩展名的脚本名也能写类型注解。 + return api.LoaderTS + } +} + +// bundleError 把 esbuild 的报错整理成一条带位置和出路的错误。 +func bundleError(filename string, errs []api.Message, resolveDir string) error { + var b strings.Builder + fmt.Fprintf(&b, "打包 %s 失败", filename) + for i, e := range errs { + if i >= 5 { + fmt.Fprintf(&b, "\n …还有 %d 条错误", len(errs)-i) + break + } + b.WriteString("\n ") + if loc := e.Location; loc != nil { + fmt.Fprintf(&b, "%s:%d:%d: ", loc.File, loc.Line, loc.Column) + } + b.WriteString(e.Text) + // 最常见的坑：单段源码里写了 import 却没有解析基准目录 + if resolveDir == "" && strings.Contains(e.Text, "Could not resolve") { + b.WriteString("（这段源码没有解析 import 的基准目录：" + + "用 jscriptx/esm 子包按目录加载，或给 Compile 配 WithResolveDir）") + } + } + return fmt.Errorf("%s", b.String()) +} diff --git a/caller.go b/caller.go new file mode 100644 index 0000000..a0e510f --- /dev/null +++ b/caller.go @@ -0,0 +1,140 @@ +package jscriptx + +import ( + "context" + + "github.com/dop251/goja" +) + +// Caller 是在 VM 借出期间对脚本函数的操作入口。 +// +// 它存在的理由是：有些调用模式没法用 Call/CallInto 表达——典型的是「回调 + next」， +// 需要先看脚本函数声明了几个形参，再决定怎么调它、把哪个 Go 闭包传进去。这些都得在 +// 同一次 VM 借出期间完成，因为传给脚本的 Go 闭包只在那段时间里有效。 +// +// 拿它写一个自定义的调用约定： +// +// err := target.WithCall(ctx, "handle", func(c jscriptx.Caller) error { +// if c.Arity() == 2 { +// res, err := c.Call(model, next) // next 是 Go 闭包，脚本能直接调 +// … +// } +// return nil +// }) +// +// 框架自己的回调约定（比如 orm 那套三种签名）就是这么实现的，见 jscriptx/dispatch。 +// +// Caller 只在 do 回调执行期间有效，别存下来跨调用用。 +type Caller interface { + // Arity 返回脚本函数声明的形参个数（JS 函数的 length 属性）。 + // 靠它判断脚本写的是哪种形状，脚本就不用额外声明签名。 + Arity() int + + // Call 调用脚本函数。参数按 goja 的规则转换：Go 对象反射包装成脚本对象， + // Go 函数变成脚本能直接调的函数——「把 next 传给脚本」就是这么实现的。 + Call(args ...any) (Result, error) + + // Script 返回脚本名，拼错误信息时用得上。 + Script() string +} + +// Result 是脚本函数一次调用的返回值。 +// +// 它只在下一次 Call 之前有效——同一个 Caller 的多次调用复用同一个对象， +// 要留着以后用就先 Value() 或 Into() 取出来。 +type Result interface { + // IsEmpty 判断脚本有没有返回东西（undefined 或 null）。 + // 「1 个形参、没有返回值」这种纯副作用的写法靠它识别。 + IsEmpty() bool + + // Value 返回导出成 Go 值的结果。空返回值时是 nil。 + Value() any + + // Into 把返回值转换进 out 指向的变量（out 必须是非 nil 指针）， + // 目标是接口时要求返回值实现它。 + Into(out any) error +} + +// WithCall 借一个 VM，在借出期间把控制权交给 do。 +// +// 超时中断、panic 恢复、错误分类、VM 归还这些都跟普通调用一样，do 里只管发起调用。 +// do 返回的错误会被包成 *Error；想让调用方 errors.Is 得到，wrap 一个哨兵错误进去， +// 比如 ErrUnsupportedSignature。 +func (s *Script) WithCall(ctx context.Context, fn string, do func(Caller) error) error { + return withCaller(ctx, s, fn, do) +} + +// WithCall 同 Script.WithCall，只是在这个实例独占的 VM 上执行。 +func (i *Instance) WithCall(ctx context.Context, fn string, do func(Caller) error) error { + return withCaller(ctx, i, fn, do) +} + +func withCaller(ctx context.Context, r runner, fn string, do func(Caller) error) error { + return invoke(ctx, r, fn, nil, func(f *frame) error { + return do(&caller{f: f}) + }) +} + +type caller struct { + f *frame + // 复用同一个 result：一次 WithCall 里可能调好几次脚本函数， + // 每次都分配一个返回值对象不划算。所以 Result 只在下一次 Call 之前有效。 + res result +} + +func (c *caller) Arity() int { return int(c.f.arity()) } +func (c *caller) Script() string { return c.f.script.name } + +func (c *caller) Call(args ...any) (Result, error) { + v, err := c.f.callWith(args) + if err != nil { + return nil, err + } + c.res = result{f: c.f, v: v} + return &c.res, nil +} + +type result struct { + f *frame + v goja.Value +} + +func (r *result) IsEmpty() bool { return empty(r.v) } + +func (r *result) Value() any { + if empty(r.v) { + return nil + } + return r.v.Export() +} + +func (r *result) Into(out any) error { + if empty(r.v) { + return nil + } + if err := r.f.export(r.v, out); err != nil { + return newError(KindType, r.f.script.name, r.f.name, err, + "返回值无法转换成 %T（拿到的是 %T）", out, r.v.Export()) + } + return nil +} + +// Target 是能发起脚本调用的对象：*Script（从 VM 池借用，脚本无跨调用状态） +// 或 *Instance（独占一个 VM，脚本里的状态跨调用保持）。 +// +// 这个接口不对外开放实现，只是让 dispatch 这类函数能同时接受两者。 +type Target interface { + // Name 返回脚本名。 + Name() string + // Has 判断脚本里有没有这个函数。 + Has(fn string) bool + // Call 调用脚本函数，返回值导出成 Go 值。 + Call(ctx context.Context, fn string, args ...any) (any, error) + // CallInto 调用脚本函数，并把返回值转换进 out 指向的变量。 + CallInto(ctx context.Context, fn string, out any, args ...any) error + // WithCall 借一个 VM，在借出期间把控制权交给 do，用来实现自定义的调用约定。 + WithCall(ctx context.Context, fn string, do func(Caller) error) error + + // 未导出方法，接口不对外开放实现。 + owner() *Script +} diff --git a/console.go b/console.go new file mode 100644 index 0000000..13345f2 --- /dev/null +++ b/console.go @@ -0,0 +1,41 @@ +package jscriptx + +import ( + "context" + "fmt" + "log/slog" + "strings" +) + +// newConsole 造一个绑定到指定脚本的 console 对象，脚本里的 console.log 等 +// 直接落到结构化日志里，带上 script 字段，方便按脚本名检索。 +func newConsole(logger *slog.Logger, script string) map[string]any { + at := func(level slog.Level) func(args ...any) { + return func(args ...any) { + if !logger.Enabled(context.Background(), level) { + return + } + logger.LogAttrs(context.Background(), level, joinArgs(args), + slog.String("script", script), slog.String("source", "console")) + } + } + return map[string]any{ + "log": at(slog.LevelInfo), + "info": at(slog.LevelInfo), + "debug": at(slog.LevelDebug), + "warn": at(slog.LevelWarn), + "error": at(slog.LevelError), + } +} + +// joinArgs 按 console 的习惯用空格拼接参数。 +func joinArgs(args []any) string { + if len(args) == 0 { + return "" + } + parts := make([]string, 0, len(args)) + for _, a := range args { + parts = append(parts, fmt.Sprintf("%v", a)) + } + return strings.Join(parts, " ") +} diff --git a/doc.go b/doc.go new file mode 100644 index 0000000..509d70b --- /dev/null +++ b/doc.go @@ -0,0 +1,150 @@ +// Package jscriptx 用嵌入式 JS 引擎承载业务回调，让业务逻辑变更不必重新编译发布 Go 程序。 +// +// 脚本用 ESM + TypeScript 编写、按目录组织，Go 侧按路径把它们当普通对象实例化并调用方法。 +// 底层是 goja（纯 Go 的 JS 引擎）加 esbuild（纯 Go 的打包器），依赖就这两个， +// 公开 API 不暴露任何 goja 类型。 +// +// goja 的反射会自动包装 Go 对象，框架里的链式 API 在脚本里照原样写， +// 不需要为每个方法写胶水代码： +// +// resource.GetDBTable(user, req.WithPermission(req.ResAll)) +// .Where(db.C("name").Eq("测试产品")) +// .Select("name", "cost_price") +// +// # 基本用法 +// +// loader, err := esm.NewLoader("app/src") +// e, err := jscriptx.New( +// jscriptx.WithLoader(loader), +// jscriptx.WithAutoReload(true), +// jscriptx.WithGlobals(myWhitelist), +// jscriptx.WithTimeout(3*time.Second), +// ) +// +// obj, err := e.New(ctx, "Resource/ResCreateController", "产品") +// defer obj.Close() +// got, err := obj.Call(ctx, "Init") +// +// # 为什么需要打包 +// +// goja 的 ES6+ 支持相当完整（class 含私有字段和静态块、async/await、generator、解构、 +// 可选链、Proxy、BigInt 都能直接跑），但它没有 ES module——import/export 在 goja 的 +// token 表里是保留字，解析阶段就报错；TypeScript 也不在它的职责范围。 +// +// esbuild 只补这两件事：把 import 内联掉、把 TypeScript 转译掉。交给 goja 的最终产物 +// 是普通 JS 语法，不含任何模块系统的东西。打包只在加载和热更新时发生，不在调用路径上。 +// +// # 入口形态 +// +// 产物是自包含的立即执行函数，所以脚本必须有 export——没有导出的顶层代码会被当死代码摇掉。 +// 入口就是模块的导出： +// +// export default class DeviceHandler { // 由本库实例化，构造参数从 Go 侧传 +// constructor(deviceId) { this.count = 0 } +// onMessage(payload) { return ++this.count } +// } +// +// export default new DeviceHandler() // 直接用这个实例 +// export default { onMessage(p) { ... } } // 对象当实例，按方法名调用 +// export default function handle(x) { ... } // 单函数入口，用 DefaultFunc 调用 +// export function Options() { ... } // 只有命名导出时，整个模块当实例 +// +// 拿到实例的几种形态都是按方法名调用，this 绑定到实例，继承来的方法也找得到。 +// +// # 两种执行方式 +// +// 区别只有一个——脚本实例活多久： +// +// 方式 取 VM 实例生命周期 脚本里的 this.xxx +// Script.Call 从 VM 池借 = VM 生命周期 随时可能归零，只能当缓存 +// Script.New → Instance 独占一个 VM 由你 Close 决定 跨调用保持 +// +// 需要状态就 New 一个实例、用完 Close；不需要就直接 Call 走池。 +// +// 本库不代管实例的生命周期——没有按 key 复用、没有空闲回收。要长期持有（比如按设备 ID +// 存着），业务侧自己拿 map 存，跟 Go 版 controller 的写法一致。 +// +// 并发粒度：不同实例完全并行；同一个实例的多次调用串行——那是保住 this.xxx 必需的， +// 跟 Go 侧用 sync.Mutex 保护 struct 字段是一回事。 +// +// # 作用域：让多个脚本共享数据 +// +// 作用域通过 ctx 传递，只携带一段业务流程里要共享的东西，不管任何生命周期： +// +// st := store.New() +// ctx = jscriptx.WithScope(ctx, +// jscriptx.ScopeExtensions(st), +// jscriptx.ScopeGlobals(map[string]any{"user": u}), +// ) +// +// obj1, err := cartCtrl.New(ctx) // 两个 controller +// obj2, err := orderCtrl.New(ctx) // 同一个 ctx → 同一份 store +// +// 共享靠的是 Go 侧对象，不是共用 Runtime——共用 Runtime 会让作用域内所有脚本被迫串行， +// 那才是真的并发瓶颈。现在各脚本各跑各的，只是手里的 store 指向同一个 Go 对象。 +// +// 扩展就是「给脚本添一个全局对象」，实例由你创建（见 Extension）。Go 侧和脚本读写的 +// 天然是同一份，不用再取回来。本库不带内置扩展，扩展由调用方自己定义。 +// +// # 多返回值约定（脚本作者唯一需要额外理解的规则） +// +// Go 函数的多返回值到了 JS 侧会按下面的规则转换，这是 goja 的行为，本库沿用： +// +// - func() T → 脚本拿到裸值 +// - func() (T, error) → error 为 nil 时拿到裸值 T；非 nil 时变成 JS 异常， +// 脚本可以 try/catch，不 catch 就冒泡成本包的 KindRuntime 错误 +// - func() (A, B) → 脚本拿到数组 [A, B]，用下标取 +// - func() (A, B, error) → error 为 nil 时拿到数组 [A, B]；非 nil 时抛异常 +// +// 也就是说 error 永远不出现在返回值里，它只会变成异常。db 的 ToSQL() 是典型例子： +// +// var r = sd.ToSQL() // r[0] 是 SQL 字符串，r[1] 是参数数组 +// +// 另外 Go 的 nil 到脚本里是 null，不是 undefined。 +// +// # async 可以用，但没有事件循环 +// +// async 方法返回的 Promise 由本库自动解包，用起来跟同步方法一样。但 goja 没有事件循环， +// 脚本里等不了真正的异步（定时器、网络、IO）——那种 Promise 永远 pending，会得到 +// ErrPromisePending。异步的活交给 Go 侧做，脚本只写同步逻辑。 +// +// # 值不能跨出脚本边界 +// +// Call 的返回值和 CallInto 的目标都不允许是 JS 函数/闭包：那种值绑在 VM 上，跨出边界 +// 就失效了，本库会直接拒绝（ErrValueEscape）。需要回调语义用 WithCall，它在 VM 借出 +// 期间完成整个交互，见 Caller 和 ExampleCaller。 +// +// # 安全边界 +// +// 脚本能看见的东西，只有 WithGlobals 显式放行的那些，加上 JS 语言自带的内置对象 +// （goja 不提供文件、网络、require，也没有 setTimeout）。白名单对象注入时会逐层拷贝成 +// 只读 JS 对象，脚本改不动，也不会跨 VM 共享同一个可变的 Go map。 +// +// 本库不预设放行哪些 API——那取决于你的框架。原则是只放行「不带数据库连接、不能自己 +// 发起查询」的纯构造器和常量：放行构造列名/表名/字面量的那些，不放行能凭空造出查询 +// 数据集的（绕过资源层）、能往 SQL 里塞裸片段的（可以挂子查询探测别的表）、 +// 以及任何数据库连接对象。脚本要碰数据，由 Go 侧把已经过权限包装的资源对象当参数传进去。 +// +// # 失控脚本 +// +// 每次调用都带超时（WithTimeout，默认 5 秒）。超时或调用方 context 取消时，会从另一个 +// goroutine 中断脚本执行，死循环也能断掉。被中断过或 panic 过的 VM 直接丢弃不回池， +// 避免状态污染。 +// +// 脚本执行期间的 panic（脚本里的类型错误、注入进去的 Go 方法内部 panic）都会被 recover +// 成 *Error 返回，不会掀翻调用方的 goroutine。 +// +// # 错误 +// +// 所有错误都是 *Error，带 Kind 分类、脚本名、函数名、脚本侧调用栈（行列号）和调用参数 +// 摘要，并实现了 slog.LogValuer： +// +// if err != nil { +// logger.Error("脚本执行失败", slog.Any("err", err)) +// } +// +// 行号指向 .ts 源文件而不是打包产物——esbuild 输出 inline sourcemap，goja 自带 sourcemap 支持。 +// +// 也可以用 errors.Is 匹配 ErrTimeout、ErrFuncNotFound、ErrScriptNotFound、ErrValueEscape +// 等哨兵错误。 +package jscriptx diff --git a/engine.go b/engine.go new file mode 100644 index 0000000..3e81ce1 --- /dev/null +++ b/engine.go @@ -0,0 +1,355 @@ +package jscriptx + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "errors" + "fmt" + "log/slog" + "runtime" + "sync" + "time" + + "github.com/dop251/goja" +) + +const ( + // DefaultTimeout 是单次脚本调用的默认时限，超过就中断脚本。 + DefaultTimeout = 5 * time.Second + // DefaultMaxCallStackSize 限制脚本的调用栈深度，防止递归打爆 Go 栈。 + DefaultMaxCallStackSize = 2000 +) + +// Engine 是脚本引擎，持有全局白名单、执行策略和脚本缓存。 +// 一个进程通常只需要一个 Engine，它本身并发安全。 +type Engine struct { + globals map[string]any + timeout time.Duration + maxVMs int + maxStack int + logger *slog.Logger + + loader Loader + autoReload bool + + // WithLoader 收下的层，New 里合成 loader；Option 没有出错的地方， + // 校验只能推迟到那时候。 + loaderLayers []Loader + + bundleOpts []BundleOption + + mu sync.Mutex + scripts map[string]*Script + closed bool +} + +// New 创建引擎。全局白名单里的名字不合法时返回错误。 +func New(opts ...Option) (*Engine, error) { + e := &Engine{ + globals: map[string]any{}, + timeout: DefaultTimeout, + maxVMs: runtime.GOMAXPROCS(0) * 2, + maxStack: DefaultMaxCallStackSize, + logger: slog.Default(), + scripts: map[string]*Script{}, + } + for _, opt := range opts { + opt(e) + } + if e.maxVMs < 1 { + e.maxVMs = 1 + } + if err := e.resolveLoader(); err != nil { + return nil, err + } + for name := range e.globals { + if !validIdent(name) { + return nil, fmt.Errorf("%w: 全局名 %q 不是合法的 JS 标识符", ErrBadGlobal, name) + } + } + return e, nil +} + +// resolveLoader 把 WithLoader 收下的层合成一个 Loader。 +func (e *Engine) resolveLoader() error { + switch len(e.loaderLayers) { + case 0: + return nil + case 1: + e.loader = e.loaderLayers[0] + if e.loader == nil { + return errors.New("jscriptx: WithLoader 收到 nil") + } + default: + o, err := Overlay(e.loaderLayers...) + if err != nil { + return err + } + e.loader = o + } + e.loaderLayers = nil + return nil +} + +// Compile 用一段 ESM/TypeScript 源码注册脚本：先经 esbuild 打包，再交给 goja 编译， +// 结果进缓存，之后 Script(name) 能取到。同名脚本会被替换，旧的 VM 池随即释放 +// （已经借出去的调用不受影响）。 +// +// 源码必须有 export——产物是 IIFE，没有导出的顶层代码会被当死代码摇掉。 +// 源码里要写 import 的话，得用 jscriptx/esm 子包按目录加载，或者配 WithResolveDir +// 给一个解析基准目录。 +func (e *Engine) Compile(name, source string) (*Script, error) { + e.mu.Lock() + defer e.mu.Unlock() + if e.closed { + return nil, newError(KindClosed, name, "", ErrClosed, "引擎已关闭") + } + return e.compileLocked(name, source, hashVersion(source), false) +} + +// Script 按名字取脚本：命中缓存直接返回；没命中就走 Loader 加载并编译。 +// 打开了 WithAutoReload 时，每次都会跟 Loader 核对版本号，变了就重编译。 +func (e *Engine) Script(name string) (*Script, error) { + e.mu.Lock() + defer e.mu.Unlock() + if e.closed { + return nil, newError(KindClosed, name, "", ErrClosed, "引擎已关闭") + } + + cached, ok := e.scripts[name] + if ok && !e.autoReload { + return cached, nil + } + if e.loader == nil { + if ok { + return cached, nil + } + return nil, newError(KindNotFound, name, "", ErrScriptNotFound, + "没有配置 Loader，也没有通过 Compile 注册过这个脚本") + } + return e.loadLocked(name, cached) +} + +// Reload 强制重新从 Loader 加载并编译，不管版本号有没有变。 +func (e *Engine) Reload(name string) (*Script, error) { + e.mu.Lock() + defer e.mu.Unlock() + if e.closed { + return nil, newError(KindClosed, name, "", ErrClosed, "引擎已关闭") + } + if e.loader == nil { + return nil, newError(KindLoad, name, "", ErrScriptNotFound, "没有配置 Loader，无法重新加载") + } + return e.loadLocked(name, nil) +} + +// Invalidate 把脚本从缓存里剔除并释放它的 VM 池，下次 Script 会重新加载。 +func (e *Engine) Invalidate(name string) { + e.mu.Lock() + defer e.mu.Unlock() + if s, ok := e.scripts[name]; ok { + delete(e.scripts, name) + s.Close() + } +} + +// Names 返回当前缓存里的脚本名。 +func (e *Engine) Names() []string { + e.mu.Lock() + defer e.mu.Unlock() + out := make([]string, 0, len(e.scripts)) + for name := range e.scripts { + out = append(out, name) + } + return out +} + +// Close 关闭引擎，释放所有脚本的 VM 池。之后再取脚本会报 ErrClosed。 +func (e *Engine) Close() { + e.mu.Lock() + defer e.mu.Unlock() + e.closed = true + for name, s := range e.scripts { + s.Close() + delete(e.scripts, name) + } +} + +// compileLocked 编译并替换缓存里的同名脚本。调用方必须持有 e.mu。 +// +// prepared 为 true 表示源码已经过打包（Loader 自己做过了），跳过这一步—— +// 对已经是 IIFE 的产物再打包一次是纯浪费。 +func (e *Engine) compileLocked(name, source, version string, prepared bool) (*Script, error) { + if !prepared { + // 脚本名同时当文件名传给打包器：扩展名（.ts/.json）决定按什么语法解析， + // 也是 sourcemap 和报错里显示的位置。 + bundled, err := Bundle(name, source, e.bundleOpts...) + if err != nil { + return nil, newError(KindCompile, name, "", err, "脚本打包失败") + } + source = bundled + } + + // 传 false = 不强制严格模式。 + // + // 注意产物里**没有** "use strict"：esbuild 输出 ESM 格式时不加这个指令， + // wrapESM 包成 IIFE 时也没加。所以脚本跑在非严格模式下，后果之一是给只读 + // 全局赋值会**静默失败**而不是抛错（见 lazyglobal_test.go 的断言）。 + // + // 想改成严格模式就把这里传 true，但那是行为变更：脚本里任何依赖非严格语义的 + // 写法（给未声明变量赋值、with、八进制字面量……）都会开始报错。 + prog, err := goja.Compile(name, source, false) + if err != nil { + return nil, newError(KindCompile, name, "", err, "脚本编译失败") + } + + s := &Script{ + engine: e, + name: name, + version: version, + prog: prog, + pool: make(chan *vmHandle, e.maxVMs), + } + if old, ok := e.scripts[name]; ok { + old.Close() + } + e.scripts[name] = s + return s, nil +} + +// bind 把白名单全局对象注入到一个新建的 VM 里。 +// extra 是这个 VM 专属的额外全局（作用域带来的扩展），可以为 nil； +// 它跟白名单同样按只读注入，同名时以 extra 为准。 +// +// 注入是**惰性**的：这里只装一个 getter，脚本第一次读到那个名字才把值转成 +// JS 对象。一个脚本通常只用得上少数几个扩展，而 freeze 要把每个方法都包装成 +// JS 函数——用不到的那些不该在每次建 VM 时都付一遍这个成本。见 lazyGlobal。 +func (e *Engine) bind(rt *goja.Runtime, script string, extra map[string]any) error { + global := rt.GlobalObject() + for name, val := range e.globals { + if _, overridden := extra[name]; overridden { + continue + } + if err := e.lazyGlobal(rt, global, name, val); err != nil { + return newError(KindBind, script, "", err, "注入全局对象 %q 失败", name) + } + } + for name, val := range extra { + if err := e.lazyGlobal(rt, global, name, val); err != nil { + return newError(KindBind, script, "", err, "注入会话全局对象 %q 失败", name) + } + } + if e.logger != nil { + _, taken := e.globals["console"] + if _, t2 := extra["console"]; t2 { + taken = true + } + if !taken { + if err := e.lazyGlobal(rt, global, "console", newConsole(e.logger, script)); err != nil { + return newError(KindBind, script, "", err, "注入 console 失败") + } + } + } + return nil +} + +// lazyGlobal 装一个惰性只读全局：脚本第一次读它才 freeze，之后复用。 +// +// 为什么惰性：freeze 要把 map 里每个方法都包装成 JS 函数对象，而一个脚本通常只用 +// 得上少数几个扩展。急切注入的话，每建一个 VM 都要为**所有**扩展付这份成本—— +// 实测这是脚本层剩余开销里最大的一块。 +// +// 缓存放在闭包里，不加锁：getter 只在脚本执行期间被调用，而那时这个 VM 是被独占的 +// （实例持着自己的锁，池化的 VM 同时只有一个借用者）。goja.Value 也跨不了 Runtime， +// 所以这份缓存天然是每 VM 一份。 +// +// 只给 getter 不给 setter，效果等同原来的 writable=false：脚本赋值时没有 setter 可调。 +// 产物跑在非严格模式下（见 compileLocked 那里的说明），所以赋值是**静默失败**—— +// 不抛错，值也不变。configurable 同样保持 false，删不掉也重定义不了。 +// +// 代价是 freeze 的错误从"建 VM 时返回 Go 错误"变成"脚本读它时抛 JS 异常"。 +// freeze 只在属性名不合法时才会失败，而 New() 里的 validIdent 已经挡过一道， +// 实际碰不到。 +func (e *Engine) lazyGlobal(rt *goja.Runtime, global *goja.Object, name string, val any) error { + var ( + cached goja.Value + failed error + ) + getter := rt.ToValue(func(goja.FunctionCall) goja.Value { + if cached == nil && failed == nil { + cached, failed = e.freeze(rt, val) + } + if failed != nil { + panic(rt.NewGoError(failed)) + } + return cached + }) + return global.DefineAccessorProperty(name, getter, nil, goja.FLAG_FALSE, goja.FLAG_TRUE) +} + +// freeze 把 map[string]any 递归转成只读的 JS 对象，其他值原样交给 goja 包装。 +// +// 直接 rt.Set(name, someMap) 会把同一个 Go map 暴露给每个 VM：脚本一句 +// db.C = null 既能污染别的 VM，又是实打实的数据竞争。这里每个 VM 都拿到 +// 自己的一份不可写、不可重定义的对象。 +func (e *Engine) freeze(rt *goja.Runtime, val any) (goja.Value, error) { + m, ok := val.(map[string]any) + if !ok { + return rt.ToValue(val), nil + } + obj := rt.NewObject() + for k, v := range m { + child, err := e.freeze(rt, v) + if err != nil { + return nil, err + } + if err := defineReadOnly(obj, k, child); err != nil { + return nil, err + } + } + return obj, nil +} + +func defineReadOnly(obj *goja.Object, name string, v goja.Value) error { + return obj.DefineDataProperty(name, v, goja.FLAG_FALSE, goja.FLAG_FALSE, goja.FLAG_TRUE) +} + +// validIdent 校验全局名是不是合法的 JS 标识符（只允许 ASCII 字母、数字、_ 和 $）。 +func validIdent(s string) bool { + if s == "" { + return false + } + for i, r := range s { + switch { + case r == '_' || r == '$': + case r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z': + case r >= '0' && r <= '9': + if i == 0 { + return false + } + default: + return false + } + } + return true +} + +func hashVersion(source string) string { + sum := sha256.Sum256([]byte(source)) + return hex.EncodeToString(sum[:8]) +} + +// New 是 Script(name) + Script.New(ctx, args...) 的快捷方式：按名字取脚本， +// 实例化它导出的 class，构造参数直接传给 constructor。 +// +// ctrl, err := e.New(ctx, "PkgVersion/PkgImportController") +// defer ctrl.Close() +// got, err := ctrl.Call(ctx, "Init") +func (e *Engine) New(ctx context.Context, name string, ctorArgs ...any) (*Instance, error) { + s, err := e.Script(name) + if err != nil { + return nil, err + } + return s.New(ctx, ctorArgs...) +} diff --git a/engine_option.go b/engine_option.go new file mode 100644 index 0000000..6272709 --- /dev/null +++ b/engine_option.go @@ -0,0 +1,86 @@ +package jscriptx + +import ( + "log/slog" + "time" +) + +// 引擎的配置项都在这个文件里，一处看全 New 能配什么。 +// +// 另有两组独立的选项：BundleOption（打包源码，见 bundle.go）由 WithBundleOptions +// 带进来；ScopeOption（每次调用的作用域，见 scope.go）跟着 ctx 走，不属于引擎配置。 + +// Option 是 New 的配置项。 +type Option func(*Engine) + +// WithGlobals 追加暴露给脚本的全局对象白名单。可以多次调用，同名后者覆盖前者。 +// +// value 为 map[string]any 时会被注入成一个只读的 JS 对象（逐层递归）， +// 脚本改不动它，多个 VM 之间也不会共享同一个可变的 Go map。 +func WithGlobals(globals map[string]any) Option { + return func(e *Engine) { + for k, v := range globals { + e.globals[k] = v + } + } +} + +// WithGlobal 暴露单个全局对象。 +func WithGlobal(name string, value any) Option { + return func(e *Engine) { e.globals[name] = value } +} + +// WithTimeout 设置单次调用的时限，超时后脚本会被强制中断，调用方拿到 KindTimeout 错误。 +// 传 0 表示不限时——只在明确知道脚本可信时才这么做。 +func WithTimeout(d time.Duration) Option { + return func(e *Engine) { e.timeout = d } +} + +// WithMaxVMs 设置每个脚本最多缓存多少个 VM 实例。这是缓存上限不是并发上限： +// 并发超过它时会临时新建 VM，用完直接丢弃，不会阻塞调用。 +func WithMaxVMs(n int) Option { + return func(e *Engine) { e.maxVMs = n } +} + +// WithMaxCallStackSize 设置脚本的最大调用栈深度，传 0 用 goja 默认值。 +func WithMaxCallStackSize(n int) Option { + return func(e *Engine) { e.maxStack = n } +} + +// WithLogger 设置日志器，脚本里的 console.* 会打到这里，带上 script 字段。 +// 传 nil 表示不注入 console。 +func WithLogger(l *slog.Logger) Option { + return func(e *Engine) { e.logger = l } +} + +// WithLoader 设置脚本源码的来源，Engine.Script 会用它按名字取脚本。 +// 本库只定义 Loader 接口，具体从文件、数据库还是配置中心读由调用方实现。 +// +// 可以给多个，它们叠成一层层的，**后面的盖前面的**——取脚本时从最后一层往前找， +// 谁先有就用谁的。把"定制层"放最后，业务侧放一份同名脚本就能改写默认实现： +// +// base, _ := esm.NewLoader("app/src") +// custom, _ := esm.NewLoader("custom/src") // 配置可以跟 base 完全不同 +// +// e, err := jscriptx.New(jscriptx.WithLoader(base, custom)) // custom 盖 base +// +// 每层是独立的 Loader，各有各的配置（入口规则、目标版本、node_modules 位置、 +// 扩展模块），来源也可以不同——一层来自磁盘目录，另一层来自数据库都行。 +// 多次调用 WithLoader 会继续往后叠，效果跟一次传多个一样。 +// +// 叠多层时各层的 Prepared 必须一致，否则 New 报错，原因见 Overlay。 +func WithLoader(loaders ...Loader) Option { + return func(e *Engine) { e.loaderLayers = append(e.loaderLayers, loaders...) } +} + +// WithAutoReload 打开后，每次 Engine.Script 都会问一次 Loader 拿版本号， +// 版本变了就重新编译并换掉旧的 VM 池——这是"改脚本不重启进程"的开关。 +// 代价是每次取脚本都会调一次 Loader.Load，实现方自己保证这个调用足够轻。 +func WithAutoReload(on bool) Option { + return func(e *Engine) { e.autoReload = on } +} + +// WithBundleOptions 配置 Compile 打包源码时的行为，比如 WithResolveDir。 +func WithBundleOptions(opts ...BundleOption) Option { + return func(e *Engine) { e.bundleOpts = append(e.bundleOpts, opts...) } +} diff --git a/errors.go b/errors.go new file mode 100644 index 0000000..a498e49 --- /dev/null +++ b/errors.go @@ -0,0 +1,367 @@ +package jscriptx + +import ( + "context" + "errors" + "fmt" + "log/slog" + "strconv" + "strings" + + "github.com/dop251/goja" +) + +// 哨兵错误，配合 errors.Is 使用。 +var ( + // ErrScriptNotFound 找不到脚本（Loader 没有这个名字，也没被 Compile 注册过）。 + ErrScriptNotFound = errors.New("jscriptx: 脚本不存在") + // ErrFuncNotFound 脚本里找不到要调用的函数，或者那个名字不是函数。 + ErrFuncNotFound = errors.New("jscriptx: 脚本里没有这个函数") + // ErrTimeout 脚本执行超过配置时限，已被强制中断。 + ErrTimeout = errors.New("jscriptx: 脚本执行超时") + // ErrInterrupted 脚本被中断，但拿不到更具体的原因。 + ErrInterrupted = errors.New("jscriptx: 脚本被中断") + // ErrClosed 脚本或引擎已经关闭。 + ErrClosed = errors.New("jscriptx: 已关闭") + // ErrUnsupportedSignature 回调函数的形参个数不在 Dispatch 支持的范围内。 + ErrUnsupportedSignature = errors.New("jscriptx: 不支持的回调签名") + // ErrValueEscape 脚本试图把只在 VM 内部有效的值（函数/闭包）传到 Go 侧。 + ErrValueEscape = errors.New("jscriptx: 该值不能跨出脚本边界") + // ErrBadGlobal 全局白名单配置不合法。 + ErrBadGlobal = errors.New("jscriptx: 全局白名单配置不合法") + // ErrPromiseRejected async 方法返回的 Promise 被 reject。 + ErrPromiseRejected = errors.New("jscriptx: Promise 被 reject") + // ErrPromisePending async 方法返回的 Promise 一直没完成（goja 没有事件循环）。 + ErrPromisePending = errors.New("jscriptx: Promise 未完成") +) + +// Kind 是错误分类，用于结构化日志过滤和调用方分流处理。 +type Kind string + +const ( + KindLoad Kind = "load" // 加载脚本源码失败 + KindCompile Kind = "compile" // 编译（语法解析）失败 + KindBind Kind = "bind" // 注入全局白名单失败 + KindNotFound Kind = "not_found" // 脚本或函数不存在 + KindRuntime Kind = "runtime" // 脚本运行期抛出异常 + KindTimeout Kind = "timeout" // 超时被中断 + KindCanceled Kind = "canceled" // 调用方 context 被取消 + KindPanic Kind = "panic" // Go 侧 panic，已兜住转成 error + KindType Kind = "type" // 返回值/参数类型不匹配 + KindSignature Kind = "signature" // 回调签名不受支持 + KindClosed Kind = "closed" // 脚本已关闭 +) + +// Frame 是脚本调用栈的一帧。从 goja 的栈信息里摘出来重新包装， +// 避免把 goja 类型暴露到本库的公开 API 上。 +type Frame struct { + Source string // 脚本名 + Func string // 函数名，匿名函数为空 + Line int + Column int +} + +func (f Frame) String() string { + name := f.Func + if name == "" { + name = "" + } + return fmt.Sprintf("%s (%s:%d:%d)", name, f.Source, f.Line, f.Column) +} + +// Error 是本库对外抛出的统一错误类型，带齐排查现场需要的上下文： +// 哪个脚本、哪个函数、脚本里哪一行、当时的调用参数是什么。 +// 它实现了 slog.LogValuer，slog.Any("err", err) 就能摊平成结构化字段。 +type Error struct { + Kind Kind // 错误分类 + Script string // 脚本名 + Func string // 被调用的函数名，可能为空 + Msg string // 人类可读的说明 + Args []string // 调用参数摘要（已截断，只用于排查，不保证可反序列化） + Stack []Frame // 脚本侧调用栈，可能为空 + Value any // 脚本 throw 出来的原始值（已导出成 Go 值） + GoStack string // Go 侧调用栈，仅 KindPanic 时填充 + Cause error // 底层错误，errors.Is/As 沿这条链走 +} + +func (e *Error) Error() string { + var b strings.Builder + b.WriteString("jscriptx: 脚本 ") + b.WriteString(strconv.Quote(e.Script)) + if e.Func != "" { + b.WriteString(" 函数 ") + b.WriteString(strconv.Quote(e.Func)) + } + b.WriteString(" [") + b.WriteString(string(e.Kind)) + b.WriteString("]") + if e.Msg != "" { + b.WriteString(": ") + b.WriteString(e.Msg) + } + if len(e.Stack) > 0 { + b.WriteString(" at ") + b.WriteString(e.Stack[0].String()) + } + if e.Cause != nil && e.Cause.Error() != e.Msg { + b.WriteString(" (") + b.WriteString(e.Cause.Error()) + b.WriteString(")") + } + return b.String() +} + +func (e *Error) Unwrap() error { return e.Cause } + +// LogValue 实现 slog.LogValuer。 +func (e *Error) LogValue() slog.Value { + attrs := []slog.Attr{ + slog.String("kind", string(e.Kind)), + slog.String("script", e.Script), + } + if e.Func != "" { + attrs = append(attrs, slog.String("func", e.Func)) + } + if e.Msg != "" { + attrs = append(attrs, slog.String("msg", e.Msg)) + } + if len(e.Stack) > 0 { + attrs = append(attrs, + slog.Int("line", e.Stack[0].Line), + slog.Int("column", e.Stack[0].Column), + slog.String("at", e.Stack[0].String()), + ) + } + if len(e.Args) > 0 { + attrs = append(attrs, slog.Any("args", e.Args)) + } + if e.GoStack != "" { + attrs = append(attrs, slog.String("go_stack", e.GoStack)) + } + if e.Cause != nil { + attrs = append(attrs, slog.String("cause", e.Cause.Error())) + } + return slog.GroupValue(attrs...) +} + +// newError 造一个带脚本上下文的错误。 +func newError(kind Kind, script, fn string, cause error, format string, a ...any) *Error { + return &Error{ + Kind: kind, + Script: script, + Func: fn, + Msg: fmt.Sprintf(format, a...), + Cause: cause, + } +} + +// classify 把 goja 抛出来的各种错误翻译成 *Error 并补上脚本上下文。 +// 已经是 *Error 的（比如 Dispatch 内部自己造的类型错误）原样返回。 +func classify(err error, script, fn string, args []any) error { + if err == nil { + return nil + } + + var known *Error + if errors.As(err, &known) { + return err + } + + // 超时/取消：goja.Runtime.Interrupt 打断脚本后返回的就是这个。 + var interrupted *goja.InterruptedError + if errors.As(err, &interrupted) { + cause := interrupted.Unwrap() + kind, msg := KindTimeout, "脚本执行超时，已强制中断" + switch { + case errors.Is(cause, context.Canceled): + kind, msg = KindCanceled, "调用方 context 被取消，脚本已中断" + case errors.Is(cause, context.DeadlineExceeded): + cause = fmt.Errorf("%w (%w)", ErrTimeout, cause) + case cause == nil: + cause = ErrInterrupted + } + return &Error{ + Kind: kind, + Script: script, + Func: fn, + Msg: msg, + Args: summarize(args), + Stack: framesOf(interrupted.Stack()), + Cause: cause, + } + } + + var overflow *goja.StackOverflowError + if errors.As(err, &overflow) { + return &Error{ + Kind: KindRuntime, + Script: script, + Func: fn, + Msg: "脚本调用栈溢出（多半是无限递归）", + Args: summarize(args), + Stack: framesOf(overflow.Stack()), + Cause: err, + } + } + + // 脚本里没被 catch 的异常。 + var exception *goja.Exception + if errors.As(err, &exception) { + e := &Error{ + Kind: KindRuntime, + Script: script, + Func: fn, + Msg: "脚本抛出异常", + Args: summarize(args), + Stack: framesOf(exception.Stack()), + Cause: err, + } + if v := exception.Value(); v != nil { + e.Msg = v.String() + e.Value = v.Export() + if hint := missingGlobalHint(e.Msg); hint != "" { + e.Msg += "。" + hint + } + } + // Go 侧函数返回的 error 透到 JS 又没被 catch 时，这里能把原始 Go error 取回来， + // 让调用方的 errors.Is 还能匹配到自己的哨兵错误。 + if inner := exception.Unwrap(); inner != nil { + e.Cause = inner + } + return e + } + + return &Error{ + Kind: KindRuntime, + Script: script, + Func: fn, + Msg: err.Error(), + Args: summarize(args), + Cause: err, + } +} + +func framesOf(stack []goja.StackFrame) []Frame { + if len(stack) == 0 { + return nil + } + out := make([]Frame, 0, len(stack)) + for i := range stack { + pos := stack[i].Position() + out = append(out, Frame{ + Source: stack[i].SrcName(), + Func: stack[i].FuncName(), + Line: pos.Line, + Column: pos.Column, + }) + } + return out +} + +const ( + maxSummaryArgs = 8 // 最多记录几个参数 + maxSummaryLen = 256 // 单个参数摘要的最大长度 +) + +// summarize 把调用参数压成可以安全写进日志的短字符串。 +// 只在出错路径上调用，正常调用不付这个格式化开销。 +func summarize(args []any) []string { + if len(args) == 0 { + return nil + } + n := min(len(args), maxSummaryArgs) + out := make([]string, 0, n+1) + for _, a := range args[:n] { + s := fmt.Sprintf("%v", a) + if len(s) > maxSummaryLen { + s = s[:maxSummaryLen] + "…" + } + out = append(out, fmt.Sprintf("%T=%s", a, s)) + } + if len(args) > n { + out = append(out, fmt.Sprintf("…还有 %d 个参数", len(args)-n)) + } + return out +} + +// fatal 判断这个错误是否说明 VM 已处于不确定状态，不该再放回池子复用。 +func fatal(err error) bool { + var e *Error + if errors.As(err, &e) { + switch e.Kind { + case KindTimeout, KindCanceled, KindPanic: + return true + } + return false + } + var interrupted *goja.InterruptedError + if errors.As(err, &interrupted) { + return true + } + var overflow *goja.StackOverflowError + return errors.As(err, &overflow) +} + +// toError 把 recover() 拿到的任意值转成 error。 +func toError(r any) error { + if err, ok := r.(error); ok { + return err + } + return fmt.Errorf("%v", r) +} + +// strconvQuote 是 strconv.Quote 的短名字，给错误信息拼接用。 +func strconvQuote(s string) string { return strconv.Quote(s) } + +// missingGlobalHint 针对几个"goja 没有、但脚本作者以为一定有"的全局， +// 在 ReferenceError 后面补一句人话。 +// +// 为什么是补错误信息，而不是把这些全局定义成"一调就报错"的桩： +// 库里 `typeof setTimeout !== "undefined"` 这种特性探测很常见，一旦定义了， +// 探测就会走进定时器分支，本来能优雅降级的库反而被弄坏。让它保持 undefined， +// 探测正常工作；真直接调用了，就在错误里说清楚。 +// +// 只认两种原样输出：goja 的 "ReferenceError: xxx is not defined"， +// 以及 esbuild 给动态 require 埋的那句运行期错误。 +func missingGlobalHint(msg string) string { + // require 不会以 ReferenceError 的形式出现——esbuild 在打包期就接管了它： + // 静态的 require("x") 直接当模块解析（解析不到就打包失败）， + // 动态的 require(变量) 换成下面这句运行期错误。 + if strings.HasPrefix(msg, "Error: Dynamic require of ") { + return "脚本走的是 ES 模块，用 import 而不是 require；" + + "而且 import 的路径必须是字面量，不能是变量拼出来的" + } + + const prefix = "ReferenceError: " + const suffix = " is not defined" + if !strings.HasPrefix(msg, prefix) || !strings.HasSuffix(msg, suffix) { + return "" + } + name := msg[len(prefix) : len(msg)-len(suffix)] + + switch name { + case "setTimeout", "setInterval", "setImmediate", + "clearTimeout", "clearInterval", "clearImmediate": + return "脚本是同步的，没有事件循环——定时器用不了。" + + "要延迟或周期执行，把这段逻辑放到 Go 侧的 Job / Cron；" + + "如果是第三方库里的 debounce / throttle 之类，换一个不依赖定时器的实现" + + case "structuredClone": + return "goja 没有这个函数。深拷贝用 JSON.parse(JSON.stringify(x))，" + + "或者换一个不依赖它的库（remeda 的 clone 就依赖它）" + + case "module", "exports": + return "脚本走的是 ES 模块，没有 CommonJS 那套；导出用 export default" + + case "process", "Buffer", "__dirname", "__filename": + return "脚本不跑在 Node 里，没有这些东西。要读配置用扩展提供的接口" + + case "window", "document", "navigator", "localStorage": + return "脚本不跑在浏览器里，没有 DOM" + + case "fetch", "XMLHttpRequest", "WebSocket": + return "脚本里发不了网络请求——那是异步的，而脚本是同步执行的。" + + "要调外部服务，在 Go 侧做好再通过扩展交给脚本" + } + return "" +} diff --git a/esmwrap.go b/esmwrap.go new file mode 100644 index 0000000..e34c219 --- /dev/null +++ b/esmwrap.go @@ -0,0 +1,108 @@ +package jscriptx + +import ( + "strings" +) + +// esbuild 按 IIFE 格式输出时，会在产物里塞一整套 CommonJS interop helper +// （__defProp / __export / __copyProps / __toCommonJS…）。那套东西是为了模拟 +// __esModule 语义，本库根本用不上：我们只要拿到导出对象。 +// +// 但它的代价是实打实的——每建一个 VM 都要重新创建那 7 个函数、再遍历一遍属性装 +// getter。实测建一个实例 22μs / 472 allocs，而不带 helper 的等价产物只要 4μs / 119。 +// +// 所以改成按 ESM 格式打包（import 照样内联），再自己把末尾那句 export 改写掉： +// +// // p.ts (() => {// p.ts +// var H = class {…}; ───► var H = class {…}; +// export { return H;})() +// H as default +// }; +// +// 改写有两条硬约束： +// +// - 开头的 (() => { 必须紧贴原第一行，不能另起一行，否则所有行号下移一位， +// sourcemap 就对不上了，报错定位不回 .ts 源码 +// - export 语句在产物末尾，把它整段换掉不影响前面任何行 + +// wrapESM 把 esbuild 的 ESM 产物改写成 goja 能直接执行的形式： +// 一个立即执行函数，完成值就是脚本的导出。 +// +// 认不出末尾的 export 语句时（脚本压根没有导出，或者 esbuild 换了输出格式）， +// 返回的产物求值为 undefined——交给"脚本没有任何导出"那条报错去解释。 +func wrapESM(code string) string { + body, entry, ok := splitESMExports(code) + if !ok { + // 没有导出：让它求值成 undefined，报错由 lookup 那边给 + return "(() => {" + code + "\nreturn void 0;})()\n" + } + return "(() => {" + body + "return " + entry + ";})()\n" +} + +// splitESMExports 从产物末尾切下 export 语句，返回前面的代码和入口表达式。 +// +// esbuild 的 ESM 输出格式很规整，末尾总是这样： +// +// export { +// H as default, +// extra +// }; +func splitESMExports(code string) (body, entry string, ok bool) { + i := strings.LastIndex(code, "\nexport {") + if i < 0 { + return "", "", false + } + j := strings.Index(code[i:], "\n};") + if j < 0 { + return "", "", false + } + body = code[:i+1] + tail := code[i+len("\nexport {") : i+j] + + names := parseExportNames(tail) + if len(names) == 0 { + return "", "", false + } + + // 有 default 就用它——这跟"脚本导出 class/函数/实例"的入口约定对得上； + // 只有命名导出时，把它们拼成一个对象，按方法名调用。 + if local, has := names["default"]; has { + return body, local, true + } + var b strings.Builder + b.WriteByte('{') + first := true + for exported, local := range names { + if !first { + b.WriteByte(',') + } + first = false + b.WriteString(exported) + b.WriteByte(':') + b.WriteString(local) + } + b.WriteByte('}') + return body, b.String(), true +} + +// parseExportNames 解析 export 语句体，返回 导出名 -> 本地名。 +// 每项形如 "H as default" 或 "foo"（导出名跟本地名相同）。 +func parseExportNames(tail string) map[string]string { + out := map[string]string{} + for _, item := range strings.Split(tail, ",") { + item = strings.TrimSpace(item) + if item == "" { + continue + } + local, exported := item, item + if k := strings.Index(item, " as "); k >= 0 { + local = strings.TrimSpace(item[:k]) + exported = strings.TrimSpace(item[k+len(" as "):]) + } + if !validIdent(local) || !validIdent(exported) { + return nil // 格式不认识，交给调用方走兜底 + } + out[exported] = local + } + return out +} diff --git a/extension.go b/extension.go new file mode 100644 index 0000000..da2fa25 --- /dev/null +++ b/extension.go @@ -0,0 +1,48 @@ +package jscriptx + +// Extension 是一个作用域级扩展：给脚本添一个全局对象。 +// +// 扩展实例由调用方自己创建，跟着 ctx 走： +// +// st := jscriptx.NewStore() +// tx := myTx(db) +// ctx = jscriptx.WithScope(ctx, jscriptx.ScopeExtensions(st, tx)) +// +// obj, err := ctrl.New(ctx) // 脚本里能用 store 和 tx +// defer obj.Close() +// +// st.Get("count") // Go 侧拿的就是同一份，不用再取回 +// +// 同一个 ctx 下 New 出来的所有实例共享同一份扩展对象——这就是多个 controller +// 共享数据的方式：共享的是 Go 侧对象，不是共用 Runtime。 +// +// 业务写自己的扩展只要实现这三个方法： +// +// type tx struct{ conn *sql.Tx } +// +// func (t *tx) Name() string { return "tx" } +// func (t *tx) Bindings() map[string]any { +// return map[string]any{"commit": t.conn.Commit, "rollback": t.conn.Rollback} +// } +// func (t *tx) Module() string { return txTypings } +type Extension interface { + // Name 是它在脚本里的全局名，必须是合法的 JS 标识符。 + // 跟白名单（WithGlobals）同名时以白名单为准。 + Name() string + + // Bindings 是暴露给脚本的方法集。方法名**大写开头**，跟脚本里能碰到的 + // 其它东西保持一致——传进来的 Go 对象（m.GetCode()、res.GetDBTable()） + // 用的都是 Go 的方法名，扩展再用小写的话，同一行代码里两种风格混着写。 + Bindings() map[string]any + + // Module 返回配套 TypeScript 模块的 import 路径和源码，让脚本能拿到类型： + // + // import store from "@jscriptx/store" + // + // 路径要加 scope 前缀，免得跟 node_modules 里的包撞名。用什么 scope 自己定， + // 框架层那套用的是 @jscriptx/，业务自己的可以用 @fsdpf/ 之类。 + // 路径返回空字符串表示不提供模块，脚本只能用全局变量的写法。 + // + // 模块本身只是个门面：把全局对象转发出来，附上类型声明。真正的实现在 Go 侧。 + Module() (path, source string) +} diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..b111363 --- /dev/null +++ b/go.mod @@ -0,0 +1,16 @@ +module git.fsdpf.net/go/jscriptx + +go 1.25.5 + +require ( + github.com/dop251/goja v0.0.0-20260826204918-8f1c0696a37b + github.com/evanw/esbuild v0.28.2 +) + +require ( + github.com/dlclark/regexp2/v2 v2.5.2 // indirect + github.com/go-sourcemap/sourcemap v2.1.3+incompatible // indirect + github.com/google/pprof v0.0.0-20230207041349-798e818bf904 // indirect + golang.org/x/sys v0.46.0 // indirect + golang.org/x/text v0.39.0 // indirect +) diff --git a/go.sum b/go.sum new file mode 100644 index 0000000..aeb2d17 --- /dev/null +++ b/go.sum @@ -0,0 +1,19 @@ +github.com/Masterminds/semver/v3 v3.5.0 h1:kQceYJfbupGfZOKZQg0kou0DgAKhzDg2NZPAwZ/2OOE= +github.com/Masterminds/semver/v3 v3.5.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM= +github.com/dlclark/regexp2/v2 v2.5.2 h1:HAsucWRhsqcDzl6Ua9aR8JwYOTzrZyPrF0/FNxJVAI0= +github.com/dlclark/regexp2/v2 v2.5.2/go.mod h1:avUrQvPaLz2DrFNHJF0taWAFFX2C1GMSSoeiqFjcBmU= +github.com/dop251/goja v0.0.0-20260826204918-8f1c0696a37b h1:mYHoARbZ0mUYXXsaNeHoDFBft3TK4PpFEe3KU7hdDgg= +github.com/dop251/goja v0.0.0-20260826204918-8f1c0696a37b/go.mod h1:u8yZRUavu+N4EnFFy6J5fVtjE7lEcZ2YyV2GcBXY9c8= +github.com/evanw/esbuild v0.28.2 h1:A2uETn4jrQTcXaT/shwTDTYBxDjl7fV7nXmUrJxfA2w= +github.com/evanw/esbuild v0.28.2/go.mod h1:D2vIQZqV/vIf/VRHtViaUtViZmG7o+kKmlBfVQuRi48= +github.com/go-sourcemap/sourcemap v2.1.3+incompatible h1:W1iEw64niKVGogNgBN3ePyLFfuisuzeidWPMPWmECqU= +github.com/go-sourcemap/sourcemap v2.1.3+incompatible/go.mod h1:F8jJfvm2KbVjc5NqelyYJmf/v5J0dwNLS2mL4sNA1Jg= +github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM= +github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA= +github.com/google/pprof v0.0.0-20230207041349-798e818bf904 h1:4/hN5RUoecvl+RmJRE2YxKWtnnQls6rQjjW5oV7qg2U= +github.com/google/pprof v0.0.0-20230207041349-798e818bf904/go.mod h1:uglQLonpP8qtYCYyzA+8c/9qtqgA3qsXGYqCPKARAFg= +golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw= +golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw= +golang.org/x/text v0.39.0 h1:UbZz4pLOvn600D6Oh6GGEI6VAmndrEBLv8/6BEXzyus= +golang.org/x/text v0.39.0/go.mod h1:3UwRclnC2g0TU9x8PZiyfOajCd1zaUNHF9cvqcQZ+ZM= diff --git a/instance.go b/instance.go new file mode 100644 index 0000000..9738ba3 --- /dev/null +++ b/instance.go @@ -0,0 +1,174 @@ +package jscriptx + +import ( + "context" + "sync" + "sync/atomic" + "time" +) + +// Instance 是脚本导出的 class 的一个实例，独占一个 VM，用起来跟普通 Go 对象差不多： +// +// obj, err := s.New(ctx, "dev-1", "温控器") +// defer obj.Close() +// got, err := obj.Call(ctx, "onMessage", payload) +// +// 跟从 VM 池借用的 Script.Call 不同，实例在整个生命周期里绑定同一个 VM， +// 所以脚本里的 this.xxx 能跨调用保持： +// +// export default class DeviceHandler { +// constructor(deviceId, model) { this.count = 0 } +// onMessage(payload) { return ++this.count } // 跨调用累加 +// } +// +// # 必须知道的三件事 +// +// 1. 生命周期归你管。Close 之前它一直占着一个 VM（约 16 KB），本库不会替你回收， +// 也没有按 key 复用那一套——要长期持有（比如按设备 ID 存着），业务侧自己拿 map 存。 +// 2. 同一个实例的调用是串行的。goja 的 Runtime 不是并发安全的，多个 goroutine +// 同时调同一个实例会排队；不同实例之间并行。 +// 3. 脚本出错会丢状态。一次超时或 panic 会让这个 VM 被丢弃，下次调用时用一份 +// 全新的实例重建（构造参数会重新传一遍，但 this 上攒的状态归零）。 +// Resets 能查到发生过几次。真正不能丢的东西放作用域的扩展里（比如 store）。 +type Instance struct { + script *Script + ctorArgs []any + label string // 错误信息里怎么称呼它 + scope *scope // ctx 带来的作用域：扩展和额外全局从这里拿，没有作用域时为 nil + + mu sync.Mutex // 保证串行执行，acquire 持锁直到 finish + vm *vmHandle + done bool + + lastUsed atomic.Int64 // UnixNano，空闲回收用 + calls atomic.Int64 + resets atomic.Int64 +} + +// New 实例化脚本导出的 class，构造参数直接传给 constructor。返回的实例独占一个 VM， +// 脚本里的 this.xxx 在它活着期间跨调用保持，用完 Close。 +// +// ctx 里带了作用域（WithScope）时，作用域里的扩展和全局对象会注入给这个实例—— +// 同一个 ctx 下 New 出来的多个实例因此共享同一份扩展（比如 store），但各有各的 VM， +// 互相并行、this.xxx 互不干扰。 +// +// 脚本导出的不是 class 而是实例或函数时也能用，只是构造参数没有去处会被忽略。 +// constructor 里抛异常会在这里就报出来，不用等到第一次调用。 +func (s *Script) New(ctx context.Context, ctorArgs ...any) (*Instance, error) { + if s.closed.Load() { + return nil, newError(KindClosed, s.name, "", ErrClosed, "脚本已关闭") + } + i := &Instance{script: s, ctorArgs: ctorArgs, label: "实例"} + if sc, ok := scopeOf(ctx); ok { + i.scope = sc + i.label = "作用域 " + strconvQuote(sc.key) + " 的实例" + } + i.touch() + if err := i.warmup(ctx); err != nil { + return nil, err + } + return i, nil +} + +// Name 返回脚本名。 +func (i *Instance) Name() string { return i.script.name } + +// Calls 返回这个实例累计发起过多少次调用。 +func (i *Instance) Calls() int64 { return i.calls.Load() } + +// Resets 返回这个实例的 VM 被重建过几次。每重建一次，脚本里 this 上的状态就归零一次。 +func (i *Instance) Resets() int64 { return i.resets.Load() } + +// IdleFor 返回这个实例空闲了多久。 +func (i *Instance) IdleFor() time.Duration { + return time.Since(time.Unix(0, i.lastUsed.Load())) +} + +// Call 在这个实例上调用方法，语义跟 Script.Call 一致，只是 this 绑定到本实例。 +func (i *Instance) Call(ctx context.Context, fn string, args ...any) (any, error) { + return callAny(ctx, i, fn, args) +} + +// CallInto 在这个实例上调用方法，并把返回值转换进 out 指向的变量。 +func (i *Instance) CallInto(ctx context.Context, fn string, out any, args ...any) error { + return callInto(ctx, i, fn, out, args) +} + +// Has 判断实例上有没有这个方法（继承来的也算）。 +func (i *Instance) Has(fn string) bool { + i.mu.Lock() + defer i.mu.Unlock() + if err := i.ensure(context.Background()); err != nil { + return false + } + _, _, _, ok := i.vm.lookup(fn) + return ok +} + +// Close 释放这个实例占用的 VM。之后的调用返回 ErrClosed。重复调用是安全的。 +// +// 作用域里的扩展不归它管——那些是你自己创建的对象，Close 只释放这个实例的 VM。 +func (i *Instance) Close() { i.shutdown() } + +func (i *Instance) owner() *Script { return i.script } +func (i *Instance) touch() { i.lastUsed.Store(time.Now().UnixNano()) } + +// warmup 提前建好 VM，让 constructor 的错误在 New 阶段就暴露出来。 +func (i *Instance) warmup(ctx context.Context) error { + i.mu.Lock() + defer i.mu.Unlock() + return i.ensure(ctx) +} + +// ensure 保证 VM 就绪，调用方必须持有 i.mu。 +func (i *Instance) ensure(ctx context.Context) error { + if i.done || i.script.closed.Load() { + return newError(KindClosed, i.script.name, "", ErrClosed, "%s已关闭", i.label) + } + if i.vm != nil { + return nil + } + // 作用域带来的额外全局（扩展 + ScopeGlobals）现取现用，不在 Instance 上留副本。 + var extra map[string]any + if i.scope != nil { + extra = i.scope.vmGlobals() + } + vm, err := i.script.newVM(ctx, extra, i.ctorArgs) + if err != nil { + return err + } + i.vm = vm + return nil +} + +// acquire 锁住实例并交出它独占的 VM。 +// 注意：锁一直持到 finish 才释放，这正是"同一实例串行执行"的保证。 +func (i *Instance) acquire(ctx context.Context) (*vmHandle, error) { + i.mu.Lock() + if err := i.ensure(ctx); err != nil { + i.mu.Unlock() + return nil, err + } + i.touch() + i.calls.Add(1) + return i.vm, nil +} + +// finish 交还 VM 并解锁。VM 状态不确定时（超时/panic）直接丢弃， +// 下次调用会重建一个全新实例——脚本里 this 上的状态也就跟着归零了。 +func (i *Instance) finish(_ *vmHandle, healthy bool) { + if !healthy { + i.vm = nil + i.resets.Add(1) + } + i.touch() + i.mu.Unlock() +} + +// shutdown 真正释放 VM。 +func (i *Instance) shutdown() { + i.mu.Lock() + defer i.mu.Unlock() + i.done = true + i.vm = nil +} diff --git a/invoke.go b/invoke.go new file mode 100644 index 0000000..f9bcf76 --- /dev/null +++ b/invoke.go @@ -0,0 +1,326 @@ +package jscriptx + +import ( + "context" + "fmt" + "reflect" + "runtime/debug" + "sync" + "time" + + "github.com/dop251/goja" +) + +// frame 是一次调用的上下文：拿到了 VM、目标函数，可以真正发起调用。 +// 它只在 withCall 的回调里有效，不能存下来跨调用使用。 +type frame struct { + script *Script + rt *goja.Runtime + fn goja.Callable + fnVal goja.Value + this goja.Value // 方法调用时绑定的 this（导出实例），默认导出函数为 undefined + name string +} + +// arity 返回 JS 函数声明的形参个数（函数对象的 length 属性）， +// Dispatch 靠它判断脚本写的是哪种回调形状。 +func (f *frame) arity() int64 { + return f.fnVal.ToObject(f.rt).Get("length").ToInteger() +} + +// call 调用目标函数，this 按 lookup 的结果绑定。 +func (f *frame) call(args ...goja.Value) (goja.Value, error) { + return f.fn(f.this, args...) +} + +// callWith 用 Go 值直接调用目标函数。 +func (f *frame) callWith(args []any) (goja.Value, error) { + jsArgs := make([]goja.Value, len(args)) + for i, a := range args { + jsArgs[i] = f.rt.ToValue(a) + } + return f.call(jsArgs...) +} + +// export 把脚本返回值转成 Go 值，写进 target 指向的变量。 +func (f *frame) export(v goja.Value, target any) error { + return f.rt.ExportTo(v, target) +} + +// empty 判断脚本返回值是不是"什么都没返回"。 +func empty(v goja.Value) bool { + return v == nil || goja.IsUndefined(v) || goja.IsNull(v) +} + +// Call 调用脚本里的函数，返回值导出成 Go 值（JS 对象变 map[string]any，数组变 []any， +// 传进去的 Go 对象原样回来）。fn 传 DefaultFunc 表示调用脚本自身求值出的那个函数。 +// +// 脚本返回函数/闭包会被拒绝：那种值只在 VM 内部有效，VM 归还池子后再调用会出问题。 +// 需要把脚本函数当回调用，走 Dispatch。 +func (s *Script) Call(ctx context.Context, fn string, args ...any) (any, error) { + return callAny(ctx, s, fn, args) +} + +// CallInto 调用脚本里的函数，并把返回值转换进 out 指向的变量（out 必须是非 nil 指针）， +// 相当于带类型的 Call：目标是 int 就按 int 转，是某个接口就要求返回值实现它。 +func (s *Script) CallInto(ctx context.Context, fn string, out any, args ...any) error { + return callInto(ctx, s, fn, out, args) +} + +// callAny 是 Call 的共用实现，*Script 和 *Session 都走这里。 +func callAny(ctx context.Context, r runner, fn string, args []any) (any, error) { + var out any + err := invoke(ctx, r, fn, args, func(f *frame) error { + res, err := f.callWith(args) + if err != nil { + return err + } + res, err = unwrapPromise(f, res, r.owner().name, fn) + if err != nil { + return err + } + if empty(res) { + return nil + } + if _, isFunc := goja.AssertFunction(res); isFunc { + return newError(KindType, r.owner().name, fn, ErrValueEscape, + "返回值是 JS 函数，只在脚本内部有效；需要回调语义请用 Dispatch") + } + out = res.Export() + return nil + }) + return out, err +} + +// callInto 是 CallInto 的共用实现。 +func callInto(ctx context.Context, r runner, fn string, out any, args []any) error { + name := r.owner().name + + rv := reflect.ValueOf(out) + if !rv.IsValid() || rv.Kind() != reflect.Pointer || rv.IsNil() { + return newError(KindType, name, fn, nil, "CallInto 的 out 必须是非 nil 指针，当前是 %T", out) + } + // 导出成 Go 函数意味着把一个绑定在 VM 上的闭包带出脚本边界， + // 而这个 VM 马上就要还回池子给别的请求用了。 + if rv.Type().Elem().Kind() == reflect.Func { + return newError(KindType, name, fn, ErrValueEscape, + "不能把脚本函数导出成 Go 函数（VM 归还池子后它就失效了）；需要回调语义请用 Dispatch") + } + + return invoke(ctx, r, fn, args, func(f *frame) error { + res, err := f.callWith(args) + if err != nil { + return err + } + res, err = unwrapPromise(f, res, name, fn) + if err != nil { + return err + } + if empty(res) { + return nil + } + if err := f.export(res, out); err != nil { + return newError(KindType, name, fn, err, "返回值无法转换成 %T", out) + } + return nil + }) +} + +// runner 抽象"这次调用用哪个 VM、用完怎么处理"：*Script 从池里借还， +// *Session 独占一个 VM（acquire 会一直持锁到 finish，保证同一会话串行执行）。 +type runner interface { + owner() *Script + acquire(ctx context.Context) (*vmHandle, error) + finish(inst *vmHandle, healthy bool) +} + +func (s *Script) owner() *Script { return s } + +func (s *Script) acquire(ctx context.Context) (*vmHandle, error) { return s.borrow(ctx) } + +func (s *Script) finish(inst *vmHandle, healthy bool) { s.release(inst, healthy) } + +// invoke 是所有脚本调用的骨架：取 VM → 找函数 → 装超时哨兵 → 兜 panic → 分类错误 → 交还 VM。 +// do 里只管发起调用和处理返回值，异常处理交给这里。 +func invoke(ctx context.Context, r runner, fn string, args []any, do func(*frame) error) (err error) { + s := r.owner() + if s.closed.Load() { + return newError(KindClosed, s.name, fn, ErrClosed, "脚本已关闭") + } + if ctx == nil { + ctx = context.Background() + } + + inst, err := r.acquire(ctx) + if err != nil { + return err + } + + healthy := true + // defer 是后进先出：recover 最先跑（把 healthy 置回 false）， + // 然后 stop 清掉可能迟到的中断标志，最后才交还 VM。 + defer func() { r.finish(inst, healthy) }() + + callable, fnVal, this, ok := inst.lookup(fn) + if !ok { + return newError(KindNotFound, s.name, fn, ErrFuncNotFound, "%s", s.notFoundHint(inst)) + } + + stop := guard(ctx, inst.rt, s.engine.timeout) + defer stop() + + defer func() { + if r := recover(); r != nil { + healthy = false + err = s.panicError(fn, args, r) + } + }() + + f := &frame{script: s, rt: inst.rt, fn: callable, fnVal: fnVal, this: this, name: fn} + if e := do(f); e != nil { + err = classify(e, s.name, fn, args) + healthy = !fatal(err) + return err + } + return nil +} + +// panicError 把 recover 到的 panic 包成带现场的错误。脚本里的类型错误、 +// 注入进去的 Go 方法内部 panic，都会走到这里，不会掀翻调用方的 goroutine。 +func (s *Script) panicError(fn string, args []any, r any) *Error { + return &Error{ + Kind: KindPanic, + Script: s.name, + Func: fn, + Msg: fmt.Sprintf("脚本执行过程中发生 panic: %v", r), + Args: summarize(args), + GoStack: string(debug.Stack()), + Cause: toError(r), + } +} + +// interruptGuard 保证"中断"和"收尾"两件事不会打架：收尾之后再迟到的中断信号必须被丢掉， +// 否则它会毒死下一次用到这个 VM 的调用。 +type interruptGuard struct { + mu sync.Mutex + stopped bool + rt *goja.Runtime +} + +func (g *interruptGuard) fire(reason error) { + g.mu.Lock() + defer g.mu.Unlock() + if g.stopped { + return + } + g.rt.Interrupt(reason) +} + +// stop 关掉哨兵并清掉可能已经发出的中断标志。返回后保证不会再有新的中断落到这个 VM 上。 +func (g *interruptGuard) stop() { + g.mu.Lock() + g.stopped = true + g.mu.Unlock() + // 到这里要么 fire 已经跑完（中断标志由下面清掉），要么它以后永远不会再发。 + g.rt.ClearInterrupt() +} + +// guard 装一个中断哨兵：超时或者调用方 context 取消时，从另一个 goroutine 调 +// Interrupt 打断正在执行的脚本（死循环也能断掉）。返回的函数负责收尾。 +func guard(ctx context.Context, rt *goja.Runtime, timeout time.Duration) func() { + watchCtx := ctx.Done() != nil + if timeout <= 0 && !watchCtx { + return func() {} + } + + g := &interruptGuard{rt: rt} + + if !watchCtx { + // 快路径：没有 context 取消要盯，一个定时器就够了，不用为每次调用起 goroutine。 + // MQTT 消息级这种高频调用走的就是这条路。 + timer := time.AfterFunc(timeout, func() { g.fire(context.DeadlineExceeded) }) + return func() { + g.stop() + timer.Stop() + } + } + + var cancel context.CancelFunc + if timeout > 0 { + ctx, cancel = context.WithTimeout(ctx, timeout) + } + done := make(chan struct{}) + exited := make(chan struct{}) + go func() { + defer close(exited) + select { + case <-ctx.Done(): + g.fire(ctx.Err()) + case <-done: + } + }() + + return func() { + close(done) + <-exited + if cancel != nil { + cancel() + } + g.stop() + } +} + +// unwrapPromise 把 async 方法返回的 Promise 解开。 +// +// goja 在调用返回前会把 microtask 队列跑干净，所以只要脚本里没有真正需要等待外部 +// 事件的操作（goja 没有事件循环，也没有 setTimeout），Promise 到这里已经是完成态了。 +// 解开它有两个理由：一是 *goja.Promise 属于引擎类型，不该出现在本库的返回值里； +// 二是调用方拿到一个未解包的 Promise 什么也做不了。 +func unwrapPromise(f *frame, v goja.Value, script, fn string) (goja.Value, error) { + p, ok := promiseOf(v) + if !ok { + return v, nil + } + switch p.State() { + case goja.PromiseStateFulfilled: + return p.Result(), nil + + case goja.PromiseStateRejected: + reason := p.Result() + e := &Error{ + Kind: KindRuntime, + Script: script, + Func: fn, + Msg: "async 方法的 Promise 被 reject", + Cause: ErrPromiseRejected, + } + if reason != nil { + e.Msg = reason.String() + e.Value = reason.Export() + } + return nil, e + + default: + return nil, newError(KindRuntime, script, fn, ErrPromisePending, + "async 方法返回的 Promise 一直没完成。goja 没有事件循环，"+ + "脚本里没法等待真正的异步操作（定时器、网络、IO）；"+ + "异步的活交给 Go 侧做，脚本只写同步逻辑") + } +} + +// promiseOf 判断一个返回值是不是 Promise。 +// +// *goja.Promise 只能从 Export() 拿到，但对普通对象调 Export 会把整个对象转成 map， +// 那个开销不能加在每次调用上。先看有没有 then 属性——一次廉价的属性查找就能排除掉 +// 绝大多数返回值，只有 thenable 才走到 Export。 +func promiseOf(v goja.Value) (*goja.Promise, bool) { + obj, ok := v.(*goja.Object) + if !ok { + return nil, false + } + if then := obj.Get("then"); then == nil || goja.IsUndefined(then) { + return nil, false + } + p, ok := obj.Export().(*goja.Promise) + return p, ok +} diff --git a/loader.go b/loader.go new file mode 100644 index 0000000..f86f64f --- /dev/null +++ b/loader.go @@ -0,0 +1,104 @@ +package jscriptx + +// Loader 负责按名字提供脚本源码。脚本存在文件、数据库表还是配置中心，由实现方决定； +// 本库只定义这个接口，不预设来源。 +// +// 给出的源码默认会由 Engine 交给 esbuild 打包（ESM/TypeScript 都在那一步抹平）， +// 所以直接返回原始源码即可。已经自己打过包的实现（比如 jscriptx/esm 的 Loader） +// 再实现 Prepared 接口，Engine 就会跳过这一步。 +// +// version 用来判断脚本有没有变：Engine 拿它跟缓存里的版本比对， +// 一致就复用已编译的 Program 和 VM 池，不一致才重新编译。取值随实现方便， +// 比如文件的 mtime+size、数据库行的 updated_at、源码哈希都行； +// 返回空字符串表示"我不提供版本号"，Engine 会退化成拿源码算哈希。 +// +// 打开 WithAutoReload 后每次取脚本都会调一次 Load，实现方要保证这个调用足够轻 +// （能只查版本就别每次全量读源码，或者自己加一层短 TTL 缓存）。 +// +// 脚本不存在时，返回的错误要能被 errors.Is(err, ErrScriptNotFound) 匹配上， +// 调用方才好区分"脚本没配"和"加载出故障"。 +// +// 实现必须并发安全。 +type Loader interface { + Load(name string) (source string, version string, err error) +} + +// LoaderFunc 让普通函数直接当 Loader 用： +// +// loader := jscriptx.LoaderFunc(func(name string) (string, string, error) { +// row, err := db.QueryScript(name) +// if err != nil { +// return "", "", err +// } +// return row.Source, row.UpdatedAt, nil +// }) +type LoaderFunc func(name string) (source string, version string, err error) + +func (f LoaderFunc) Load(name string) (string, string, error) { return f(name) } + +// PreparedFunc 跟 LoaderFunc 一样是把函数当 Loader 用，区别是它声明"源码已经打好包了" +// （见 Prepared）。多层叠放时各层的 Prepared 必须一致，拿它就能让一个自定义来源 +// 跟 jscriptx/esm 那样的层对齐： +// +// db := jscriptx.PreparedFunc(func(name string) (string, string, error) { +// row, err := db.QueryScript(name) +// if err != nil { +// return "", "", err +// } +// bundled, err := jscriptx.Bundle(name, row.Source) // 自己打包 +// if err != nil { +// return "", "", err +// } +// return bundled, row.UpdatedAt, nil +// }) +// +// e, _ := jscriptx.New(jscriptx.WithLoader(esmLoader, db)) +// +// 名副其实是你自己的责任：说了打好包，交出去的就必须是打包产物， +// 否则脚本里的 import/export 会原样进 goja，直接编译失败。 +type PreparedFunc func(name string) (source string, version string, err error) + +func (f PreparedFunc) Load(name string) (string, string, error) { return f(name) } + +// Prepared 恒为 true，见 PreparedFunc 的说明。 +func (f PreparedFunc) Prepared() bool { return true } + +var _ Prepared = PreparedFunc(nil) + +// Prepared 由那些自己已经把源码打包好的 Loader 实现（比如 jscriptx/esm 的 Loader）， +// Engine 见到它就跳过打包这一步。 +// +// 这不是性能优化，是正确性要求：打包产物是 IIFE，里面已经没有 export 了， +// 再打包一遍会被 esbuild 当死代码整段摇空，脚本变成什么都不剩。 +// 所以自己打过包的 Loader 必须实现它。 +// +// Engine 靠类型断言识别，方法签名写错了不会有编译错误。自己实现时最好钉一行 +// +// var _ jscriptx.Prepared = (*MyLoader)(nil) +type Prepared interface { + // Prepared 返回 true 表示 Load 给出的源码已经可以直接交给引擎编译。 + Prepared() bool +} + +func isPrepared(l Loader) bool { + p, ok := l.(Prepared) + return ok && p.Prepared() +} + +// loadLocked 走 Loader 拿源码；cached 非空且版本一致时直接复用缓存。调用方必须持有 e.mu。 +func (e *Engine) loadLocked(name string, cached *Script) (*Script, error) { + source, version, err := e.loader.Load(name) + if err != nil { + return nil, newError(KindLoad, name, "", err, "加载脚本源码失败") + } + if cached != nil && version != "" && cached.version == version { + return cached, nil + } + if version == "" { + version = hashVersion(source) + if cached != nil && cached.version == version { + return cached, nil + } + } + return e.compileLocked(name, source, version, isPrepared(e.loader)) +} diff --git a/overlay.go b/overlay.go new file mode 100644 index 0000000..8309896 --- /dev/null +++ b/overlay.go @@ -0,0 +1,238 @@ +package jscriptx + +import ( + "errors" + "fmt" + "sort" + "strconv" + "strings" +) + +// VersionSep 分隔脚本名和版本标签。叠层时用 "脚本名@版本" 点名要哪一层的实现。 +const VersionSep = "@" + +// OverlayLoader 把若干个 Loader 叠成一个，**后面的盖前面的**。 +// 由 Overlay 创建。 +type OverlayLoader struct { + loaders []Loader + prepared bool // 所有成员一致，构造时已校验过 + byVer map[string]int // 版本标签 -> 层号，贴了标签的层才在里面 +} + +// Versioned 由带版本标签的 Loader 实现（比如 esm.Loader 配 WithVersion）。 +// 叠层时这个标签就是调用点用来点名的那个：Load("Foo/Bar@v1")。 +// +// 没实现这个接口、或者标签是空串的层，只能通过"上层盖下层"取到，点不了名。 +type Versioned interface { + // Version 返回这一层的版本标签。 + Version() string +} + +// Tag 给任意 Loader 贴一个版本标签，让它在叠层里能被点名。 +// 自带标签的 Loader（比如 esm.NewLoader 配了 WithVersion）不用它。 +// +// e, _ := jscriptx.New(jscriptx.WithLoader( +// disk, +// jscriptx.Tag("hotfix", dbLoader), // 之后可以 Load("Foo/Bar@hotfix") +// )) +func Tag(version string, l Loader) Loader { + return &taggedLoader{Loader: l, version: version} +} + +type taggedLoader struct { + Loader + version string +} + +func (t *taggedLoader) Version() string { return t.version } + +// Prepared 透传底下那个 Loader 的取值，别让贴标签这件事改了它的性质。 +func (t *taggedLoader) Prepared() bool { return isPrepared(t.Loader) } + +func versionOf(l Loader) string { + v, ok := l.(Versioned) + if !ok { + return "" + } + return v.Version() +} + +// Overlay 把多个 Loader 叠成一个：取脚本时从最后一个往前找，谁先有就用谁的。 +// 排在后面的因此能覆盖前面的同名脚本——把"定制层"放最后，业务侧放一份同名脚本 +// 就能改写默认实现，不用动被覆盖的那一份： +// +// base, _ := esm.NewLoader("app/src") +// custom, _ := esm.NewLoader("custom/src") // 配置可以跟 base 完全不同 +// +// loader, err := jscriptx.Overlay(base, custom) // custom 盖 base +// e, _ := jscriptx.New(jscriptx.WithLoader(loader)) +// +// 每个成员是独立的 Loader，各有各的配置（入口规则、目标版本、node_modules 位置、 +// 扩展模块），来源也可以不同——一层来自磁盘目录，另一层来自数据库都行。 +// +// 给某一层贴了版本标签（esm 的 WithVersion，或者 Tag），调用点就能点名要它： +// +// v1, _ := esm.NewLoader("app/v1/src", esm.WithVersion("v1")) +// v2, _ := esm.NewLoader("app/v2/src", esm.WithVersion("v2")) +// +// e.New(ctx, "Resource/ResCreateController") // 不点名：上层盖下层，拿到 v2 +// e.New(ctx, "Resource/ResCreateController@v1") // 点名：只在 v1 那层找，不回落 +// +// 点名是"只认这一层"：那层没有这个脚本就直接报不存在，不会掉到别的层去—— +// 不然点名要 v1 却跑了 v2 的实现，比报错难查得多。 +// +// 成员的 Prepared 必须一致：要么都是自己打好包的（比如 jscriptx/esm 的 Loader）， +// 要么都交出原始源码由引擎打包。混着来会返回错误，因为引擎只能对整个 Loader +// 做一次判断，没法分脚本区别对待。真要混，把原始源码那层用 LoaderFunc 包一下， +// 里面自己调 Bundle，它就跟其它层一样是"打好包的"了。 +func Overlay(loaders ...Loader) (*OverlayLoader, error) { + if len(loaders) == 0 { + return nil, errors.New("jscriptx: Overlay 至少要给一个 Loader") + } + for i, l := range loaders { + if l == nil { + return nil, fmt.Errorf("jscriptx: Overlay 的第 %d 个 Loader 是 nil", i) + } + } + prepared := isPrepared(loaders[0]) + for i, l := range loaders[1:] { + if isPrepared(l) != prepared { + return nil, fmt.Errorf( + "jscriptx: Overlay 的成员 Prepared 不一致（第 0 个是 %v，第 %d 个是 %v）；"+ + "要么都自己打包，要么都交出原始源码", prepared, i+1, !prepared) + } + } + byVer := map[string]int{} + for i, l := range loaders { + v := versionOf(l) + if v == "" { + continue + } + if strings.Contains(v, VersionSep) { + return nil, fmt.Errorf("jscriptx: 版本标签 %q 里不能有 %q", v, VersionSep) + } + if j, dup := byVer[v]; dup { + return nil, fmt.Errorf("jscriptx: 版本标签 %q 重了（第 %d 层和第 %d 层）", v, j, i) + } + byVer[v] = i + } + return &OverlayLoader{ + loaders: append([]Loader(nil), loaders...), + prepared: prepared, + byVer: byVer, + }, nil +} + +// Load 从最后一个成员往前找，返回第一个找到的脚本。 +// +// 成员报"脚本不存在"就继续往前找；报别的错直接返回——加载出故障不该被 +// 后面那层的结果悄悄盖掉。 +func (o *OverlayLoader) Load(name string) (string, string, error) { + if bare, version, ok := splitVersion(name); ok { + return o.loadFrom(bare, version) + } + var notFound error + for i := len(o.loaders) - 1; i >= 0; i-- { + source, version, err := o.loaders[i].Load(name) + if err != nil { + if errors.Is(err, ErrScriptNotFound) { + notFound = err + continue + } + return "", "", err + } + // 版本号带上是第几层给的：覆盖层的脚本删掉后会落回下面那层， + // 两层的版本号万一撞上，不带层号就看不出脚本已经换了人。 + if version != "" { + version = strconv.Itoa(i) + ":" + version + } + return source, version, nil + } + if notFound == nil { + notFound = ErrScriptNotFound + } + return "", "", fmt.Errorf("%w: %s（%d 层都没有）", notFound, name, len(o.loaders)) +} + +// loadFrom 只在点名的那一层找，找不到就报不存在，不回落到别的层。 +func (o *OverlayLoader) loadFrom(name, version string) (string, string, error) { + i, ok := o.byVer[version] + if !ok { + return "", "", fmt.Errorf("%w: %s（没有版本 %q 这一层，有的是 %v）", + ErrScriptNotFound, name, version, o.Versions()) + } + source, ver, err := o.loaders[i].Load(name) + if err != nil { + return "", "", err + } + if ver != "" { + ver = strconv.Itoa(i) + ":" + ver + } + return source, ver, nil +} + +// splitVersion 把 "Foo/Bar@v1" 拆成 "Foo/Bar" 和 "v1"。 +// 用最后一个分隔符，脚本名里真带了 @ 也不会拆错。 +func splitVersion(name string) (bare, version string, ok bool) { + i := strings.LastIndex(name, VersionSep) + if i <= 0 || i == len(name)-1 { + return name, "", false // 没有分隔符，或者两边空着 + } + return name[:i], name[i+1:], true +} + +// Versions 返回各层的版本标签，按叠放顺序，没贴标签的层跳过。 +func (o *OverlayLoader) Versions() []string { + var out []string + for _, l := range o.loaders { + if v := versionOf(l); v != "" { + out = append(out, v) + } + } + return out +} + +// Prepared 返回成员们一致的取值，见 Overlay 的说明。 +func (o *OverlayLoader) Prepared() bool { return o.prepared } + +// Loaders 返回成员，顺序即叠放顺序（后面的盖前面的）。 +func (o *OverlayLoader) Loaders() []Loader { return append([]Loader(nil), o.loaders...) } + +// Names 汇总所有成员的脚本名，去重后按字典序排列。 +// 成员得有 Names() []string 方法才算得上，没有的（比如数据库来源）就跳过。 +func (o *OverlayLoader) Names() []string { + seen := map[string]bool{} + var out []string + for _, l := range o.loaders { + lister, ok := l.(interface{ Names() []string }) + if !ok { + continue + } + for _, n := range lister.Names() { + if !seen[n] { + seen[n] = true + out = append(out, n) + } + } + } + sort.Strings(out) + return out +} + +// Rebuild 挨个让成员重建。成员没有 Rebuild() error 方法就跳过。 +// 有成员失败时其余的照样会走一遍，返回的错误里带上所有失败。 +func (o *OverlayLoader) Rebuild() error { + var errs []error + for i, l := range o.loaders { + r, ok := l.(interface{ Rebuild() error }) + if !ok { + continue + } + if err := r.Rebuild(); err != nil { + errs = append(errs, fmt.Errorf("第 %d 层: %w", i, err)) + } + } + return errors.Join(errs...) +} + +var _ Prepared = (*OverlayLoader)(nil) diff --git a/scope.go b/scope.go new file mode 100644 index 0000000..d8dfeb9 --- /dev/null +++ b/scope.go @@ -0,0 +1,159 @@ +package jscriptx + +import ( + "context" + "crypto/rand" + "encoding/hex" + "time" +) + +// 作用域通过 context 传递：它只携带一段业务流程里要共享的东西（扩展和全局对象）， +// 不管任何生命周期——实例的生死由你 Close 决定。 +// +// st := jscriptx.NewStore() +// ctx = jscriptx.WithScope(ctx, jscriptx.ScopeExtensions(st)) +// +// obj, err := resCtrl.New(ctx, arg) // 从 ctx 拿扩展和全局 +// defer obj.Close() +// _, err = obj.Call(ctx, "Store", cfg) // this.xxx 在 obj 活着期间保持 +// +// obj2, err := queryCtrl.New(ctx) // 同一个 ctx → 同一份 store +// defer obj2.Close() +// +// 每个实例独占一个 VM，所以： +// +// - 不同请求的实例互不相干，完全并行 +// - 同一个 ctx 下的不同 controller 各有各的 VM，也是并行的，只是共享扩展 +// - 同一个实例的多次调用串行——这是保住 this.xxx 必需的 +// +// 共享数据走扩展（Go 侧对象，注入到各个 VM 的是同一份引用），而不是共用 Runtime： +// 共用 Runtime 会让所有脚本被迫串行，那才是真的并发瓶颈。 +// +// 设备连接这类长期会话，业务侧自己拿 map 存 Instance 就行，跟 Go 版 controller 的 +// 写法一致；本库不代管这个生命周期。 + +type scopeCtxKey struct{} + +// scope 是一个作用域：一个标识、一批专属的全局对象、若干扩展。 +// 它整个装在 ctx 里传递，不持有任何 VM，也不管实例的生命周期。 +type scope struct { + key string + globals map[string]any + exts []Extension +} + +// ScopeOption 配置 WithScope 装进 ctx 的作用域。 +type ScopeOption func(*scope) + +// ScopeKey 给作用域一个标识，脚本里可以通过 scope.key 读到，也会出现在日志里。 +// 不给就生成一个随机的。它只是个标识，不参与任何查找或复用。 +func ScopeKey(key string) ScopeOption { + return func(s *scope) { s.key = key } +} + +// ScopeExtensions 把扩展带进这个作用域，它们会成为脚本里的全局对象。 +// +// 实例由你自己创建，所以 Go 侧和脚本读写的天然是同一份，不用再取回来： +// +// st := jscriptx.NewStore() +// ctx = jscriptx.WithScope(ctx, jscriptx.ScopeExtensions(st)) +// // …脚本里 store.Set("k", v)… +// st.Get("k") +// +// 同名的后者覆盖前者；跟白名单（WithGlobals）同名时以白名单为准。 +func ScopeExtensions(exts ...Extension) ScopeOption { + return func(s *scope) { s.exts = append(s.exts, exts...) } +} + +// ScopeGlobals 给这个作用域注入专属的全局对象，同名时盖过扩展。 +// 这个 ctx 下 New 出来的实例都能看到它，适合放当前用户、当前设备这类东西。 +// +// 注意它是**建 VM 时**注入的，也就是 New 的那一刻。实例建好之后再改 ctx 不会影响它， +// 每次调用都可能变的东西当调用参数传。 +func ScopeGlobals(globals map[string]any) ScopeOption { + return func(s *scope) { + if s.globals == nil { + s.globals = map[string]any{} + } + for k, v := range globals { + s.globals[k] = v + } + } +} + +// WithScope 把一个作用域装进 ctx。没给 ScopeKey 时生成一个随机标识。 +func WithScope(ctx context.Context, opts ...ScopeOption) context.Context { + sc := &scope{} + for _, opt := range opts { + opt(sc) + } + if sc.key == "" { + sc.key = randomKey() + } + if ctx == nil { + ctx = context.Background() + } + return context.WithValue(ctx, scopeCtxKey{}, sc) +} + +// ScopeKeyOf 取回 ctx 里的作用域标识，没有作用域时第二个返回值是 false。 +func ScopeKeyOf(ctx context.Context) (string, bool) { + sc, ok := scopeOf(ctx) + if !ok { + return "", false + } + return sc.key, true +} + +// ScopeExtensionOf 按名字取回 ctx 里的扩展，没有时返回 nil。 +// +// 通常用不上——扩展实例是你自己创建的，直接拿着那个变量就行。这个函数是给 +// 「ctx 从别处传来、手上没有原对象」的场合准备的。 +func ScopeExtensionOf(ctx context.Context, name string) Extension { + sc, ok := scopeOf(ctx) + if !ok { + return nil + } + // 倒着找，同名时后注册的生效 + for i := len(sc.exts) - 1; i >= 0; i-- { + if sc.exts[i].Name() == name { + return sc.exts[i] + } + } + return nil +} + +func scopeOf(ctx context.Context) (*scope, bool) { + if ctx == nil { + return nil, false + } + sc, ok := ctx.Value(scopeCtxKey{}).(*scope) + return sc, ok +} + +// vmGlobals 拼出这个作用域下每个 VM 都要注入的全局：各个扩展的方法集、 +// 调用方给的 ScopeGlobals，加上一个描述作用域身份的 scope 对象。 +// +// 注入到各个 VM 里的扩展是同一个 Go 对象，所以同一个 ctx 下的脚本天然共享数据， +// 又不必共用 Runtime。 +func (sc *scope) vmGlobals() map[string]any { + g := make(map[string]any, len(sc.globals)+len(sc.exts)+1) + for _, ext := range sc.exts { + g[ext.Name()] = ext.Bindings() + } + // ScopeGlobals 优先级高于扩展 + for k, v := range sc.globals { + g[k] = v + } + g["scope"] = map[string]any{"key": sc.key} + return g +} + +func randomKey() string { + var b [12]byte + if _, err := rand.Read(b[:]); err != nil { + // crypto/rand 出问题时退回时间戳，重复的概率仍然极低 + return "t" + hex.EncodeToString([]byte(time.Now().Format(time.RFC3339Nano))) + } + return hex.EncodeToString(b[:]) +} diff --git a/script.go b/script.go new file mode 100644 index 0000000..6c5d3fb --- /dev/null +++ b/script.go @@ -0,0 +1,327 @@ +package jscriptx + +import ( + "context" + "fmt" + "sync/atomic" + + "github.com/dop251/goja" +) + +// DefaultFunc 传给 Call/Dispatch 的 fn 参数时，表示脚本的默认导出本身， +// 也就是 `export default function ...` 这种"整个脚本就是一个函数"的写法。 +// 默认导出是 class 或对象时用不上它——那种要按方法名调用。 +const DefaultFunc = "" + +// Script 是一份编译好的脚本，内部维护一个 VM 池。它并发安全，可以长期持有。 +// +// 一个 Script 对应一份不可变的编译产物；热更新时 Engine 会造一个新的 Script +// 顶替它，已经拿着旧 Script 的调用不受影响，会继续跑完旧版本。 +type Script struct { + engine *Engine + name string + version string + prog *goja.Program + + pool chan *vmHandle + closed atomic.Bool + + created atomic.Int64 // 累计新建过多少个 VM + dropped atomic.Int64 // 累计丢弃过多少个 VM（超时/panic/池满） +} + +// vmHandle 是一个 VM：一个 goja.Runtime 加上它跑完脚本后的求值结果。 +// Runtime 不是并发安全的，同一时刻只能有一个 goroutine 持有它。 +// +// 一个 VM 只跑一个脚本。会话下多个脚本要共享数据时靠 store（Go 侧对象，注入到各个 VM +// 里的是同一份引用），而不是共用 Runtime——共用 Runtime 会让会话内的所有脚本被迫串行。 +type vmHandle struct { + rt *goja.Runtime + defFn goja.Value // 脚本求值出的函数（单函数入口写法） + exports *goja.Object // 脚本求值出的对象（class 实例写法），方法调用时绑定为 this + ctor *goja.Object // 导出的 class 本身。静态方法挂在它上面，实例的原型链上没有 + + // scoped 表示这个 VM 注入过某个作用域的扩展，因此**不能**回池给别的作用域用。 + // 用完直接丢，见 release。 + scoped bool +} + +// Name 返回脚本名。 +func (s *Script) Name() string { return s.name } + +// Version 返回脚本版本号（Loader 给的，或者源码哈希）。 +func (s *Script) Version() string { return s.version } + +// Stats 是 VM 池的运行统计，用于观测。 +type Stats struct { + Pooled int // 池里闲置的 VM 数 + MaxVMs int // 池容量 + Created int64 // 累计新建 + Dropped int64 // 累计丢弃 +} + +// Stats 返回 VM 池的当前统计。 +func (s *Script) Stats() Stats { + return Stats{ + Pooled: len(s.pool), + MaxVMs: cap(s.pool), + Created: s.created.Load(), + Dropped: s.dropped.Load(), + } +} + +// Has 判断脚本导出的实例上有没有这个方法（继承来的也算）。 +func (s *Script) Has(fn string) bool { + inst, err := s.borrow(context.Background()) + if err != nil { + return false + } + defer s.release(inst, true) + _, _, _, ok := inst.lookup(fn) + return ok +} + +// Close 释放池里所有 VM。之后的调用会返回 ErrClosed。 +// 已经借出去、正在执行的调用不受影响，它们的 VM 归还时直接丢弃。 +// +// New 出来的实例不在这条链上——它们的生命周期归调用方，Close 之后那些实例的调用 +// 会因为脚本已关闭而报错，VM 等 GC 回收。 +func (s *Script) Close() { + if s.closed.Swap(true) { + return + } + for { + select { + case <-s.pool: + s.dropped.Add(1) + default: + return + } + } +} + +// borrow 从池里取一个 VM；池空就新建一个。 +// +// 刻意不阻塞等待：并发量超过池容量时宁可临时多造几个 VM，也不让请求在这里排队。 +// 池只是复用缓存，不承担限流职责。 +// +// ctx 带了作用域时**不走池**：池是所有调用共享的，而作用域的扩展是这一次调用专属的 +// （store、当前请求……）。混用要么让脚本看不见扩展（顶层 import 直接 ReferenceError）， +// 要么把上一个作用域的对象漏给下一个。所以为它单造一个 VM，用完丢弃。 +// +// 代价是这类调用每次约 5μs 建一个 VM。同一作用域下要反复调，用 New 拿实例更划算—— +// 实例把 VM 攥在手里，不必每次重建。 +func (s *Script) borrow(ctx context.Context) (*vmHandle, error) { + if sc, ok := scopeOf(ctx); ok { + // 作用域至少带一个 scope.key，所以只要有作用域就必然要单造 + vm, err := s.newVM(ctx, sc.vmGlobals(), nil) + if err != nil { + return nil, err + } + vm.scoped = true + return vm, nil + } + + select { + case inst := <-s.pool: + return inst, nil + default: + } + return s.newVM(ctx, nil, nil) +} + +// release 归还 VM。healthy 为 false（被中断过或 panic 过）时直接丢弃： +// 脚本本来就不该有跨调用状态，重建一个 VM 远比拖着一个状态可疑的 VM 划算。 +func (s *Script) release(inst *vmHandle, healthy bool) { + if inst == nil { + return + } + if !healthy || s.closed.Load() || inst.scoped { + // scoped 的 VM 带着某个作用域的扩展，回池就会漏给下一个调用 + s.dropped.Add(1) + return + } + select { + case s.pool <- inst: + default: + s.dropped.Add(1) // 池满，丢弃 + } +} + +// newVM 造一个新 VM 并在里面加载这个脚本：注入白名单（extra 是会话专属的额外全局， +// 池化调用传 nil）→ 跑一遍脚本顶层代码 → 记下求值结果。 +func (s *Script) newVM(ctx context.Context, extra map[string]any, ctorArgs []any) (*vmHandle, error) { + rt, err := s.engine.newRuntime(s.name, extra) + if err != nil { + return nil, err + } + return s.loadInto(ctx, rt, ctorArgs) +} + +// newRuntime 造一个空 VM 并注入白名单。scope 是它在日志和 store 里的身份： +// 池化 VM 用脚本名，会话 VM 用会话 key。 +func (e *Engine) newRuntime(scope string, extra map[string]any) (*goja.Runtime, error) { + rt := goja.New() + if e.maxStack > 0 { + rt.SetMaxCallStackSize(e.maxStack) + } + if err := e.bind(rt, scope, extra); err != nil { + return nil, err + } + return rt, nil +} + +// loadInto 在一个已经建好的 VM 里跑这个脚本，取出它的导出。 +// 顶层代码同样受超时保护，脚本在顶层写死循环不会把调用方卡住。 +// +// 同一个 rt 上可以先后加载多个脚本：打包产物是 IIFE，除了 ModuleGlobal 这一个全局名 +// 之外不往外泄漏东西，而那个名字的值在这里当场就取走了，后一个脚本覆盖它也不影响。 +func (s *Script) loadInto(ctx context.Context, rt *goja.Runtime, ctorArgs []any) (*vmHandle, error) { + return s.load(ctx, rt, ctorArgs, false) +} + +// load 把脚本装进一个 VM。noInstance 为 true 时不构造实例—— +// 只想调静态方法时用，避免白跑一遍 constructor（那是每次调用的准备工作）。 +func (s *Script) load(ctx context.Context, rt *goja.Runtime, ctorArgs []any, noInstance bool) (h *vmHandle, err error) { + stop := guard(ctx, rt, s.engine.timeout) + defer stop() + defer func() { + if r := recover(); r != nil { + h, err = nil, s.panicError(DefaultFunc, nil, r) + } + }() + + v, err := rt.RunProgram(s.prog) + if err != nil { + return nil, classify(err, s.name, DefaultFunc, nil) + } + + h = &vmHandle{rt: rt} + // 打包产物末尾的入口表达式求值出来的东西决定了脚本的形态： + // class → 由这里 new 出实例，构造参数从 Go 侧传（export default class X {}） + // 普通函数 → 单函数入口，用 DefaultFunc 调用（export default function(){}） + // 非函数对象 → 直接当导出实例（export default {...}，或只有命名导出时的模块对象） + if !empty(v) { + switch { + case isClass(rt, v): + h.ctor = v.ToObject(rt) + if noInstance { + break // 只要静态方法，不跑 constructor + } + obj, err := construct(rt, v, ctorArgs) + if err != nil { + return nil, classify(err, s.name, "constructor", ctorArgs) + } + h.exports = obj + case isCallable(v): + h.defFn = v + default: + if obj, ok := v.(*goja.Object); ok { + h.exports = obj + } + } + } + s.created.Add(1) + return h, nil +} + +// classDetector 判断一个值是不是 class。goja 的 AssertConstructor 对普通 function +// 也返回 true，区分不了；靠规范保证的差别来判：class 的 prototype 属性不可写， +// 普通函数的可写，箭头函数和方法简写根本没有 prototype。 +var classDetector = goja.MustCompile("jscriptx:isclass", `(function (x) { + if (typeof x !== "function") { return false } + var d = Object.getOwnPropertyDescriptor(x, "prototype") + return !!d && d.writable === false +})`, true) + +func isClass(rt *goja.Runtime, v goja.Value) bool { + if _, ok := goja.AssertConstructor(v); !ok { + return false + } + dv, err := rt.RunProgram(classDetector) + if err != nil { + return false + } + detect, ok := goja.AssertFunction(dv) + if !ok { + return false + } + res, err := detect(goja.Undefined(), v) + if err != nil { + return false + } + return res.ToBoolean() +} + +func isCallable(v goja.Value) bool { + _, ok := goja.AssertFunction(v) + return ok +} + +// construct 从 Go 侧 new 一个 JS class 实例，构造参数按 goja 的规则转换。 +func construct(rt *goja.Runtime, class goja.Value, args []any) (*goja.Object, error) { + ctor, ok := goja.AssertConstructor(class) + if !ok { + return nil, fmt.Errorf("不是构造器") + } + jsArgs := make([]goja.Value, len(args)) + for i, a := range args { + jsArgs[i] = rt.ToValue(a) + } + return ctor(nil, jsArgs...) +} + +// lookup 找要调用的函数，同时给出调用时该绑定的 this。 +// +// fn 为空取默认导出本身（export default function 那种）；否则找导出实例的方法， +// this 绑定到实例，这样 class 里的 this.xxx 才有意义。 +// +// 最后那层全局查找基本只是兜底：脚本经打包后是 IIFE，顶层声明进不了全局， +// 只有脚本显式往 globalThis 上挂东西时才走得到。 +func (i *vmHandle) lookup(fn string) (callable goja.Callable, fnVal goja.Value, this goja.Value, ok bool) { + if fn == DefaultFunc { + if i.defFn == nil { + return nil, nil, nil, false + } + callable, ok = goja.AssertFunction(i.defFn) + return callable, i.defFn, goja.Undefined(), ok + } + + if i.exports != nil { + // Get 会走原型链，class 方法定义在 prototype 上也找得到 + if v := i.exports.Get(fn); v != nil && !goja.IsUndefined(v) && !goja.IsNull(v) { + if callable, ok = goja.AssertFunction(v); ok { + return callable, v, i.exports, true + } + } + } + + // 静态方法挂在 class 自身上，不在实例的原型链上，所以实例那边找不到才轮到这里。 + // this 绑定到 class 本身，跟 JS 里 C.Startup() 的语义一致。 + if i.ctor != nil { + if v := i.ctor.Get(fn); v != nil && !goja.IsUndefined(v) && !goja.IsNull(v) { + if callable, ok = goja.AssertFunction(v); ok { + return callable, v, i.ctor, true + } + } + } + + v := i.rt.Get(fn) + if v == nil || goja.IsUndefined(v) || goja.IsNull(v) { + return nil, nil, nil, false + } + if callable, ok = goja.AssertFunction(v); !ok { + return nil, nil, nil, false + } + return callable, v, goja.Undefined(), true +} + +// notFoundHint 在找不到函数时给一句有用的话。最常见的原因是脚本压根没写 export： +// 打包产物是 IIFE，没有导出的顶层代码会被当死代码摇掉，什么都不剩。 +func (s *Script) notFoundHint(inst *vmHandle) string { + if inst.exports == nil && inst.defFn == nil { + return "脚本没有任何导出。打包产物是 IIFE，不写 export 的顶层代码会被当死代码摇掉；" + + "请用 export default 指明入口，或者用命名导出" + } + return "脚本里没有这个函数，或者它不是函数" +} diff --git a/static.go b/static.go new file mode 100644 index 0000000..adbbceb --- /dev/null +++ b/static.go @@ -0,0 +1,86 @@ +package jscriptx + +import "context" + +// CallStatic 调用脚本导出的 class 上的**静态方法**。 +// +// export default class PkgImportController { +// static Startup() { store.Set("pkg.registry", "https://…") } +// Execute(g) { … } +// } +// +// _, err := script.CallStatic(ctx, "Startup") +// +// 它跟 Call 有两点不同，都是"静态"这个语义要求的： +// +// - **不构造实例**：constructor 不会跑。构造函数做的是"这一次调用的准备"， +// 跟脚本级的初始化无关，跑它只会白费一遍还可能有副作用。 +// - **VM 用完就丢**，不回池。静态方法一般只在脚本生命周期里跑一两次， +// 为它留一个 VM 不划算；而且它做的事通常是往 Go 侧扩展里写东西， +// 那些副作用留在 Go 那边，VM 本身没有保留的价值。 +// +// 脚本没写这个静态方法时返回的错误可以被 errors.Is(err, ErrFuncNotFound) 匹配上 +// ——生命周期钩子多半是可选的，用它来区分"没写"和"写了但炸了"： +// +// if _, err := script.CallStatic(ctx, "Startup"); err != nil && +// !errors.Is(err, ErrFuncNotFound) { +// return err // 真的出错了 +// } +// +// 静态方法里能用 ctx 带进来的作用域扩展（WithScope），这正是它的用武之地： +// 把配置写进 store、往 Go 侧注册东西。但**它建的 JS 对象活不下来**—— +// VM 一丢就没了，别指望后续调用能看到。 +func (s *Script) CallStatic(ctx context.Context, fn string, args ...any) (any, error) { + if fn == DefaultFunc { + return nil, newError(KindNotFound, s.name, fn, ErrFuncNotFound, + "CallStatic 要给一个静态方法名") + } + return callAny(ctx, staticTarget{s}, fn, args) +} + +// HasStatic 判断脚本导出的 class 上有没有这个静态方法。 +// +// 它要建一个 VM 才能回答，所以别在热路径上反复调；只想"有就调"的话， +// 直接 CallStatic 然后判 ErrFuncNotFound 更省。 +func (s *Script) HasStatic(fn string) bool { + if fn == DefaultFunc { + return false + } + vm, err := s.borrowStatic(context.Background()) + if err != nil { + return false + } + _, _, _, ok := vm.lookup(fn) + return ok && vm.ctor != nil +} + +// staticTarget 让静态调用复用 invoke 那一整套（超时中断、panic 恢复、错误分类）， +// 只是换一种取 VM 的方式：不构造实例，用完丢弃。 +type staticTarget struct{ s *Script } + +func (t staticTarget) owner() *Script { return t.s } + +func (t staticTarget) acquire(ctx context.Context) (*vmHandle, error) { + return t.s.borrowStatic(ctx) +} + +// finish 直接丢弃，不回池——见 CallStatic 的说明。 +func (t staticTarget) finish(*vmHandle, bool) { t.s.dropped.Add(1) } + +// borrowStatic 造一个只装了 class、没有实例的 VM。 +func (s *Script) borrowStatic(ctx context.Context) (*vmHandle, error) { + if s.closed.Load() { + return nil, newError(KindClosed, s.name, "", ErrClosed, "脚本已关闭") + } + + var extra map[string]any + if sc, ok := scopeOf(ctx); ok { + extra = sc.vmGlobals() + } + + rt, err := s.engine.newRuntime(s.name, extra) + if err != nil { + return nil, err + } + return s.load(ctx, rt, nil, true) +}