jscriptx/errors.go

package jscriptx

import (
	"errors"
	"fmt"
	"log/slog"
	"strconv"
	"strings"
)

// 哨兵错误，配合 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: 已关闭")
	// 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"      // 返回值/参数类型不匹配
	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,
	}
}