用 WASM 设计插件系统：宿主 ABI、版本兼容与热加载

四种扩展机制的对比：
  动态库（.so/.dll）  同进程、最快，但无隔离、ABI 脆弱、崩溃传染
  子进程 / 容器       隔离好，但启动百毫秒级、IPC 成本高
  脚本引擎（Lua/JS）  灵活，但性能与沙箱强度有限
  WASM 插件           同进程微秒启动 + 强隔离 + 跨语言

1. 插件不能直接访问宿主内存 → 数据必须通过线性内存拷贝或共享区交换
2. 插件不能发起系统调用 → 文件/网络/日志必须由宿主注入
3. 插件崩溃（trap）会终止实例，但不影响宿主进程
4. 插件实例有状态，重启即丢内存 → 要么无状态化，要么快照

最常见的两种 ABI 风格：
  指针+长度（多数宿主采用）
    插件导出 alloc(len) -> ptr，宿主写入字节后调用
    宿主导出 write(ptr, len) 回调插件
  单缓冲区（Proxy-Wasm 风格）
    宿主分配一块线性内存，双方约定 offset 与长度布局
    避免反复 alloc/free，适合高频调用

// 插件侧（Rust）导出分配与释放，供宿主写入数据
#[no_mangle]
pub extern "C" fn alloc(len: usize) -> *mut u8 {
    let mut buf = Vec::with_capacity(len);
    let ptr = buf.as_mut_ptr(); std::mem::forget(buf); ptr
}
#[no_mangle]
pub extern "C" fn dealloc(ptr: *mut u8, len: usize) {
    unsafe { drop(Vec::from_raw_parts(ptr, 0, len)) };
}

所有权规则：
  1. 宿主调用插件：宿主分配输入 → 插件只读 → 宿主释放
  2. 插件返回数据：插件分配 → 宿主读取 → 宿主调用 dealloc 归还
  3. 插件注册的回调：宿主持有句柄，插件卸载前必须注销
  4. 任何一方都不得假设对方的 allocator 与自己兼容

三种协商模式：
  编译期绑定    插件编译时链接固定版本宿主接口 → 升级即全部重编
  运行时探测    插件导出一个描述函数，宿主读取后决定调用路径
  能力位图      插件声明支持的能力集合，宿主按交集调用

// 插件导出元信息：版本 + 能力位图
#[no_mangle]
pub extern "C" fn plugin_meta() -> u64 {
    let abi_major: u64 = 2;
    let abi_minor: u64 = 3;
    let caps: u64 = 0b1011;      // 位 0: 日志，位 1: HTTP，位 3: 存储
    (abi_major << 48) | (abi_minor << 32) | caps
}

major 不同 → 拒绝加载（破坏性变更）；major 相同且插件 minor 不大于宿主
minor → 允许；插件 minor 大于宿主 → 拒绝或降级；能力位图取交集，宿主不
认识的能力静默忽略。

// Wasmtime：用 StoreLimits 限制单实例资源
let limits = StoreLimitsBuilder::new()
    .memory_size(32 * 1024 * 1024)   // 内存上限 32MiB
    .instances(1)
    .tables(2)
    .build();
store.limiter(|s| &mut s.limits);

配额维度：内存上限（防吃光宿主内存）、实例数（防无限 new 实例）、
并发调用数（防占满线程池）、表大小（限制间接调用表）。

// 燃料（fuel）：把 CPU 时间换算成可扣减的计量单位
config.consume_fuel(true);
store.set_fuel(10_000_000)?;           // 给插件 1000 万单位
match instance.get_typed_func::<(), ()>(&mut store, "run")?.call(&mut store, ()) {
    Err(e) if e.downcast_ref::<Trap>().is_some() => { /* 燃料耗尽 → 降级 */ }
    r => r?,
}

fuel 是确定性计量，跨机器可复现，适合计费与配额；epoch 中断由宿主线程定期
递增 epoch 异步打断超时实例，适合「墙钟时间」语义且开销极低。

热加载的安全流程：新版本加载到独立实例（旧实例继续服务）→ 校验 meta 与
能力集（不兼容即中止）→ 预热跑一次初始化钩子（失败即回滚）→ 原子切换路由
指针 → 旧实例等待在途请求完成后释放。

// 用 Arc<RwLock<Instance>> 做原子切换
let new_inst = load_plugin(&engine, &bytes)?;
let mut guard = registry.write().unwrap();
guard.insert(plugin_id, Arc::new(new_inst));   // 切换瞬间完成
// 旧 Arc 的引用计数归零后自然释放

