Skip to content

refactor(desktop): generate Rust models from OpenAPI #2113

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlexStocks merged 8 commits into from
Oct 21, 2026
+2,958 −327
Merged

refactor(desktop): generate Rust models from OpenAPI #2113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7c3177d
refactor(desktop): generate Rust models from OpenAPI
CX33071 Oct 20, 2026
991b955
fix(desktop): support Windows OpenAPI generation
CX33071 Oct 20, 2026
43c6120
fix(desktop): support Windows OpenAPI generation
CX33071 Oct 20, 2026
d46395e
fix(desktop): update generated IPC types
CX33071 Oct 20, 2026
32ced08
fix(desktop): export generated IPC model declarations
CX33071 Oct 20, 2026
08b78d4
fix(desktop): accept nullable pagination cursor
CX33071 Oct 20, 2026
6f5d507
docs(desktop):document Java generation prerequisites
CX33071 Oct 21, 2026
e7ce9f3
Merge upstream master into desktop generator branch
CX33071 Oct 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions desktop/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@ Repeated launches activate the existing window for this channel. Profile storage

## Build on Windows

Use Windows 11 x64, Visual Studio C++ Build Tools with a Windows SDK, Node **24.14.1**, pnpm **11.13.1**, Rust **1.95.0 MSVC**, and WebView2. `desktop/.mise.toml`, `rust-toolchain.toml`, `pnpm-lock.yaml` and `src-tauri/Cargo.lock` pin the tools and dependencies independently of Python and the website.
Use Windows 11 x64, Visual Studio C++ Build Tools with a Windows SDK, Node **24.14.1**, pnpm **11.13.1**, Rust **1.95.0 MSVC**, **JDK 11 or newer with `java` available on `PATH`**, and WebView2. `desktop/.mise.toml`, `rust-toolchain.toml`, `pnpm-lock.yaml` and `src-tauri/Cargo.lock` pin the tools and dependencies independently of Python and the website.

The OpenAPI Generator used by `generate` and `generate:check` runs on Java. On the first run, `openapi-generator-cli` may download the pinned generator JAR from Maven Central, so the first generation or drift check requires network access. Subsequent runs can reuse the downloaded JAR.

Some machines default to Rust's GNU host. In PowerShell, explicitly select the pinned MSVC host for this process:

Expand Down Expand Up @@ -65,7 +67,7 @@ A successful save that returns no memory record is reported as an operation succ

## Contracts and resources

`pnpm --dir desktop generate` derives TypeScript schemas and the reviewed ten-operation manifest from `openapi/powercontext.yaml`; `generate:check` detects drift, including a normalized contract SHA-256. Typed Rust adapters consume that generated manifest and generated wire schemas. No public route is independently handwritten in the application. The manifest is not an IPC permission grant.
`pnpm --dir desktop generate` derives TypeScript schemas, the reviewed ten-operation manifest, and the Rust wire models from `openapi/powercontext.yaml`; `generate:check` detects drift, including a normalized contract SHA-256. The OpenAPI Generator CLI version is pinned in `desktop/openapitools.json`, and the limited Rust customization lives in `desktop/scripts/openapi-generator/rust/`. Generated `src-tauri/src/transport/wire.rs` must not be edited by hand: after changing the contract or generator template, run `pnpm --dir desktop generate`, then run `pnpm --dir desktop generate:check` in CI. Typed Rust adapters consume that generated manifest and generated wire schemas. No public route is independently handwritten in the application. The manifest is not an IPC permission grant.

@AlexStocks AlexStocks Oct 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 新增的生成链前置（PATH 上的 java、首次运行下载 JAR）未写入两份 README 的构建前置

本 PR 把 generate:check 的代价从纯 Node 计算变成「启动 JVM + 可能下载 JAR + 调用 rustfmt」，但 desktop/README.md 第 20 行的前置清单与 README.zh.md 对应位置仍只有 VS C++ Build Tools、Node 24.14.1、pnpm 11.13.1、Rust 1.95.0、WebView2。

