docs: explain host capability discovery

- document exact-version import resolution and deny-by-default behavior
- clarify that Component imports remain the capability source of truth
- describe structured capability metadata returned by the Console API
This commit is contained in:
Maofeng
2026-07-29 19:13:51 +08:00
parent bdbf868f75
commit 51b452ecc5
2 changed files with 9 additions and 1 deletions
+4
View File
@@ -4,6 +4,10 @@ Wasmeld 是面向 WebAssembly Component 的服务运行与管理平台。内部
Component,在受限 Wasmtime Sandbox 中以常驻 Actor 运行,并通过稳定 WIT 契约 Component,在受限 Wasmtime Sandbox 中以常驻 Actor 运行,并通过稳定 WIT 契约
暴露能力。 暴露能力。
Runtime 内置版本化 Host Capability Registry。注册 Component 时会直接读取其 WIT
imports,只链接实际请求且版本完全匹配的 Host 能力;未知能力会被拒绝。能力不需要在
`.wasmpkg` 中重复声明,管理面会展示每个服务版本解析出的完整接口标识。
## 结构 ## 结构
```text ```text
+5 -1
View File
@@ -55,7 +55,7 @@ WIT Registry 路由。
| `POST` | `/api/v1/runtime/start` | 启动 Runtime 并重新注册受管 Component | | `POST` | `/api/v1/runtime/start` | 启动 Runtime 并重新注册受管 Component |
| `POST` | `/api/v1/runtime/stop` | 停止 Runtime 并释放所有 Actor | | `POST` | `/api/v1/runtime/stop` | 停止 Runtime 并释放所有 Actor |
| `POST` | `/api/v1/runtime/restart` | 重建 Runtime,并重新创建活动 Deployment 的 Actor | | `POST` | `/api/v1/runtime/restart` | 重建 Runtime,并重新创建活动 Deployment 的 Actor |
| `GET` | `/api/v1/services` | 服务版本列表 | | `GET` | `/api/v1/services` | 服务版本及精确 Host Capability 列表 |
| `POST` | `/api/v1/services` | multipart 上传单个 `package` 字段(`.wasmpkg` | | `POST` | `/api/v1/services` | multipart 上传单个 `package` 字段(`.wasmpkg` |
| `POST` | `/api/v1/services/{id}/{revision}/start` | 启动 Actor | | `POST` | `/api/v1/services/{id}/{revision}/start` | 启动 Actor |
| `POST` | `/api/v1/services/{id}/{revision}/stop` | 停止 Actor | | `POST` | `/api/v1/services/{id}/{revision}/stop` | 停止 Actor |
@@ -91,6 +91,10 @@ curl http://127.0.0.1:8081/v1/services/echo/invoke \
成功响应通过 `X-Wasmeld-Revision` 返回实际路由的版本。Gateway 错误统一返回 JSON 成功响应通过 `X-Wasmeld-Revision` 返回实际路由的版本。Gateway 错误统一返回 JSON
未部署为 `404`Actor 不可用为 `503`,过载为 `429`,执行超时为 `504` 未部署为 `404`Actor 不可用为 `503`,过载为 `429`,执行超时为 `504`
服务响应的 `capabilities` 来自 Component 二进制中的 WIT imports,例如
`wasmeld:clock/monotonic-clock@0.1.0`。Console 不接受手工能力声明,Runtime 只会链接
注册表中存在且版本完全匹配的接口。
组件包的构建与格式说明见 组件包的构建与格式说明见
[`docs/design/wasmeld-component-package.md`](../../docs/design/wasmeld-component-package.md)。 [`docs/design/wasmeld-component-package.md`](../../docs/design/wasmeld-component-package.md)。
WIT 依赖、Registry 和本地 replace 说明见 WIT 依赖、Registry 和本地 replace 说明见