Skip to content

Commit 8e11572

Browse files
genednaclaude
andcommitted
docs: ImportRepo update contract and lifecycle user docs (FU-22, #26, #27)
- user-guide(.zh).md: new section 2.6 "ImportRepo lifecycle", the home of the ImportRepo update/removal/retention contract and of the operator CLI `mega2 import-repo remove` (usage, prerequisites, outcome lines and exit codes, continuation, ledger checks, recovery after a kill, legacy mount exceptions); section 4.6 for the HTTP removal endpoint; a CLI table row. Wording that contradicted the update contract is scoped to Monorepo paths (2.1, 4.2, the MONO_PATH_NOT_ALLOWED note, the write-queue claims in section 1 and 4.1). - quick-start(.zh).md: the migration example gains a second push, mirror sync (with the LFS steps) and removal with the CLI inside the container. - README(.zh).md: one contract sentence (later pushes accepted; removal via POST /api/v1/import-repo/remove with a token, or the CLI on push_auth=none deployments). - errors.md: the ImportRepo rows and the cleanup scenarios name the CLI and its exit code. No code change. C/D coverage comes from FU-23. Plan: docs/plan/plan-20260923.md (FU-22; DEFER-FU-49). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Eli Ma <eli@patch.sh>
1 parent fb66649 commit 8e11572

8 files changed

Lines changed: 211 additions & 31 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Use `libra mega2 browser --server https://mega2.example.com` to browse a remote
2424

2525
Mega2 provides trunk-based Git storage and hosting for monorepos. Regular Monorepo paths expose `refs/heads/main` as the public trunk; Git clients cannot push other branches or tags. Use the HTTP API or Libra's terminal browser for supported Tag and directory operations. The open-source edition does not include the multi-branch Change List feature.
2626

27-
Git metadata is stored in Postgres, while Git objects live in local or S3-compatible object storage. ImportRepos under `[monorepo].import_dir` (default `/third-party`) follow ordinary Git semantics, including multiple branches and client-managed tags, and can hold third-party repositories that need independent synchronization. See [Monorepo path policy and first use](docs/user-guide.md#25-monorepo-path-policy-and-first-use) for path provisioning and push rules.
27+
Git metadata is stored in Postgres, while Git objects live in local or S3-compatible object storage. ImportRepos under `[monorepo].import_dir` (default `/third-party`) follow ordinary Git semantics, including multiple branches and client-managed tags, and can hold third-party repositories that need independent synchronization. ImportRepos accept later pushes (branches and tags) and can be removed through `POST /api/v1/import-repo/remove` (which needs a push token; `push_auth=none` deployments run `mega2 import-repo remove` on the server instead); see [ImportRepo lifecycle](docs/user-guide.md#26-importrepo-lifecycle). See [Monorepo path policy and first use](docs/user-guide.md#25-monorepo-path-policy-and-first-use) for path provisioning and push rules.
2828

2929
### Agent Session Capture
3030

‎README.zh.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Mega2 开源版以 **trunk / storage-only** 模式运行,不提供 Web UI 或
2424

2525
Mega2 为 monorepo 提供 trunk-based Git 存储与托管。普通 monorepo 路径以 `refs/heads/main` 为公开主干;Git 客户端不能推送其它分支或 Tag,受支持的 Tag 与目录操作通过 HTTP API 或 Libra 终端浏览器完成。开源版不包含依赖多分支的 Change List。
2626

27-
Git 元数据存于 Postgres,Git 对象存于本地或 S3-compatible 对象存储。`[monorepo].import_dir`(默认 `/third-party`)下的 ImportRepo 遵循普通 Git 语义,可使用多个分支和客户端 Tag,适合存放需要独立同步的第三方仓库。新路径开通与推送规则见[Monorepo 路径策略](docs/user-guide.zh.md#25-monorepo-路径策略与首次使用)。
27+
Git 元数据存于 Postgres,Git 对象存于本地或 S3-compatible 对象存储。`[monorepo].import_dir`(默认 `/third-party`)下的 ImportRepo 遵循普通 Git 语义,可使用多个分支和客户端 Tag,适合存放需要独立同步的第三方仓库。ImportRepo 接受后续推送(分支与 tag),并可经 `POST /api/v1/import-repo/remove` 清理(需要 push token;`push_auth=none` 的部署在服务器上运行 `mega2 import-repo remove`),见[ImportRepo 生命周期](docs/user-guide.zh.md#26-importrepo-生命周期)。新路径开通与推送规则见[Monorepo 路径策略](docs/user-guide.zh.md#25-monorepo-路径策略与首次使用)。
2828

2929
### Agent Session Capture
3030

‎docs/errors.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -145,9 +145,9 @@ report-status 行为 `ng refs/heads/main <文本>`;`git push` 显示为 `! [re
145145
| `StaleRef { ref_name, expected }` | `IMPORT_REPO_STALE_REF` | 409 | ImportRepo 推送的 ref 更新未通过服务端 CAS(ADR-FU-08 第 2 条):`Create` 时该 ref 已存在,`Update` / `Delete` 时它已不再指向客户端声称的 `old_id`(广告之后有别的推送或 API 写入)。`fetch` 后重推即可 |
146146
| `PathOccupied { path }` | `IMPORT_REPO_PATH_OCCUPIED` | 409 | ImportRepo 推送的挂载位置已被不属于该仓库的内容占用(ADR-FU-08 第 1 条):该路径在 Monorepo 根树中是普通目录或文件,且没有该仓库的挂载来源记录(存量挂载按「只含 `.gitkeep` 且仓库已有分支」惰性回填,不在此列)。根树不变;换一个路径导入,或由运维清理占用的内容 |
147147
| `Removed { path }` | `IMPORT_REPO_REMOVED` | 409 | 推送或产品 API 写(编辑保存、tag 创建 / 删除)进行期间,该 ImportRepo 已被清理(detach,ADR-FU-09 第 5 条):被拒绝的那次写不落任何行(对象行、tag、分支 ref、`file_path` 都不写,叶子不会被重新挂载);编辑保存分两个事务写对象行与默认分支 ref,二者之间遇 detach 时,已提交的对象行留给清扫删除。再推送一次即以新的 `repo_id` 重新导入。Git 面为 `ng` 行原文;API 面 `POST /api/v1/edit/save`、`POST /api/v1/tags` 与 `DELETE /api/v1/tags/{name}` 返回 409 |
148-
| `PathInvalid { path, reason }` | `IMPORT_REPO_PATH_INVALID` | 400 | 路径不是合法的 ImportRepo 叶子(ADR-FU-08 第 7 条、ADR-FU-10 第 1 条):协议分派在 TP-08 规范化之后、任何查找或注册之前,对进入 ImportRepo 分支的路径(以 `import_dir` 为组件前缀的绝对路径)拒绝 `import_dir` 本身、非规范形式与含 NUL 的路径(SSH 的相对写法如 `third-party` 照旧走 Monorepo 分支,计划 `DEFER-FU-37`);清理 API 与运维 CLI 的严格入口(FU-20 / FU-21 起)另拒绝 `\`、`..`、重复斜杠与结尾斜杠(`reason` 说明原因;输入可规范化但不是规范形式时给出应使用的规范形式 `did you mean …`)。不写任何行、ref、对象,根树不变;HTTP 清理端点在鉴权之前返回它 |
149-
| `HasChildren { path }` | `IMPORT_REPO_HAS_CHILDREN` | 409 | 清理目标之下仍有其它已注册 ImportRepo(`repo_path LIKE escape_like(P) \|\| '/%'`,绑定参数;规范形式等于 P 的别名行不算,ADR-FU-10 第 3 条):入口的无写预检(不入队、不写台账与审计)或 B3 锁内再检(写入队列行 `Failed`)拒绝,行、ref、对象与根树不变;文本不点名子仓;整页 64 行都是目标别名时保守视为有子仓(计划 `DEFER-FU-10`);先清理子仓。FU-20 起经 `POST /api/v1/import-repo/remove` 暴露 |
150-
| `CleanupNotFound { path, cleanup_id }` | `IMPORT_REPO_CLEANUP_NOT_FOUND` | 404 | 续做请求的 `cleanup_id` 不存在或属于另一路径:两者同一文本,只回显请求自己的 path 与 id(`no cleanup "<id>" for "<path>"`),不泄漏其它路径的台账;无写、永不 detach。FU-20 起经同一端点暴露 |
148+
| `PathInvalid { path, reason }` | `IMPORT_REPO_PATH_INVALID` | 400 | 路径不是合法的 ImportRepo 叶子(ADR-FU-08 第 7 条、ADR-FU-10 第 1 条):协议分派在 TP-08 规范化之后、任何查找或注册之前,对进入 ImportRepo 分支的路径(以 `import_dir` 为组件前缀的绝对路径)拒绝 `import_dir` 本身、非规范形式与含 NUL 的路径(SSH 的相对写法如 `third-party` 照旧走 Monorepo 分支,计划 `DEFER-FU-37`);清理 API 与运维 CLI 的严格入口(FU-20 / FU-21 起)另拒绝 `\`、`..`、重复斜杠与结尾斜杠(`reason` 说明原因;输入可规范化但不是规范形式时给出应使用的规范形式 `did you mean …`)。不写任何行、ref、对象,根树不变;HTTP 清理端点在鉴权之前返回它;运维 CLI `mega2 import-repo remove` 在连接数据库、Redis 与对象存储之前打印它(退出码 1) |
149+
| `HasChildren { path }` | `IMPORT_REPO_HAS_CHILDREN` | 409 | 清理目标之下仍有其它已注册 ImportRepo(`repo_path LIKE escape_like(P) \|\| '/%'`,绑定参数;规范形式等于 P 的别名行不算,ADR-FU-10 第 3 条):入口的无写预检(不入队、不写台账与审计)或 B3 锁内再检(写入队列行 `Failed`)拒绝,行、ref、对象与根树不变;文本不点名子仓;整页 64 行都是目标别名时保守视为有子仓(计划 `DEFER-FU-10`);先清理子仓。FU-20 起经 `POST /api/v1/import-repo/remove` 暴露;也由 `mega2 import-repo remove` 打印(退出码 1) |
150+
| `CleanupNotFound { path, cleanup_id }` | `IMPORT_REPO_CLEANUP_NOT_FOUND` | 404 | 续做请求的 `cleanup_id` 不存在或属于另一路径:两者同一文本,只回显请求自己的 path 与 id(`no cleanup "<id>" for "<path>"`),不泄漏其它路径的台账;无写、永不 detach。FU-20 起经同一端点暴露;也由 `mega2 import-repo remove --cleanup-id` 打印(退出码 1) |
151151

152152
出现场景(ImportRepo 推送,`import_dir` 之下;ADR-FU-08 第 1、4、5 条):tag 命令逐 ref 独立,失败的 tag 得到以 `IMPORT_REPO_STALE_REF` 开头的 `ng` 行;同一推送内的分支命令作为一批在同一 B3 事务内应用,任一分支 CAS 失败则整批回滚、所有分支 `ng`、无一分支前进,各分支的 `ng` 行都是陈旧那条命令的 `IMPORT_REPO_STALE_REF` 原文(只含删除的分支批同样经写入队列、只写 ref,不经物化预检与挂载归属判定,FU-13 起)(`Create` 遇到已存在的 ref 时为 `IMPORT_REPO_STALE_REF: "<ref>" already exists; fetch and push again`)。挂载位置不属于该仓库时得到 `IMPORT_REPO_PATH_OCCUPIED` 原文——首推遇到普通目录或文件,以及后续推送遇到既无来源记录、又不符合存量规则的叶子(例如叶子下已有嵌套子仓的存量父挂载,见计划 `DEFER-FU-23`)。FU-13 起经写入队列的失败不再带 `attach B3 did not complete successfully: {Debug}` 包装:客户端文本按挂载路径与本次推送的分支命令还原为上述类型化错误;物化预检的拒绝保留其明细,为 `Other error: ImportRepo attach failed: <明细>`(I3 祖先 / 后代 / 目标已物化);其余未归类的失败只返回 `Other error: ImportRepo attach failed (push_queue id <N>); retry the push`,原因只留在队列行(`push_queue.error_message`,可能含存储内部信息,不外露、不写日志);未执行完的轮次为 `Other error: ImportRepo attach for push_queue id <N> did not complete; retry the push`,等待被放弃为 `Other error: attach wait abandoned for push_queue id <N>`,重放后 ref 仍未生效为 `Other error: ImportRepo attach replayed push_queue id <N> but the refs did not move; retry the push`(这些回落文本是 `MegaError::Other`,`ng` 行带 `Other error: ` 前缀)(v0.40.1 中经队列的分支批失败仍被 Debug 包装)。
153153

@@ -161,6 +161,7 @@ report-status 行为 `ng refs/heads/main <文本>`;`git push` 显示为 `! [re
161161
- 判定顺序:axum 提取器的纯文本拒绝(400 / 413 / 415 / 422,不是 `CommonResult`)→ 400 `IMPORT_REPO_PATH_INVALID`(先于鉴权,与 Git 面相反)→ 固定体 401 `authentication required` / 403 `forbidden`(不是本域的码、不回显路径;`push_auth=none` 或未配置一律 403)→ 404 `IMPORT_REPO_CLEANUP_NOT_FOUND` / 409 `IMPORT_REPO_HAS_CHILDREN`(只对已授权调用方出现;不写台账、审计、ref、对象与根树,409 由写入队列锁内再检得出时留下一行 `Failed` 队列行)。
162162
- 例:`{"req_result":false,"data":null,"err_message":"IMPORT_REPO_HAS_CHILDREN: \"/third-party/p\" contains other ImportRepos; remove them first"}`、`{"req_result":false,"data":null,"err_message":"IMPORT_REPO_CLEANUP_NOT_FOUND: no cleanup \"12\" for \"/third-party/p\""}`。
163163
- 500 `Internal server error` 可重试(写入队列暂停 / 硬停 / 满、detach 轮次未完成、存储错误;计划 `DEFER-FU-42`);带 `cleanup_id` 的续做重试对重新导入安全,只带 `path`(不带 `cleanup_id`)的重试会 detach 当时存活的仓库。请求、结局语义与客户端协议见 [refactoring/directory-entry-api.md](refactoring/directory-entry-api.md) 的「ImportRepo 叶子清理」。
164+
- 运维 CLI `mega2 import-repo remove`(FU-21 起)把本域的错误原文写到 stderr、不输出结局行,以退出码 1 结束;结局行、其它退出码与续做见[使用指南](./user-guide.zh.md#26-importrepo-生命周期)第 2.6 节。
164165

165166
## 响应安全
166167

0 commit comments

Comments
 (0)