插件状态的三类处理：
  无状态插件     最理想，热加载无痛
  可序列化状态   卸载前导出快照，加载后导入
  不可迁移状态   拒绝热加载，要求重启宿主或等待排空

// 快照接口约定
#[no_mangle] pub extern "C" fn snapshot(alloc: extern "C" fn(usize) -> *mut u8) -> u64;
#[no_mangle] pub extern "C" fn restore(ptr: *const u8, len: usize) -> i32;

默认完全隔离：每个插件一个 Store/实例，互不可见
可选的共享：
  共享内存（shared memory）→ 性能好，但要自己做同步与边界检查
  宿主中介消息            → 安全可控，是推荐默认值
  共享表（shared table）  → 极少用，破坏隔离假设

// 插件 A 发消息给插件 B，全程经过宿主校验
#[no_mangle]
pub extern "C" fn emit(target: u32, ptr: *const u8, len: usize) -> i32 {
    let payload = unsafe { std::slice::from_raw_parts(ptr, len) };
    // 宿主检查：A 是否有权向 target 发送？payload 是否超限？
    // 通过后投递到 B 的收件队列
    0
}

消息层必须做的四道检查：发送方权限（能否向该目标发送）、消息大小上限
（防内存放大）、频率限制（防互相刷爆）、死信与循环检测（防 A→B→A 无限循环）。

典型能力清单（按风险从低到高）：log（写日志）、config（读自己的配置）、
kv（读写宿主键值存储）、http（需域名白名单）、fs（需目录白名单）、
secret（读密钥，需显式声明用途）。

// 宿主侧：每次能力调用都做一次校验
fn check_cap(store: &Store<HostState>, cap: Cap, arg: &str) -> Result<(), Trap> {
    let state = store.data();
    if !state.granted.contains(&cap) {
        return Err(Trap::new("capability not granted"));
    }
    if cap == Cap::Http && !state.http_allow.iter().any(|d| arg.ends_with(d)) {
        return Err(Trap::new("domain not allowed"));
    }
    Ok(())
}

授权模型的三个原则：
  1. 默认拒绝：未声明的能力一律不可用
  2. 声明式清单：插件包内附 manifest，列出所需能力
  3. 运行时可收窄：宿主可授予清单的子集，绝不放大

每个插件必须独立采集：调用次数 / 错误率 / P99 延迟、燃料消耗（CPU 代理
指标）、内存峰值与当前占用、trap 次数与原因分布、按能力分桶的调用次数。

let start = Instant::now();
let result = instance.call(&mut store, "handle", (req_ptr, req_len));
metrics.observe(plugin_id, "latency", start.elapsed());
metrics.inc(plugin_id, if result.is_err() { "error" } else { "ok" });

连续 N 次 trap → 熔断；P99 超阈值持续 M 分钟 → 降级为旁路（记录但不执行）；
内存接近上限 → 拒绝新请求并排空；单插件故障绝不影响其他插件与宿主主流程。

能力对比要点：
  Proxy-Wasm  生态成熟、绑定 Envoy 生命周期，但脱离 Envoy 难独立用
  Extism      多语言 PDK 齐备、开箱即用，抽象层厚、极致性能受限
  自研        完全掌控 ABI 与配额，但 SDK、文档、测试全要自己维护

已在服务网格内 → Proxy-Wasm
SaaS 插件市场 / 快速起步 → Extism
需要精细计费、确定性执行、特殊 ABI → 自研

阶段一（最小可用）：固定 ABI（alloc/dealloc + handle 入口）、只给 log 能力、
内存与 fuel 双限额、无热加载

阶段二（可用）：版本协商 + 能力位图、插件级指标与熔断、双缓冲热加载

阶段三（生产）：完整能力集与白名单、状态快照与迁移、插件市场与签名校验、
多语言 SDK 与兼容性测试矩阵

[ ] ABI 文档化，所有权规则明确且被测试覆盖
[ ] 版本协商与能力位图在 CI 中做兼容矩阵测试
[ ] 每个插件独立 Store，内存与 fuel 双限额
[ ] 所有调用点有超时与错误兜底
[ ] 能力默认拒绝，manifest 声明 + 运行时收窄
[ ] 插件级指标、熔断与降级策略就绪
[ ] 热加载可回滚，旧实例优雅排空
[ ] 插件包签名校验，producers 段记录工具链