docs: describe resident component architecture

Document the Host-owned event/effect flow, revision-scoped resource supervision, endpoint policy, versioned resident WIT dependency, and the resident-probe packaging command.
This commit is contained in:
Maofeng
2026-07-30 07:40:11 +08:00
parent 572fed47b4
commit a5718da1da
2 changed files with 32 additions and 0 deletions
+26
View File
@@ -13,6 +13,22 @@ imports,只链接实际请求且版本完全匹配的 Host 能力;未知能
- `wasmeld:clock/monotonic-clock@0.1.0`Actor 内单调时钟 - `wasmeld:clock/monotonic-clock@0.1.0`Actor 内单调时钟
- `wasmeld:kv/store@0.1.0`:按服务隔离、跨 Revision 共享的持久化二进制 KV - `wasmeld:kv/store@0.1.0`:按服务隔离、跨 Revision 共享的持久化二进制 KV
常驻型 Component 可额外导出 `wasmeld:resident/actor@0.1.0`。Runtime 将定时器、
TCP/UDP/Unix、消息订阅和扩展事件放入同一个有界 Actor mailboxComponent 每次只处理
一个事件并返回 effect。系统 socket、timer task 和 broker consumer 始终由 Host 持有,
Component 只能引用当前 Revision 内不复用的资源 ID,不能直接取得文件描述符或绕过
端点策略。
```text
Host driver -> ResidentSession -> Actor mailbox -> Wasm Component
Host driver <- validated operation <- raw effect <-
```
`ResidentSession` 负责 deny-by-default 的网络策略、资源归属、数量限制、流的暂停/半关闭/
关闭状态以及 effect 批量原子校验。TCP、UDP、Unix listener 等异步驱动运行在 Actor
线程外;协议级驱动以及文件监听、串口、系统信号等其它来源通过独立版本的 WIT 能力演进,
不需要扩大基础 service world。
## 结构 ## 结构
```text ```text
@@ -93,6 +109,16 @@ cargo run -p wasmeld-package --bin wasmeld -- \
`kv-probe` 接受 `set:<key>:<value>``get:<key>``delete:<key>`,用于验证 Host KV `kv-probe` 接受 `set:<key>:<value>``get:<key>``delete:<key>`,用于验证 Host KV
能力;它不是公开 Gateway 的业务协议。 能力;它不是公开 Gateway 的业务协议。
常驻事件示例组件:
```bash
cargo run -p wasmeld-package --bin wasmeld -- \
pack components/resident-probe/Cargo.toml --locked
```
该组件同时实现基础 service world 与 resident actor export,用于验证 stream、datagram、
timer、message 和扩展 source 的事件/effect 往返。
发布 WIT Package 发布 WIT Package
```bash ```bash
+6
View File
@@ -156,6 +156,7 @@ url = "http://127.0.0.1:8080"
[dependencies] [dependencies]
"wasmeld:service" = "0.1.0" "wasmeld:service" = "0.1.0"
"wasmeld:kv" = "0.1.0" "wasmeld:kv" = "0.1.0"
"wasmeld:resident" = "0.1.0"
[replace."wasmeld:service"] [replace."wasmeld:service"]
path = "../../wit/service" path = "../../wit/service"
@@ -164,6 +165,11 @@ path = "../../wit/service"
依赖解析结果写入 `wit.lock`,源码开发时应提交该文件。解析出的 `wit/deps/` 是生成目录, 依赖解析结果写入 `wit.lock`,源码开发时应提交该文件。解析出的 `wit/deps/` 是生成目录,
不应提交。 不应提交。
普通请求型 Component 只需要 `wasmeld:service`。需要接收 Host 定时器、网络流、UDP、
消息订阅或扩展 source 事件时,再依赖并导出 `wasmeld:resident/actor@0.1.0`;例如
`components/resident-probe``resident` 是独立版本化 package,不会把所有 Host 能力
合并到基础 service world。
同步依赖: 同步依赖:
```bash ```bash