Maofeng
c399781369
- describe resident Runtime boundaries and sandbox guarantees\n- specify component archive and host capability contracts\n- document Console ownership and persistence behavior\n- explain versioned WIT Registry, lock files, and path replace\n- provide startup, packaging, publication, and dependency commands
102 lines
2.9 KiB
Markdown
102 lines
2.9 KiB
Markdown
# Wasmeld Host Capabilities
|
||
|
||
**状态：** Implemented
|
||
|
||
**首个能力：** `wasmeld:clock/monotonic-clock@0.1.0`
|
||
|
||
## 边界
|
||
|
||
所有组件实现稳定的 `service-component` 导出契约。宿主能力不加入这个基础 World，
|
||
而是定义成独立 WIT interface，由组件专属 World 按需 import。
|
||
|
||
```text
|
||
wit/
|
||
├── service/package.wit # wasmeld:service@0.1.0
|
||
└── clock/package.wit # wasmeld:clock@0.1.0
|
||
```
|
||
|
||
例如普通 Echo 不导入宿主能力：
|
||
|
||
```wit
|
||
package component:echo@0.1.0;
|
||
|
||
world echo-component {
|
||
include wasmeld:service/service-component@0.1.0;
|
||
}
|
||
```
|
||
|
||
Clock Probe 显式申请单调时钟：
|
||
|
||
```wit
|
||
package component:clock-probe@0.1.0;
|
||
|
||
world clock-probe-component {
|
||
include wasmeld:service/service-component@0.1.0;
|
||
import wasmeld:clock/monotonic-clock@0.1.0;
|
||
}
|
||
```
|
||
|
||
组件通过自己的 World 生成 binding：
|
||
|
||
```rust
|
||
wit_bindgen::generate!({
|
||
path: "wit",
|
||
world: "clock-probe-component",
|
||
generate_all,
|
||
});
|
||
```
|
||
|
||
组件根目录中的 `wit/deps` 由 `wasmeld wit fetch` 根据 `wasmeld.toml` 和
|
||
`wit.lock` 生成。这几行只是编译期 binding 入口，不是网络协议。组件最终只包含
|
||
所选 World 的 imports 和 exports。
|
||
|
||
## Runtime
|
||
|
||
Runtime 注册 Component 时读取真实 imports，并映射为内部 `HostCapability`。未知
|
||
import 会在注册阶段拒绝。Actor 创建 Linker 时，只为该 Component 实际导入的能力
|
||
注册实现。
|
||
|
||
```text
|
||
Component imports
|
||
|
|
||
v
|
||
validate_component_imports
|
||
|
|
||
v
|
||
Vec<HostCapability>
|
||
|
|
||
v
|
||
Actor Linker
|
||
```
|
||
|
||
当前 `monotonic-clock.now` 返回 Actor 创建后经过的纳秒数。它不提供系统时间、网络、
|
||
文件或其他宿主访问。
|
||
|
||
Rust `std::time::Instant` 会引入 `wasi:clocks/monotonic-clock`，该 WASI 接口仍不在
|
||
Sandbox 白名单内。组件必须使用平台明确提供的 `wasmeld:clock/monotonic-clock`，
|
||
不能通过标准库绕过能力控制。
|
||
|
||
## 新增能力
|
||
|
||
新增能力时必须同时完成：
|
||
|
||
1. 在独立 `.wit` 文件中定义小型 interface。
|
||
2. 只在需要它的组件 World 中 import。
|
||
3. 在 Runtime 中实现生成的 Host trait。
|
||
4. 将完全限定的 import 名称映射到新的 `HostCapability`。
|
||
5. 在 Actor Linker 中注册实现。
|
||
6. 增加允许和拒绝两类 Sandbox 测试。
|
||
|
||
不要把可选能力加入 `service-component`。不要仅依据包 manifest 授权，Runtime 必须
|
||
以编译后 Component 的真实 imports 为准。
|
||
|
||
## 版本策略
|
||
|
||
- 已发布的 WIT 版本不可原地修改。
|
||
- 破坏性变更发布新的 major version。
|
||
- Runtime 在迁移期可以同时实现两个版本。
|
||
- 不相关能力独立演进，不能迫使所有组件重新编译。
|
||
|
||
`service` 和 `clock` 已经是两个独立版本的 WIT package。源码只维护当前版本，历史
|
||
版本由 Git tag 与不可变 Registry 制品保留；组件通过包名、版本和锁文件选择依赖。
|