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，不能直接取得文件描述符或绕过 端点策略。

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。

结构

crates/wasmeld-runtime   Component Runtime 与 Sandbox
crates/wasmeld-console   管理 API 与持久化
  └── web/               Solid + Tailwind v4 管理面
crates/wasmeld-package   wasmeld CLI、组件包与 WIT 依赖管理
components/              示例 Component
wit/                     Wasmeld WIT package 源码

启动

后端：

cargo +stable run -p wasmeld-console

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

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，并以原始二进制请求调用活动版本：

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

管理面开发服务器：

cd crates/wasmeld-console/web
npm ci
npm run dev

打开 http://127.0.0.1:3000。开发期间 Rust 和 Web 独立增量构建；Release 构建会自动 构建 Web 并嵌入 wasmeld-console：

cargo +stable build --release -p wasmeld-console
./target/release/wasmeld-console

此时管理面直接由 http://127.0.0.1:8080 提供，不需要部署单独的静态站点。Host + iframe 页面生命周期、PWA 缓存和前端目录约定见 Console Web 文档。

组件开发

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

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。

构建组件：

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

KV 示例组件：

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 的业务协议。

常驻事件示例组件：

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：

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 文档。