From 71654a8bcf620c4a08cc427549c4668bb4c6d237 Mon Sep 17 00:00:00 2001 From: Maofeng Date: Wed, 29 Jul 2026 19:37:19 +0800 Subject: [PATCH] docs: document persistent Host KV Describe the versioned KV capability, service-level namespace, persistence behavior, limits, and kv-probe packaging workflow. Record the v0.1 exclusions for TTL, enumeration, transactions, and compare-and-swap. --- README.md | 15 +++++++++++++++ crates/wasmeld-console/README.md | 9 +++++++++ 2 files changed, 24 insertions(+) diff --git a/README.md b/README.md index 14723a9..97bf038 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,11 @@ Runtime 内置版本化 Host Capability Registry。注册 Component 时会直接 imports，只链接实际请求且版本完全匹配的 Host 能力；未知能力会被拒绝。能力不需要在 `.wasmpkg` 中重复声明，管理面会展示每个服务版本解析出的完整接口标识。 +当前 Host 能力： + +- `wasmeld:clock/monotonic-clock@0.1.0`：Actor 内单调时钟 +- `wasmeld:kv/store@0.1.0`：按服务隔离、跨 Revision 共享的持久化二进制 KV + ## 结构 ```text @@ -58,6 +63,16 @@ 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::`、`get:` 和 `delete:`，用于验证 Host KV +能力；它不是公开 Gateway 的业务协议。 + 发布 WIT Package： ```bash diff --git a/crates/wasmeld-console/README.md b/crates/wasmeld-console/README.md index 14a03f6..8191e7a 100644 --- a/crates/wasmeld-console/README.md +++ b/crates/wasmeld-console/README.md @@ -8,11 +8,14 @@ - 启动、停止和重启常驻 Actor - 管理服务 ID 到活动版本的 Deployment - 通过独立 Gateway 转发原始二进制调用 +- 为导入 `wasmeld:kv/store@0.1.0` 的 Component 提供持久化 KV - 暴露调用计数、状态和最近事件 Wasm 制品保存在本地文件系统。服务 manifest、调用计数和最近 256 条事件通过 [Toasty](https://github.com/tokio-rs/toasty) 写入本地 libSQL 数据库，默认路径是 `var/wasmeld/console.db`。Deployment 也存储在同一数据库中。 +Host KV 使用 `(service_id, key)` 复合主键存储在该数据库中：同一服务的 Revision +共享数据，不同服务互相隔离，Runtime 或 Console 重启不会清空 KV。 `wasmeld-console` 启动时会在同一进程内创建 `wasmeld-runtime`、加载 Wasmtime Engine， 并重新注册已保存的 Component。Runtime 停止后 Console HTTP 和数据库仍然在线； @@ -95,6 +98,12 @@ curl http://127.0.0.1:8081/v1/services/echo/invoke \ `wasmeld:clock/monotonic-clock@0.1.0`。Console 不接受手工能力声明，Runtime 只会链接 注册表中存在且版本完全匹配的接口。 +## Host KV + +`wasmeld:kv/store@0.1.0` 提供 `get`、`set` 和 `delete`。Key 必须是非空 UTF-8， +最大 256 B；Value 最大 64 KiB。数据库命令通过有界专用工作线程执行，Host 等待时间 +不会超过服务的 `deadline_ms`。v0.1.0 不提供 TTL、遍历、事务或 CAS。 + 组件包的构建与格式说明见 [`docs/design/wasmeld-component-package.md`](../../docs/design/wasmeld-component-package.md)。 WIT 依赖、Registry 和本地 replace 说明见