WASM 宿主嵌入 API：在 Rust/C/Go/Python 中跑 WASM 模块

嵌入形态：
[宿主应用（Rust/Go/Python/C…）]
   └─ 运行时库（wasmtime/wasmer/v8…）
        └─ 加载 .wasm 模块
             └─ 实例化 + 调用导出函数
                  └─ host 函数回调宿主（可选）

典型场景：
□ 插件系统：第三方逻辑（配置/模板/计费规则）编成 WASM 动态加载
□ FaaS 单元：把函数即模块，沙箱隔离执行
□ 规则引擎/脚本：用户自定义逻辑安全执行
□ 跨语言：团队用 Rust 写核心，业务用 Python 嵌入调用

Config     → 运行时配置（特性开关、cache、资源上限）
Engine     → 全局引擎（编译与执行），进程通常一个
Module     → 编译后的模块（可缓存、可共享）
Store      → 实例状态空间（每实例一个，隔离状态）
Instance   → 模块 + store 的具体实例
Imports    → 实例化时注入的宿主能力（host 函数/内存/表）
Exports    → 模块导出的函数/内存（宿主可调用）

典型流程（各语言一致）：
1. 创建 Engine + Store
2. 编译/加载 Module
3. 构造 Imports（注入 host 能力）
4. Instance::new → 实例化
5. 通过导出函数调用，或访问导出内存

use wasmtime::{Engine, Module, Store, Instance};

// 1. 引擎 + 存储
let engine = Engine::default();
let mut store = Store::new(&engine, ());

// 2. 编译模块
let module = Module::from_file(&engine, "plugin.wasm")?;

// 3. 实例化（可传 imports）
let instance = Instance::new(&mut store, &module, &[])?;

// 4. 调用导出函数
let add = instance.get_typed_func::<(i32, i32), i32>(&mut store, "add")?;
let result = add.call(&mut store, (2, 3))?;
assert_eq!(result, 5);

Rust API 要点：
□ 类型安全：get_typed_func 把 WASM 类型映射成 Rust 泛型
□ store 显式传递：调用函数必须带 &mut store
□ Config：可用 Config 开关特性（wasm-gc、stack-switching、WASI preview2）
□ 嵌入与异步：store 支持异步 I/O 嵌入（async store）

C API 是「稳定 ABI」：
□ wasmtime 提供 C 头文件 + 共享库
□ Go/Python/其他语言通过 cgo/cffi 绑定
□ 所有语言看到的是同一套 wasm_engine_t / wasm_store_t / wasm_instance_t

核心句柄：
wasm_engine_t、wasm_store_t、wasm_module_t
wasm_instance_t、wasm_func_t、wasm_memory_t

// C API 示例（简化）
wasm_engine_t* engine = wasm_engine_new();
wasm_store_t* store = wasm_store_new(engine);
// 编译/实例化/调用...（句柄 + 错误码）

import "wasmtime-go"

engine := wasmtime.NewEngine()
store := wasmtime.NewStore(engine)
module, _ := wasmtime.NewModule(engine, wasmBytes)
instance, _ := wasmtime.NewInstance(store, module, []wasmtime.AsExtern{})

add := instance.GetFunc(store, "add")
result, _ := add.Call(store, 2, 3)
fmt.Println(result)   // 5

Go 嵌入要点：
□ 面向对象包装（NewEngine/NewStore/NewInstance）
□ Call 返回 interface{}（动态类型，Go 侧做类型断言）
□ 与 Rust 相比类型安全弱一些，但集成分钟级
□ 适合：Go 服务里嵌入规则/脚本插件

import wasmer

engine = wasmer.engine.JIT()
store = wasmer.Store(engine)
module = wasmer.Module(store, wasm_bytes)
wasi_env = wasmer.wasi.WasiVersion.LATEST
imports = wasmer.wasi.get_imports(store, wasi_env)

instance = wasmer.Instance(module, imports)
result = instance.exports.add(2, 3)   # 直接当 Python 函数调用
print(result)                          # 5

Python 嵌入要点：
□ exports.函数名直接调用（wasmer 生成 Python 可调用对象）
□ WASI imports 一行注入（wasi.get_imports）
□ 性能：Python 侧的开销主要在「边界往返」，适合「低频但需要隔离」的逻辑
□ 典型：ML 服务里嵌入规则/后处理、配置文件里的自定义函数

// Rust：注册一个 host 函数给 WASM 调用
let log_func = Func::wrap(&mut store, |caller: Caller<'_, ()>, msg: String| {
    println!("[wasm] {msg}");           // 宿主侧处理（打日志/写库/发请求）
});
let imports = vec![log_func.into()];
let instance = Instance::new(&mut store, &module, &imports)?;
// WASM 侧 import "env" "log" (func (param i32))

host 函数用途：
□ 日志/监控：WASM 回传执行信息
□ 数据访问：让 WASM 读宿主数据库/缓存（经宿主 API，而非直接网络）
□ 能力授权：宿主决定「这个模块能做什么」（读哪个表、调哪个服务）
□ 回调：WASM 主动触发宿主流程

安全原则：
□ host 函数是「能力出口」——每个都要最小授权
□ 不在 host 函数里盲目信任 WASM 传入的值（校验）
□ 传给 WASM 的引用/句柄用 externref 承载，避免裸指针

数据传递模式：
□ 标量：i32/f64 直接作为函数参数/返回值（零拷贝）
□ 缓冲区：WASM 导出内存 → 宿主按「指针 + 长度」访问
□ 引用：externref 承载宿主对象（WASM 只持有不透明句柄）
□ 结构化：组件模型/WIT 类型（跨语言复杂类型，见组件篇）

线性内存访问（Rust 示例）：
let memory = instance.get_memory(&store, "memory")?;
let data = memory.data(&store);          // &[u8]，直接读
// 写入前先检查偏移+长度在 memory size 内（防越界）

// 读取 WASM 导出的缓冲区
let buf_ptr = instance.get_typed_func::<(), i32>(&mut store, "get_ptr")?
    .call(&mut store, ())?;              // 拿到指针
let data = &memory.data(&store)[buf_ptr as usize .. buf_ptr as usize + len];

选型考虑：
□ 深度 WASI/组件模型 → Wasmtime（参考实现）
□ 多语言绑定广度、需要 LLVM 后端 → Wasmer
□ 极致冷启动 → 看 AOT + 缓存（Wasmtime 的 compile 产物）
□ 嵌入形态：两者都是「进程内库」，写法相近