87 lines
4.6 KiB
Markdown
87 lines
4.6 KiB
Markdown
# Design
|
|
|
|
## Boundary
|
|
|
|
本任务增加机器级 Dever 管理层。它拥有稳定入口、版本目录、项目版本分派、更新事务和共享缓存服务；版本化编译器继续拥有源码检查、生成和运行语义。项目仍通过现有 CLI 合同进入编译器。
|
|
|
|
## Directory Contract
|
|
|
|
发行安装器按平台选择机器级根目录，但根内布局一致：
|
|
|
|
```text
|
|
<toolchain>/
|
|
bin/
|
|
dever stable launcher
|
|
deverd cache/build service
|
|
state/
|
|
active-version
|
|
install.lock
|
|
versions/
|
|
<version>/
|
|
dever-core
|
|
manifest.json
|
|
runtime/
|
|
cache/
|
|
native/
|
|
downloads/
|
|
staging/
|
|
```
|
|
|
|
`bin/dever` 是机器上唯一公开入口。`versions/*`、`state/*` 与缓存目录不加入 PATH，也不要求用户直接操作。目录根由安装器写入 launcher 自身的安装位置，运行时不读取环境变量。
|
|
|
|
## Command Flow
|
|
|
|
1. launcher 解析命令和项目根，不读取 Dever 源码。
|
|
2. 对项目命令只解析 `config/setting.json` 的 `dever.version`；存在时精确选择，否则读取机器 `active-version`。
|
|
3. launcher 校验版本 manifest 和核心可执行文件身份，然后把原参数分派给版本核心。
|
|
4. 核心完成现有 check/run/build 流程；需要原生产物时通过本机受保护 IPC 请求 `deverd`。
|
|
5. `deverd` 根据已安装版本和完整构建输入自行计算缓存键、编译或恢复产物，再将结果返回请求用户，客户端不能指定缓存文件路径。
|
|
|
|
`config/setting.json` 增加可选配置：
|
|
|
|
```json
|
|
{
|
|
"dever": {
|
|
"version": "0.1.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
runtime 配置解析器接受并忽略已经由 launcher 消费的 `dever` 段，确保同一配置可以同时用于 `run` 和独立构建产物；构建产物不使用该字段选择自身 runtime。
|
|
|
|
## Ownership
|
|
|
|
- `dever-cli`：稳定 launcher 命令合同、项目版本读取和版本核心分派。
|
|
- 独立 machine manager 模块：安装、更新、切换、卸载、签名验证和原子状态变更；不把这些分散进每个命令分支。
|
|
- `dever-runtime::config`：只增加严格的 `dever.version` 配置合同，不承担安装或版本选择。
|
|
- `dever-core::native::build`：把默认缓存请求交给共享服务；保留显式隔离缓存入口供测试使用。
|
|
- cache service：唯一可写共享缓存的进程，负责密码学键、编译、恢复、并发发布、租约和清理。
|
|
- 平台 adapter：只封装全局路径、权限提升、服务管理和 IPC 差异；上层状态机和版本规则只有一套。
|
|
|
|
## Install And Update Transaction
|
|
|
|
下载先进入 `cache/downloads`，验证发行 manifest 签名、包摘要、平台和版本后解包到 `cache/staging`。核心自检成功后原子发布到 `versions/<version>`，最后原子更新 `active-version`。任一步失败都删除 staging 并保留旧版本。卸载同样持有 `install.lock`，不能删除当前版本或正在服务请求的版本。
|
|
|
|
初次安装由签名的系统安装器建立全局入口、机器服务、权限和初始版本；之后统一由 `dever install/update/use/uninstall` 管理。需要管理员权限时使用平台标准提权流程，不保存凭据。
|
|
|
|
## Cache Security And Cleanup
|
|
|
|
- `deverd` 使用专用系统身份，缓存目录只允许该身份写入。
|
|
- 本地 IPC 使用操作系统凭据识别调用者；请求只包含规范化构建输入，不接受任意读写路径。
|
|
- 缓存键使用 SHA-256 等密码学摘要；命中前复核 manifest 与产物摘要。
|
|
- 客户端只有提交完整相同输入才能取得同一产物，服务不提供缓存目录列表或其他项目索引。
|
|
- 运行中的条目持有租约。清理只删除无租约的 staging、损坏条目和按策略选出的旧条目，并使用原子删除/替换。
|
|
- `cache status` 输出容量、条目数和版本占用，不输出项目源码、路径或用户信息。
|
|
|
|
## Failure Contract
|
|
|
|
全局入口、活动版本状态、项目锁定、签名、版本 manifest、IPC 或缓存完整性任一验证失败时返回明确错误。不得静默切换版本、使用用户 PATH 中的编译器、改写项目配置或执行未验证产物。
|
|
|
|
## Compatibility
|
|
|
|
开发态 `deverc` 保持为私有仓库入口直到正式发行链完成。正式 `dever` 不读取开发仓库 `target/native-artifacts`。已有项目无需新增配置；只有需要固定版本的项目才增加 `dever.version`。
|
|
|
|
## Deferred Complexity
|
|
|
|
本任务不重复实现父发行任务的原生后端、目标包生产和发布基础设施。安装管理层必须以父任务提供的签名发行包为输入；在发行包合同完成前可以实现和测试本地 fixture，但不能宣称公开安装链已完成。
|