证据链：

  1. desktop/scripts/generate.mjs 第 194 行是顶层 const rustModels = await generateRustModels();，--check 分支在第 226 行才开始比对字节 ⇒ generate:check 同样执行生成器，不是只读校验。generateRustModels() 内先 pnpm exec openapi-generator-cli generate ...，再 run("rustfmt", ["--edition", "2024", wirePath])。
  2. desktop/package.json 的 lint 与 build 都串了 generate:check；CI 日志（job 118638863265）可对照：第 460 行 $ oxlint ui scripts && pnpm generate:check && ...，第 527 行 $ pnpm generate:check && tsc --noEmit && vite build。即 pnpm lint / pnpm build 两个常规命令都依赖该链路。
  3. 该 CLI 的官方要求：「The OpenAPI Generator is a Java project. openapi-generator-cli will download the appropriate JAR file and invoke the java executable to run the OpenAPI Generator. You must have the java binary executable available on your PATH for this to work. (JDK 11 is the minimal version supported.)」（openapitools/openapi-generator-cli）
  4. CI 通过不能证明本地可复现：windows-2025 runner 的 PATH 已预装 C:/hostedtoolcache/windows/Java_Temurin-Hotspot_jdk/17.0.20-101/x64/bin（同一 job 日志的环境 PATH 行），仓库未声明这一前置。JAR 在首次运行时从 Maven Central/Sonatype 拉取，无哈希校验，openapitools.json 只固定版本串。

影响：缺 JDK 或无法访问 Maven 的贡献者执行 pnpm --dir desktop lint / build 会在 generate:check 阶段失败，而 README 的构建前置不会指向原因。

建议：在 desktop/README.md 的前置段落与其 README.zh.md 对应段落同时补上 JDK 11+ 与「首次 generate 需访问 Maven Central」；若希望离线可复现，在 openapitools.json 里加 storageDir 或说明预置 JAR 的位置。无需改动产品运行时行为。

@CX33071 CX33071 Oct 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in the latest update.
Both desktop/README.md and desktop/README.zh.md now document:

  • JDK 11 or newer
  • java must be available on PATH
  • generate and generate:check invoke the Java-based OpenAPI Generator
  • the first run may download the pinned Generator JAR from Maven Central and therefore requires network access
    I also verified the updated setup with pnpm install --frozen-lockfile, pnpm generate:check, and pnpm typecheck.

@AlexStocks AlexStocks Oct 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

确认已在 head e7ce9f38 修复，两份文档均已落实且语义一致。

改动核实（提交 6f5d5074，desktop/README.md +3/-1、desktop/README.zh.md +3/-1）：

  • README.md 第 20 行前置清单已含 JDK 11 or newer with `java` available on `PATH` ；README.zh.md 第 20 行为「JDK 11 或更高版本（确保 java 位于 PATH 中）」，与英文版逐项对应。
  • 两份均新增一段说明：generate / generate:check 启动基于 Java 的 OpenAPI Generator，首次运行可能从 Maven Central 下载固定版本 JAR、因此首次生成或漂移检查需网络，后续可复用。英文用 may download、中文用「可能……下载」，措辞与「已有缓存时不下载」的实际行为一致，未过度声明。
  • 「JDK 11」这一下限对 openapitools.json 固定的 Generator 7.26.0 准确：上游 README 写明 Java 11 runtime at a minimum，安装前置列 * [Java 11]；openapitools.json 的 version 为 7.26.0，未随本次合并漂移。

