From ccad05fa5aa4c9c09601c78a6554d8f86321295a Mon Sep 17 00:00:00 2001 From: Maofeng Date: Thu, 30 Jul 2026 09:22:10 +0800 Subject: [PATCH] docs(console): document Host-page and embedded build workflows - explain the persistent Host and disposable iframe ownership model - define SDK compatibility and PWA cache boundaries - document independent debug servers and release embedding - record Node, npm, NPM, and WASMELD_BUILD_WEB requirements - update repository structure and startup commands --- README.md | 19 +++++- crates/wasmeld-console/README.md | 20 ++++++ crates/wasmeld-console/web/README.md | 94 ++++++++++++++++++++++++++++ 3 files changed, 130 insertions(+), 3 deletions(-) create mode 100644 crates/wasmeld-console/web/README.md diff --git a/README.md b/README.md index 13d28f8..e52386e 100644 --- a/README.md +++ b/README.md @@ -34,9 +34,9 @@ Host driver <- validated operation <- raw effect <- ```text crates/wasmeld-runtime Component Runtime 与 Sandbox crates/wasmeld-console 管理 API 与持久化 + └── web/ Solid + Tailwind v4 管理面 crates/wasmeld-package wasmeld CLI、组件包与 WIT 依赖管理 components/ 示例 Component -console/ TanStack Start 管理面 wit/ Wasmeld WIT package 源码 ``` @@ -65,13 +65,26 @@ curl http://127.0.0.1:8081/v1/services/echo/invoke \ --data-binary 'hello' ``` -管理面： +管理面开发服务器： ```bash -cd console +cd crates/wasmeld-console/web +npm ci npm run dev ``` +打开 `http://127.0.0.1:3000`。开发期间 Rust 和 Web 独立增量构建；Release 构建会自动 +构建 Web 并嵌入 `wasmeld-console`： + +```bash +cargo +stable build --release -p wasmeld-console +./target/release/wasmeld-console +``` + +此时管理面直接由 `http://127.0.0.1:8080` 提供，不需要部署单独的静态站点。Host + +iframe 页面生命周期、PWA 缓存和前端目录约定见 +[`Console Web 文档`](crates/wasmeld-console/web/README.md)。 + ## 组件开发 Console 启动后，使用开发模式监听组件源码和本地 WIT `replace`： diff --git a/crates/wasmeld-console/README.md b/crates/wasmeld-console/README.md index a0a9020..713a4d9 100644 --- a/crates/wasmeld-console/README.md +++ b/crates/wasmeld-console/README.md @@ -10,6 +10,7 @@ - 通过独立 Gateway 转发原始二进制调用 - 为导入 `wasmeld:kv/store@0.1.0` 的 Component 提供持久化 KV - 暴露调用计数、状态和最近事件 +- 在 Release 可执行文件中嵌入 Solid + Tailwind v4 管理面 Wasm 制品保存在本地文件系统。服务 manifest、调用计数和最近 256 条事件通过 [Toasty](https://github.com/tokio-rs/toasty) 写入本地 libSQL 数据库，默认路径是 @@ -38,6 +39,25 @@ Console 或 Runtime 重启后可由 Wasmtime 直接复用；缓存不包含 Acto cargo +stable run -p wasmeld-console ``` +Debug 构建只启动 API，不构建或提供 Web 静态文件。前端开发服务器需要单独启动： + +```bash +cd crates/wasmeld-console/web +npm ci +npm run dev +``` + +Release 构建会自动使用 `package-lock.json` 构建并嵌入管理面： + +```bash +cargo +stable build --release -p wasmeld-console +./target/release/wasmeld-console +``` + +发布构建要求 Node.js 22.13+ 和 npm。可用 `NPM` 指定 npm 可执行文件；设置 +`WASMELD_BUILD_WEB=1` 可以在非 Release Cargo 构建中验证嵌入流程。前端结构和 PWA +边界见 [`web/README.md`](web/README.md)。 + 进程默认启动两个独立 Listener： - 管理 API：`127.0.0.1:8080` diff --git a/crates/wasmeld-console/web/README.md b/crates/wasmeld-console/web/README.md new file mode 100644 index 0000000..d5e60a5 --- /dev/null +++ b/crates/wasmeld-console/web/README.md @@ -0,0 +1,94 @@ +# Wasmeld Console Web + +管理面使用 Solid 和 Tailwind CSS v4。它不是传统单文档 SPA，而是由一个常驻 Host +文档和一个可替换 Page iframe 组成： + +```text +index.html / src/host +├── 导航、搜索、弹窗、通知 +├── 管理 API 轮询和共享状态 +└── page.html?view=&instance= + └── src/pages/ +``` + +Host 始终只保留一个 iframe。切换一级页面时，Host 先发送 `dispose`，再销毁 iframe +并创建新的文档。页面所属的 Solid reactive owner、事件监听器、第三方 UI 库和页面局部 +缓存会随文档一起释放，避免长期导航后把各页面资源都留在同一个 JavaScript realm 中。 + +iframe 是资源生命周期边界，不是安全边界。Host 和 Page 都是 Wasmeld 自己构建并同源 +发布的可信代码；Wasm 服务的安全边界仍然在后端 Wasmtime Sandbox 和 Host Capability +Registry 中。 + +## 目录 + +```text +src/host/ 常驻 Host Shell 和 Host-owned dialogs +src/components/ui/ 跨页面复用的无业务 UI +src/lib/ API client、领域模型和纯函数 +src/primitives/ Solid reactive primitives；Solid 不使用 React Hooks 约定 +src/pages/ 每个 iframe 页面一个目录和独立懒加载 chunk +src/sdk/ Host/Page postMessage 协议与两侧 client +src/styles/ Tailwind v4 theme 和共享组件样式 +``` + +`src/sdk/protocol.ts` 中的 `SDK_VERSION` 是文档间协议版本。新增可选消息可以保持原版本； +删除字段、改变字段语义或产生不兼容状态时必须升级版本，并让两侧同时发布。消息接收端 +同时检查 origin、source、channel 和 version，不接收任意窗口的控制命令。 + +## 开发 + +先在仓库根目录启动 Rust 后端： + +```bash +cargo +stable run -p wasmeld-console +``` + +再启动 Web 开发服务器： + +```bash +cd crates/wasmeld-console/web +npm ci +npm run dev +``` + +打开 `http://127.0.0.1:3000`。Vite 开发环境默认连接 +`http://127.0.0.1:8080`；设置页可以覆盖该地址。Debug Cargo 构建不会调用 npm， +因此 Rust 与 Web 的增量开发互不阻塞。 + +常用检查： + +```bash +npm run format:check +npm run lint +npm test +npm audit --audit-level=high +``` + +## 发布与嵌入 + +Release 构建由 `../build.rs` 自动执行： + +```bash +cargo +stable build --release -p wasmeld-console +``` + +构建脚本使用 `npm ci` 严格读取 `package-lock.json`，将 Vite 输出写入 Cargo +`OUT_DIR`，再由 Rust `include_dir!` 嵌入可执行文件。发布机器必须提供 Node.js 22.13+ +和 npm。可以用 `NPM=/absolute/path/to/npm` 指定 npm；只有需要调试嵌入行为时，才在 +非 Release 构建中设置 `WASMELD_BUILD_WEB=1`。 + +Release 管理 Listener 同时服务 `/`、`/page.html`、静态资源、PWA manifest 和 +`/sw.js`。资源路径必须精确存在，不做 SPA fallback。带内容哈希的 `assets/` 使用长期 +immutable 缓存，其它入口使用 `no-cache`。 + +## PWA 边界 + +一个 Host-owned service worker 管理整个应用： + +- 构建时预缓存 Host、Page 和带哈希静态资源。 +- 文档请求使用 network-first，离线时分别回退到 `index.html` 或 `page.html`。 +- `/api/*` 和 `/healthz` 永远走网络，不缓存运行状态或管理操作。 +- 新 worker 激活时删除旧的 `wasmeld-*` 缓存。 + +PWA 只提供安装和静态壳离线能力。没有后端连接时页面会显示离线状态，不会用旧 API +响应伪造 Runtime 状态。