wasmeld/docs/design/wasmeld-runtime-mvp.md

Wasmeld Runtime 架构

状态： Draft

日期： 2026-07-22

范围： 仅实现 Wasmeld Runtime

1. 范围

本阶段只解决一件事：在一个 Rust 宿主进程中，安全地加载并常驻运行内部 Rust 编译的 WebAssembly Component。

需要具备：

• Rust Component 的构建、注册、加载、调用、停止与重载。
• 同一实例跨多次调用保留内存。
• 同一实例不发生并发重入。
• Wasmtime 资源限制与最小 sandbox。
• 统一且不含业务语义的 Component 调用契约。

当前不做 HTTP、客户、鉴权、数据库、网络、消息队列、业务状态持久化、分布式部署或发布治理。

2. 核心结构

Rust Component source
  |
  | cargo build --target wasm32-wasip2 --release
  v
component.wasm + manifest.toml
  |
  v
Component Registry
  |
  v
Wasmeld Runtime (one Rust process)
  |
  +-- Engine
  +-- compiled Component cache
  +-- Service Manager
        |
        +-- ServiceActor
              +-- bounded mailbox
              +-- Store<HostState>
              +-- restricted Linker
              +-- Component Instance

Runtime 是一个 Rust 库或单独进程，不提供网络协议。对内只暴露：

register(manifest, artifact) -> ServiceKey
start(service_key, init_config) -> ActorHandle
invoke(actor_handle, bytes) -> bytes or RuntimeError
stop(actor_handle)
reload(next_manifest, next_artifact, init_config) -> ActorHandle

调用方未来可以是 HTTP Adapter、CLI 或测试程序；Runtime 本身不关心调用来源。

3. 核心对象

对象	责任
Component Artifact	一个不可变的 component.wasm 与最小 manifest。
Service Revision	Artifact 的 id + revision。
Engine	进程级共享的 Wasmtime 编译和执行引擎。
Component Cache	缓存编译后的 Component，不保存实例内存。
Service Manager	管理 Service Revision 与 ActorHandle 的映射。
ServiceActor	独占 Store、Instance、HostState 与有界邮箱。
ActorHandle	向 Actor 发送调用，不能接触 Store 或 Instance。
HostState	Store 专有的运行时状态，不包含业务数据。

V1 采用：

one Service Revision -> one ServiceActor -> one Store + one Instance

多个 Actor、分片和水平扩展属于后续能力。

4. 制品与注册

内部服务构建为 Component：

cargo build --target wasm32-wasip2 --release

最小制品：

component.wasm
manifest.toml

manifest 只包含：

id
revision
component path
expected WIT world
memory limit
fuel per call
deadline
mailbox capacity
input/output byte limits

注册规则：

• ServiceKey 由 id 与 revision 构成，不允许覆盖。
• Runtime 校验 manifest 的 WIT world 格式与资源策略；实例化时由 typed binding 校验基础导出契约。
• V1 只接受本地受信任制品；Registry、签名、SBOM 与远程下载后置。
• 已编译 Component 可缓存，但 Actor 的内存只能存在于 Store + Instance 中。

5. 最小 WIT 契约

V1 不定义任何业务协议。输入输出都是有长度上限的 opaque bytes。

package wasmeld:service@0.1.0;

world service-component {
  variant service-error {
    init-failed(string),
    call-failed(string),
  }

  export init: func(config: list<u8>) -> result<_, service-error>;
  export invoke: func(input: list<u8>) -> result<list<u8>, service-error>;
}

规则：

• init 仅在一个新 Instance 上调用一次。
• invoke 是唯一的普通调用入口。
• Component 返回 service-error 后，Actor 可继续使用。
• trap、资源超限或中断后，整个 Store + Instance 必须丢弃，不能继续调用。
• 基础 world 不定义宿主能力 import。组件专属 World 通过独立 interface 按需 import 平台能力，详见 wasmeld-capabilities.md。普通 Rust wasm32-wasip2 产物会隐式导入标准 WASI P2 接口，因此 Runtime 提供受限的 WASI 兼容层，而不是把它们暴露为业务 ABI。
• Runtime 在注册时只允许以下兼容 import：wasi:cli/{environment,exit,stdin,stdout,stderr}、 wasi:clocks/wall-clock、wasi:filesystem/{preopens,types}、wasi:io/{error,streams}。 wasi:io/poll、WASI monotonic clock、随机数、socket、HTTP 和未知平台 import 都会被拒绝。
• V1 提供独立的 wasmeld:clock/monotonic-clock@0.1.0 平台能力。只有显式导入 该 interface 的组件会获得对应 Linker 实现。
• health、shutdown、日志、文件、网络和标准 I/O 都不属于基础 ABI。wall clock 仅作为 Rust/WASI 兼容层的一部分存在，不用于传递业务能力；随机数不在 V1 白名单内。

6. 常驻 Actor

Caller
  -> ActorHandle
     -> bounded Sender<Invocation>
        -> dedicated Wasm worker
           -> Store + Instance + HostState

一个 Actor 的 worker 独占 Store。不能使用 Arc<Mutex> 共享 Store，也不能让同一 Instance 重入。

处理流程：

1. ActorHandle 提交 Invocation。
2. Actor 从 FIFO mailbox 取出一条消息。
3. Actor 在同一 Store + Instance 上调用 service.invoke。
4. Actor 通过 oneshot response 返回结果。
5. 下一条消息才可进入该 Instance。

这保证 Rust heap、Wasm linear memory 和全局变量在多次调用间常驻，同时保证状态修改串行。

