WASM 扩展

WASM 扩展

AI 原文

WASM 扩展

功能

WASM 扩展使用 WASM/WASI 模块作为后端入口，适合用 Rust 编写高性能逻辑、复杂状态管理或需要更清晰 ABI 边界的扩展。它的 manifest.kind 为 wasm，manifest.abi 为 bts-wasi-1。

BT 提供 bt-extension-sdk Rust SDK，帮助扩展作者处理 BtValueBinary 编解码、WASM 线性内存分配释放、调用 ID 分发和扩展对象句柄。

语法

WASM 扩展通常使用 module.wasm 作为入口：

WASM 模块必须导出：

导出说明
memoryWASM 线性内存。
bts_alloc(len) -> ptr给宿主写入参数申请内存。
bts_call(id, args_ptr, args_len) -> packed_ptr_len根据调用 ID 执行业务逻辑并返回结果缓冲区。
bts_free(ptr, len)释放宿主传回的参数或返回值内存。

模块可以额外导出这些函数：

导出说明
bts_set_module_id(module_id)宿主实例化模块后调用，SDK 用该模块 ID 创建扩展对象句柄。
bts_init(config_ptr, config_len) -> packed_ptr_lenworker 初始化后调用，参数是宿主整理后的 runtime 配置对象。
bts_shutdown() -> packed_ptr_lenworker 正常退出前调用，用于释放扩展内部连接或缓存。
bts_stats() -> packed_ptr_len返回扩展侧统计对象，供宿主后续调试接口汇总。

生命周期导出是可选的。旧 WASM 扩展不导出这些函数时仍可正常运行；如果导出，签名必须和表格一致。

参数

WASM 扩展收到的参数来自 BtValueBinary 编码后的数组。入口函数参数按 bindings 顺序传入；对象方法参数会在最前面额外收到接收者 ExtObject 句柄。

返回值

WASM handler 通过 SDK 返回 BtValue。返回原始类型时必须和 bindings 的 returns 匹配；返回对象类型时必须返回当前模块创建的同类型 ExtObject。

Rust SDK 流程

创建 WASM 扩展：

脚手架中的核心结构类似：

这里的数字必须和 bindings.json 里的函数或方法 id 一致。

如果扩展需要生命周期导出，可以使用 SDK 提供的独立 helper 宏：

bt_extension! 仍只负责 bts_alloc、bts_free、bts_set_module_id 和 bts_call，不会强制旧扩展导出生命周期函数。

对象句柄

WASM 扩展不能把 Rust 对象直接交给 BT 脚本。正确做法是：

1. 扩展内部用 ObjectStore 保存真实状态。

2. 返回 ExtObject 句柄给 BT。

3. 脚本调用对象方法时，宿主把这个句柄作为第一个参数传给 WASM handler。

4. handler 根据对象 ID 找到扩展内部状态，再执行方法。

脚本侧仍然是普通链式调用：

脚本中的 type() 会返回 bindings 对象名，而不是低层 ABI 标签：

BtValueBinary

bts-wasi-1 使用 BtValueBinary 在宿主和 WASM 之间传输值。它会保留 empty 与 null 的区别，并支持普通值、Bytes、数组、对象和扩展对象句柄。

不支持通过 ABI 传输函数、类实例、正则、标准库对象、任务、定时器、迭代器或循环引用数组/对象。

shared runtime

WASM 扩展默认使用 runtime.mode: "thread_local"，运行态会按调用线程缓存。需要跨请求复用昂贵初始化状态、连接或缓存时，可以在 manifest.json 中声明 runtime.mode: "shared"。

shared WASM 扩展会使用项目级 ExtensionService：

1. 调用线程按 bindings 处理参数和路径 role。

2. 调用线程把参数编码成 BtValueBinary 字节。

3. 服务把调用 ID、返回类型、调用标签、参数字节和回复通道投递到有界 worker 队列。

4. worker 内持有独立 WASM Store/Instance，调用 bts_call。

5. worker 返回结果字节，调用线程解码成 BT 值。

6. 如果返回扩展对象，宿主把 worker 本地对象 ID 改写成脚本可见 host_object_id；对象方法调用时再改写回创建 worker 的本地对象 ID。

当前阶段支持 shared 入口函数和对象方法返回原始值或扩展对象。lifecycle: "dispose" 的 close() / dispose() 方法成功后，宿主会移除对象路由，旧句柄再次调用会报已失效。

shared worker 会启用 Wasmtime epoch interrupt。call_timeout_ms 到期时，调用线程会标记目标 worker 并触发 epoch 检查；该 worker 捕获超时 trap 后会丢弃当前 WASM Store/Instance 并重建，后续调用不会被永久占用的 worker 卡住。

注意事项

  • WASM 模块包含 start section 会被拒绝。
  • thread_local WASM Runner 会延迟实例化模块，并在线程本地缓存实例。
  • shared WASM 扩展使用独立有界 worker 队列；队列满或服务关闭时会返回中文错误，不会落回线程本地 Runner。
  • shared WASM 扩展多 worker 下会使用宿主级对象路由，避免不同 worker 内相同本地对象 ID 互相冲突。
  • shared WASM 扩展调用超时会统计 timeout，并中断目标 worker 的 WASM 执行；其他 worker 不会因为同一个超时调用被强制重建。
  • 可选生命周期导出只在存在时调用；不导出 bts_init、bts_shutdown、bts_stats 的旧扩展保持兼容。
  • 普通 object 返回类型可以用 empty 表示无结果，例如 SQLite one() 查不到行；具体扩展对象返回类型仍必须返回同模块、同类型对象句柄。
  • WASM 返回对象类型时，必须返回同模块、同类型的扩展对象句柄。
  • SDK 内部错误信息仍可使用 ext_object 这类 ABI 分类；脚本层 type() 返回的是 bindings.json 声明的对象类型名。
  • 长期持有状态的 WASM 对象应提供 close() 或 dispose()，并在 handler 中释放扩展内部状态。
  • bt ext new --kind wasm 生成的是 Rust SDK 项目骨架；仍需要先编译 WASM 并复制为 module.wasm 后再打包。