Node.js 中嵌入 WASM：原生 API、WASI 与实例池实践

const fs = require('node:fs');

// 编译一次，多次实例化：编译产物是可复用的
const bytes = fs.readFileSync('./plugin.wasm');
const module = await WebAssembly.compile(bytes);

const instance = await WebAssembly.instantiate(module, imports);
instance.exports.handle(0);

┌─ Node 主线程 ────────────────────────────┐
│  Module(编译一次) ─▶ Instance ─▶ exports  │
│        │                 │               │
│  linear Memory ◀─── imports(host 函数)   │
└──────────────────────────────────────────┘
与浏览器一致，差别在于 Node 没有 fetch，需自行读文件或读网络流。

WebAssembly.instantiate(bytes)  异步，内部走后台编译，推荐
new WebAssembly.Instance(module) 同步，阻塞事件循环，仅限极小模块
实践：启动阶段用异步编译预热，请求路径上只做「从池里取实例」。

const { WASI } = require('node:wasi');

const wasi = new WASI({
  version: 'preview1',
  args: ['plugin'],
  env: { NODE_ENV: 'production' },
  preopens: { '/data': '/var/app/data' },   // 唯一可见的目录
});

const instance = await WebAssembly.instantiate(bytes, wasi.getImportObject());
wasi.start(instance);

WASI 的核心理念是「能力即授权」：
  没有全局文件系统，只有宿主显式 preopen 的目录
  没有环境变量泄漏，只有显式传入的 env
  没有网络，除非宿主提供对应的 socket 扩展
反过来：宿主给什么，模块才能用什么 —— 默认拒绝是默认值。

node:wasi 的现状与边界：
  支持 preview1（wasi_snapshot_preview1）
  不支持 preview2 / 组件模型（需用其他运行时如 Wasmtime）
  生产建议：纯计算型模块用原生 API + 自定 host 函数，
            需要文件/环境的模块才引入 WASI。

实例化的成本构成：
  编译（可复用，只做一次）
  实例化（创建内存、初始化数据段、绑定导入）—— 每实例一次
  初始化（跑模块的 _start / init 钩子）—— 每实例一次

实测：编译一个中等模块约 5~20 ms，实例化约 0.1~1 ms。
高频请求下，实例化开销累积明显，池化能把它摊平。

class InstancePool {
  constructor(module, imports, size = 8) {
    this.module = module;
    this.imports = imports;
    this.idle = [];
    for (let i = 0; i < size; i++) this.idle.push(this.create());
  }
  create() { return new WebAssembly.Instance(this.module, this.imports); }
  acquire() { return this.idle.pop() || this.create(); }   // 池空则新建
  release(inst) { this.idle.push(inst); }                  // 归还前需 reset
}

池化的三条纪律：
  1. 归还前必须重置状态（清线性内存或调用模块的 reset 导出）
  2. 池要有上限，避免内存无限增长
  3. 崩溃（trap）的实例不能归还，直接丢弃重建

const imports = {
  env: {
    log: (ptr, len) => {                    // 模块调用宿主的日志
      const view = new Uint8Array(instance.exports.memory.buffer, ptr, len);
      console.log('[plugin]', Buffer.from(view).toString('utf8'));
    },
    now_ms: () => Date.now(),               // 返回 i64 时需 BigInt
  },
};

// 把字符串写入 WASM 线性内存：先向模块申请空间
function writeString(inst, str) {
  const bytes = Buffer.from(str, 'utf8');
  const ptr = inst.exports.alloc(bytes.length);      // 插件导出 alloc
  new Uint8Array(inst.exports.memory.buffer, ptr, bytes.length).set(bytes);
  return { ptr, len: bytes.length };
}

三条铁律：
  1. 跨边界只传「指针 + 长度」，字符串用 UTF-8 字节
  2. 读写前重新取 memory.buffer（增长会让旧视图失效）
  3. 谁分配谁释放，或跨边界显式调用对方的 dealloc
宿主绝不能直接 new 一个视图长期持有 —— 增长即 detached。

WASM 执行是同步的：一次调用会独占事件循环直到返回。
  短任务（< 1 ms）  直接在主线程跑，无碍
  长任务（数十毫秒）会拖垮整个服务的 P99，必须隔离
隔离手段：worker_threads 把 WASM 执行挪到独立线程。