声称的验证已由 CI 独立证实（Desktop validation / windows，run 39590150278，job 119188793670，head_sha=e7ce9f38，conclusion success）：

  • pnpm install --frozen-lockfile 通过（说明 merge 解决的 pnpm-lock.yaml 冲突与 package.json 自洽）
  • pnpm lint 输出 $ node scripts/generate.mjs --check → Desktop contract matches OpenAPI.
  • pnpm typecheck（tsc --noEmit）、pnpm test（vitest）、pnpm build（含 generate:check + tsc + vite build）、cargo fmt --check、cargo clippy --all-targets -- -D warnings、cargo test、pnpm ipc:check 全部通过，且 pnpm tauri build --bundles nsis 完成

一处可选改进，不阻塞合并：desktop/.mise.toml 目前只 pin 了 node 与 pnpm，未包含 java。用 mise 的贡献者仍需自行装 JDK，mise 无法一键就绪。若希望与「Node/pnpm 版本由 .mise.toml 固定」的原则对齐，可考虑加一行 Java（例如 java = "temurin-21"），同时保持 README 的 11+ 下限不变。

该线程可以关闭。


`cargo run --locked --manifest-path desktop/src-tauri/Cargo.toml --example export_ipc` derives the TypeScript IPC request/receipt/error types from Rust. `ipc:check` verifies them. IPC exposes typed connection, Scope, memory and diagnostic operations to the main window only; no generic fetch, shell, file, database or secret-read command is granted.

Expand Down
5 changes: 4 additions & 1 deletion desktop/README.zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,9 @@

## 开发与构建

Windows 11 x64 上需要 Node 24.14.1、pnpm 11.13.1、Rust 1.95.0 MSVC、Visual Studio C++ Build Tools、Windows SDK 和 WebView2。安装后的用户程序不依赖 Node、Rust、Python 或本地 Server。
Windows 11 x64 上需要 Node 24.14.1、pnpm 11.13.1、Rust 1.95.0 MSVC、JDK 11 或更高版本（确保 `java` 位于 `PATH` 中）、Visual Studio C++ Build Tools、Windows SDK 和 WebView2。安装后的用户程序不依赖 Node、Rust、Python 或本地 Server。

`generate` 和 `generate:check` 会启动基于 Java 的 OpenAPI Generator。首次运行时，`openapi-generator-cli` 可能从 Maven Central 下载固定版本的 Generator JAR，因此首次生成或漂移检查需要网络访问；后续运行可以复用已下载的 JAR。

从仓库根目录执行：

Expand Down Expand Up @@ -44,6 +46,7 @@ pnpm --dir desktop desktop:dev
工程边界：

- OpenAPI 自动派生的 TypeScript schema 和十项 operation 映射，包含契约摘要及漂移检查。
- `desktop/openapitools.json` 固定 OpenAPI Generator CLI 版本，Rust 模板位于 `desktop/scripts/openapi-generator/rust/`。修改 OpenAPI 合同或模板后，在仓库根目录执行 `pnpm --dir desktop generate`，不要手动编辑生成的 `src-tauri/src/transport/wire.rs`；CI 通过 `pnpm --dir desktop generate:check` 检查生成结果是否漂移。
- Rust 自动派生的 IPC 类型与安全错误；凭据只写请求必须显式选择持久化或仅会话，成功回执只含存储模式，不含秘密或凭据标识。
- Windows Credential Manager 原生适配器；保存失败直接报错，只有显式选择才采用仅会话内存。秘密类型不支持序列化，不实现 Debug。
- 使用系统证书信任的原生 HTTPS；可为单个客户端添加显式 CA，继续校验主机名。
Expand Down
7 changes: 7 additions & 0 deletions desktop/openapitools.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
"spaces": 2,
"generator-cli": {
"version": "7.26.0"
}
}
1 change: 1 addition & 0 deletions desktop/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
},
"devDependencies": {
"@tauri-apps/cli": "2.11.4",
"@openapitools/openapi-generator-cli": "2.41.0",
"@testing-library/react": "16.3.0",
"@testing-library/user-event": "14.6.1",
"@types/node": "26.3.0",
Expand Down
Loading
Loading