Maofeng
ad7d8cdd72
- describe resident Runtime boundaries and sandbox guarantees - specify component archive and host capability contracts - document Console ownership and persistence behavior - explain versioned WIT Registry, lock files, and path replace - provide startup, packaging, publication, and dependency commands
95 lines
2.4 KiB
Markdown
95 lines
2.4 KiB
Markdown
# Wasmeld 组件包
|
||
|
||
**状态：** Implemented
|
||
|
||
**格式版本：** 1
|
||
|
||
`.wasmpkg` 是平台内部发布 WebAssembly Component 的单文件制品。文件使用 ZIP
|
||
容器，扩展名固定为 `.wasmpkg`，并且只能包含两个根目录条目：
|
||
|
||
```text
|
||
echo-0.1.0.wasmpkg
|
||
├── package.toml
|
||
└── component.wasm
|
||
```
|
||
|
||
`package.toml` 示例：
|
||
|
||
```toml
|
||
schema_version = 1
|
||
id = "echo"
|
||
revision = "0.1.0"
|
||
world = "component:echo/echo-component@0.1.0"
|
||
component = "component.wasm"
|
||
sha256 = "..."
|
||
```
|
||
|
||
包中不包含内存、Fuel、超时或 mailbox 等部署策略。这些限制由
|
||
`wasmeld-console` 的 `registration_limits` 注入，组件发布者不能通过上传制品扩大
|
||
Sandbox 权限。
|
||
|
||
## 组件配置
|
||
|
||
组件必须是 `cdylib`，并在 `Cargo.toml` 中声明平台服务 ID：
|
||
|
||
```toml
|
||
[lib]
|
||
crate-type = ["cdylib"]
|
||
|
||
[package.metadata.wasmeld]
|
||
id = "echo"
|
||
world = "component:echo/echo-component@0.1.0"
|
||
```
|
||
|
||
版本直接使用 `[package].version`。`world` 必须是组件选择的完整、带版本 WIT World；
|
||
打包工具会将它写入制品，控制台不需要手工填写。
|
||
|
||
组件的 WIT 依赖由同目录的 `wasmeld.toml` 和 `wit.lock` 管理。`pack` 会在 Cargo
|
||
编译前自动生成 `wit/deps`；CI 应传入 `--locked`，禁止依赖摘要发生漂移。
|
||
|
||
## 打包
|
||
|
||
从项目根目录运行：
|
||
|
||
```bash
|
||
cargo run -p wasmeld-package --bin wasmeld -- \
|
||
pack components/echo/Cargo.toml --locked
|
||
```
|
||
|
||
命令默认使用 Rust `1.90.0` 构建 `wasm32-wasip2` release Component，并输出：
|
||
|
||
```text
|
||
dist/echo-0.1.0.wasmpkg
|
||
```
|
||
|
||
可以覆盖输出路径，或者复用已经构建的 Component：
|
||
|
||
```bash
|
||
cargo run -p wasmeld-package --bin wasmeld -- \
|
||
pack components/echo/Cargo.toml \
|
||
--output dist/echo.wasmpkg \
|
||
--no-build
|
||
```
|
||
|
||
通过 `WASMELD_COMPONENT_TOOLCHAIN` 可以覆盖组件构建工具链。
|
||
|
||
## 注册
|
||
|
||
管理 API 只接收一个 multipart 字段：
|
||
|
||
```bash
|
||
curl -F package=@dist/echo-0.1.0.wasmpkg \
|
||
http://127.0.0.1:8080/api/v1/services
|
||
```
|
||
|
||
Console 在写入制品目录前执行以下校验：
|
||
|
||
- ZIP 恰好包含 `package.toml` 和 `component.wasm`
|
||
- schema、服务 ID、版本和 WIT World 合法
|
||
- 解压后的 Component 未超过平台上限
|
||
- Component 的 SHA-256 与 manifest 一致
|
||
- Wasmtime 能编译 Component，且 imports 符合 Sandbox 白名单
|
||
- 同一服务 ID 和版本尚未注册
|
||
|
||
校验成功后，服务以 `stopped` 状态注册。启动 Actor 仍是独立的管理操作。
|