const { Worker } = require('node:worker_threads');

const worker = new Worker('./wasm-worker.js', {
  workerData: { wasmPath: './plugin.wasm' },
});
worker.postMessage({ type: 'call', fn: 'handle', input });
worker.on('message', (result) => { /* 回传结果 */ });

线程池 + 实例池的组合：
  每个 Worker 线程内持有自己的模块与实例池
  主线程只做调度：选线程 → 投递任务 → 等结果
好处：崩溃（trap）只终结该 Worker，主进程可重启它；
      长任务不再阻塞主线程事件循环。
代价：跨线程消息需要结构化克隆（大对象建议用 SharedArrayBuffer）。

插件加载四步：
  1. 读字节 → WebAssembly.compile → 得到可复用 Module
  2. 校验元信息（版本号、能力位图）与签名
  3. 构建 imports（只注入被授权的 host 函数）
  4. 实例化并跑 init 钩子，失败即拒绝加载

async function loadPlugin(path, grantedCaps) {
  const module = await WebAssembly.compile(fs.readFileSync(path));
  const imports = buildImports(grantedCaps);        // 按能力构建
  const instance = await WebAssembly.instantiate(module, imports);
  const meta = instance.exports.plugin_meta();      // 读版本与能力
  if (!compatible(meta)) throw new Error('incompatible plugin');
  return { module, instance, meta };
}

热更新安全流程：
  新版本加载到独立实例 → 校验 meta → 预热 init → 原子替换注册表引用
  → 旧实例等待在途调用完成后回收
Node 侧用 Map 存 id → { module, pool }，替换即改引用，无需重启进程。

// 进程内：把 Module 缓存在全局，避免重复编译
const moduleCache = new Map();
async function getModule(path) {
  if (!moduleCache.has(path)) {
    moduleCache.set(path, await WebAssembly.compile(fs.readFileSync(path)));
  }
  return moduleCache.get(path);
}

WASM 天然提供的隔离：
  独立的线性内存（越界即 trap，不污染宿主）
  只能调用宿主显式注入的 import
  无系统调用，文件/网络/时间都必须由宿主提供
WASM 不提供的：
  默认没有 CPU 时间上限、没有内存上限、没有调用次数上限
  → 这些必须由宿主（Node 层）自行施加

// 内存上限：通过导入自定义 memory 并限制其 maximum
const memory = new WebAssembly.Memory({
  initial: 16, maximum: 256,   // 上限 256 页 = 16 MiB
});
const imports = { env: { memory } };

// CPU 上限：Node 无 fuel 机制 → 用 Worker + 墙钟超时兜底
const timer = setTimeout(() => worker.terminate(), 2000);

四类配额与实现方式：
  内存   自定义 Memory 设 maximum
  时间   Worker + terminate 墙钟超时（或换用支持 fuel 的运行时）
  调用   在 host 函数入口做计数与限流
  输出   限制返回值大小，防止内存放大攻击

每个插件独立采集：
  调用次数 / 错误率 / P50 与 P99 延迟
  实例池命中率与新建次数
  线性内存峰值与当前页数
  trap 次数与原因分布

const start = process.hrtime.bigint();
try {
  instance.exports.handle(ptr);
  metrics.ok(pluginId);
} catch (err) {                       // WebAssembly.RuntimeError
  metrics.trap(pluginId, err.message);
  pool.discard(instance);             // trap 实例不归还
} finally {
  metrics.observe(pluginId, Number(process.hrtime.bigint() - start) / 1e6);
}

三类故障与对策：
  trap（越界/除零）  → 丢弃实例、返回错误码、计数告警
  超时              → terminate Worker 并重建，请求返回 503
  内存耗尽          → 捕获分配失败，降级为拒绝新请求并排空
原则：最差的插件只能拖慢自己，绝不能拖垮宿主进程。

[ ] 编译只在启动阶段，请求路径零编译
[ ] Module 进程内缓存，实例池设上限并 reset
[ ] 长任务走 worker_threads，有墙钟超时兜底
[ ] 自定义 Memory 设 maximum，host 函数限输出大小
[ ] 所有 malloc / 调用失败路径有降级，不崩溃
[ ] 按插件采集调用/延迟/内存/trap 指标
[ ] 插件包签名校验，meta 做版本兼容检查
[ ] trap 实例不归还池，超时 Worker 重建