实现约束：

• Wasm 调用放在专用 worker 线程或线程池，不能阻塞 Tokio 的通用 worker。
• V1 不使用 Wasmtime async 或 Wasm threads。为兼容 Rust 的 wasm32-wasip2 组件， 链接同步、受限的 WASI P2 白名单实现。
• mailbox 满时立即返回 RuntimeOverloaded。
• 调用 deadline 到期且尚未进入 Instance 时直接取消。
• Component 不得在 invoke 之外启动后台循环。

Actor 内存是易失的。Runtime 重启、Actor fault、stop 或 reload 后，下一实例重新执行 init，不恢复旧内存。

7. 生命周期

Registered -> Starting -> Ready -> Draining -> Stopped
                              |
                              +-> Failed

• register：保存 Artifact 与 manifest。
• start：取得已编译 Component，创建 Store、受限 WASI Linker 与 Instance，然后调用 init。
• ready：接收 invoke。
• draining：拒绝新调用，等待当前调用完成。
• stopped：释放 Store 和 Instance。
• failed：trap、fuel 耗尽、deadline 或 Runtime 错误后立即释放 Store 和 Instance。

故障后：

fault
  -> mark Actor failed
  -> reject queued calls
  -> drop Store + Instance
  -> optionally create a new Actor

自动重建可配置，但 V1 不应隐藏故障或声称保留了旧内存。

reload 的最小流程：

1. 注册新的 Service Revision。
2. start 新 Actor，确保 init 成功。
3. 调用方切换到新的 ActorHandle。
4. 调用方显式 stop 旧 Actor 并释放。

V1 不做请求级流量切换或状态迁移。

8. Sandbox 与资源限制

V1 Linker 注册受限 WASI P2 兼容实现，并按 Component 的真实 imports 注册已批准的 平台能力。每个 Actor 都有独立 WasiCtx，并且显式禁止 TCP、UDP、DNS 和所有 socket 地址。默认配置还保证无环境变量、 参数、工作目录或预打开目录，stdin 关闭，stdout/stderr 丢弃。因此 Component 默认没有：

• 文件系统、环境变量、命令行参数或标准 I/O 继承。
• 网络、DNS、socket 或原始系统调用。
• 数据库、密钥、配置文件、宿主目录或宿主进程能力。

每个 Actor 必须显式设置：

限制	目的
linear memory	阻止无限内存增长。
tables / instances / memories	限制 Wasm 对象数量。
fuel per invocation	限制确定性的计算工作量。
epoch deadline	限制 wall-clock 执行时间。
input/output bytes	限制单次数据传输。
mailbox capacity	实现背压，避免无限排队。

fuel 和 epoch 只约束 Wasm 执行。未来一旦加入 Host I/O，必须单独定义 timeout、取消和连接资源策略。

Runtime 的 epoch ticker 上限为 10 ms，且服务 deadline 不能小于该 tick，以避免配置使 wall-clock deadline 失效。ActorHandle 持有 ticker 的生命周期引用，因此 Runtime 对象释放后， 仍被调用方持有的 ActorHandle 不会失去 epoch 中断能力。

Wasm Store 隔离 Component 内存和可见 import，但不是完整 OS 隔离。V1 以第一方代码为前提；进程、Pod、gVisor 或 Kata 隔离在实际需要时再加入。

9. 最小代码结构

wit/
  service/
    package.wit
  clock/
    package.wit

crates/
  wasmeld-runtime/
    bindings.rs
    error.rs
    manifest.rs
    runtime.rs
    lib.rs

components/
  echo/
  counter/
  fault/
  spin/
  clock-probe/

tests/
  runtime_components.rs

10. 验收测试

测试 Component：

• echo：原样返回输入，验证基础加载与调用。
• counter：init 创建计数状态，每次 invoke 递增，验证内存常驻。
• fault：显式 trap，验证旧 Store 会被丢弃且 Actor 可重建。
• spin：不可被优化掉的 CPU 循环，验证 fuel 与 epoch 中断。
• clock-probe：显式导入平台 monotonic-clock，验证能力按需 Link。
• wasi-clock-probe：通过 Rust 标准库导入 WASI monotonic clock，验证注册时拒绝越权。

必须验证：

1. Component 只有在导出匹配预期 WIT world、且其 import 可由受限 WASI Linker 满足时才可启动。
2. 同一 Actor 调用 counter 两次能观察到递增状态。
3. stop、fault 或 Runtime 重启后，counter 从 init 重新开始。
4. 多个并发 invoke 会严格经同一 Actor 串行执行。
5. 无限循环会被 fuel 或 epoch deadline 终止。
6. trap 后旧 Store 被丢弃，重建 Actor 后可再次调用。
7. mailbox 满时立即出现 overload，不无限等待。
8. memory.grow 超过限制会导致 Actor fault。
9. reload 能启动新 revision 的 Actor；旧 Actor 由调用方显式 stop。

11. 后续扩展触发条件

明确需求	再引入的能力
需要网络入口	HTTP/gRPC Adapter 与 API Gateway。
需要调用宿主资源	独立 Host Capability 与 WIT import。
需要跨重启保留状态	外部状态、checkpoint 与恢复协议。
需要多个实例	Actor 池、分片和放置策略。
需要生产发布治理	制品签名、Registry、灰度与回滚。
需要执行非第一方代码	额外进程或 OS sandbox。

12. 参考资料

• WebAssembly Component Model
• Rust Components with wasm32-wasip2
• Wasmtime
• Wasmtime interruption with fuel and epochs