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

结构

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 源码

启动

后端：

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 console
npm run dev

组件开发

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 会被注销并释放。

管理面每 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 的业务协议。

发布 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 来源。