wasmeld/README.md

# Wasmeld

Wasmeld 是面向 WebAssembly Component 的服务运行与管理平台。内部服务编译为
Component，在受限 Wasmtime Sandbox 中以常驻 Actor 运行，并通过稳定 WIT 契约
暴露能力。

Runtime 内置版本化 Host Capability Registry。注册 Component 时会直接读取其 WIT
imports，只链接实际请求且版本完全匹配的 Host 能力；未知能力会被拒绝。能力不需要在
`.wasmpkg` 中重复声明，管理面会展示每个服务版本解析出的完整接口标识。

当前 Host 能力：

- `wasmeld:clock/monotonic-clock@0.1.0`：Actor 内单调时钟
- `wasmeld:kv/store@0.1.0`：按服务隔离、跨 Revision 共享的持久化二进制 KV

常驻型 Component 可额外导出 `wasmeld:resident/actor@0.1.0`。Runtime 将定时器、
TCP/UDP/Unix、消息订阅和扩展事件放入同一个有界 Actor mailbox；Component 每次只处理
一个事件并返回 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
crates/wasmeld-runtime   Component Runtime 与 Sandbox
crates/wasmeld-console   管理 API 与持久化
crates/wasmeld-package   wasmeld CLI、组件包与 WIT 依赖管理
components/              示例 Component
console/                 TanStack Start 管理面
wit/                     Wasmeld WIT package 源码
```

## 启动

后端：

```bash
cargo +stable run -p wasmeld-console
```

后端会启动本地管理 API `127.0.0.1:8080` 和公开数据面
`0.0.0.0:8081`。注册 Component 后，通过管理 API 激活一个版本：

```bash
curl -X POST http://127.0.0.1:8080/api/v1/deployments/echo/activate \
  -H 'Content-Type: application/json' \
  -d '{"revision":"0.1.0"}'
```

客户端只访问 Gateway，并以原始二进制请求调用活动版本：

```bash
curl http://127.0.0.1:8081/v1/services/echo/invoke \
  -H 'Content-Type: application/octet-stream' \
  --data-binary 'hello'
```

管理面：

```bash
cd console
npm run dev
```

## 组件开发

Console 启动后，使用开发模式监听组件源码和本地 WIT `replace`：

```bash
cargo run -p wasmeld-package --bin wasmeld -- \
  dev components/echo/Cargo.toml
```

首次构建和每次源码变化都会自动完成 WIT 同步、Debug 编译、打包、注册和 Deployment
切换。默认使用 `echo-dev` 这类独立服务 ID，并根据 Component 内容生成
`0.1.0-dev.h<hash>` Revision，不会覆盖正式服务。新版本构建、校验或启动失败时，上一
版本继续运行；切换成功后旧开发 Revision 会被注销并释放。编译期间的新保存会继续
排队构建，Console 暂时不可用时则复用已构建制品重试部署。

管理面每 5 秒刷新一次，可以直接在调用面板预览新版本。只构建并部署一次可使用
`--once`；其它选项包括 `--id`、`--console`、`--release` 和 `--poll-ms`。管理 API
地址也可通过 `WASMELD_CONSOLE` 设置。默认允许本地 `replace` 更新 `wit.lock`；若开发
期间不允许 WIT 契约发生变化，再添加 `--locked`。

构建组件：

```bash
cargo run -p wasmeld-package --bin wasmeld -- \
  pack components/echo/Cargo.toml --locked
```

KV 示例组件：

```bash
cargo run -p wasmeld-package --bin wasmeld -- \
  pack components/kv-probe/Cargo.toml --locked
```

`kv-probe` 接受 `set:<key>:<value>`、`get:<key>` 和 `delete:<key>`，用于验证 Host KV
能力；它不是公开 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：

```bash
cargo run -p wasmeld-package --bin wasmeld -- \
  wit publish wit/service --registry http://127.0.0.1:8080
```

组件在 `wasmeld.toml` 中声明 Registry 和精确版本依赖，`wasmeld wit fetch` 会递归
解析依赖、生成 `wit/deps`，并将完整解析结果记录在 `wit.lock`。本地开发可使用
`[replace]` 临时覆盖 Registry 来源。

完整命令、开发选项、组件包格式和 WIT 依赖说明见
[`wasmeld-package` CLI 文档](crates/wasmeld-package/README.md)。