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 在脚本里表现为抛异常，不占返回值位置。
- 脚本能看见的全局只有白名单放行的那些，且注入是惰性的——没读到的
全局根本不会被转换。
This commit is contained in:
@@ -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())
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
+41
@@ -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, " ")
|
||||
}
|
||||
@@ -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
|
||||
@@ -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...)
|
||||
}
|
||||
@@ -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...) }
|
||||
}
|
||||
@@ -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 = "<anonymous>"
|
||||
}
|
||||
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 ""
|
||||
}
|
||||
+108
@@ -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
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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
|
||||
)
|
||||
@@ -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=
|
||||
+174
@@ -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
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
@@ -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))
|
||||
}
|
||||
+238
@@ -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)
|
||||
@@ -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[:])
|
||||
}
|
||||
@@ -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 "脚本里没有这个函数，或者它不是函数"
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
Reference in New Issue
Block a user