zhenyi
66afd932ed
- Add FindCommit, ListCommitsByOid, CommitIsAncestor RPCs to CommitService - Add CheckObjectsExist, CommitsByMessage, GetCommitStats RPCs to CommitService - Add LastCommitForPath, CountCommits, CountDivergingCommits RPCs to CommitService - Add RawDiff, RawPatch, FindChangedPaths RPCs to DiffService - Add FindMergeBase, WriteRef, SearchFilesByContent RPCs to RepositoryService - Add SearchFilesByName, ObjectsSize, RepositorySize RPCs to RepositoryService - Add FindLicense, OptimizeRepository, GetRawChanges RPCs to RepositoryService - Add FetchRemote, CreateRepositoryFromURL RPCs to RepositoryService - Implement server handlers for all new RPC methods - Add new modules for commit counting, finding, and querying features - Add new modules for diff changed paths and raw operations - Add new modules for refs and remote operations - Remove unnecessary comments from various source files - Update proto definitions with new message types and service methods
226 lines
24 KiB
Markdown
226 lines
24 KiB
Markdown
# GitKS RPC 补齐任务
|
||
|
||
> 对照 Gitaly 分析后，梳理有必要实现但目前缺失的功能，按优先级排列。
|
||
> 每个任务标注：类别、预估工作量、前置依赖、实现思路。
|
||
|
||
---
|
||
|
||
## P0 — 核心功能缺失（影响基本使用场景）
|
||
|
||
### P0-1. `RefService` — 原子性引用操作
|
||
|
||
| 项 | 内容 |
|
||
|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `UpdateReferences`, `DeleteRefs`, `FindDefaultBranchName`, `RefExists` |
|
||
| **Proto** | 新建 `proto/ref.proto`（独立 RefService） |
|
||
| **工作量** | **M**（3-5 天） |
|
||
| **为什么必要** | 当前 `branch.proto` / `tag.proto` 每个操作单独一个 RPC，无法做批量原子更新。`UpdateReferences` 是 Gitaly 中最核心的写操作之一，支持 `expected_old_oid` 校验 |
|
||
| **实现思路** | 1. 新建 `ref/` 模块 2. `UpdateReferences` 调用 `git update-ref --stdin` 批量原子更新 3. `DeleteRefs` 调用 `git update-ref -d` 批量删除 4. `RefExists` 用 `gix` 检查 reference 是否存在 5. `FindDefaultBranchName` 从已有的 `default_branch_name()` 抽取 |
|
||
|
||
### P0-2. `RepositoryService` — FindMergeBase
|
||
|
||
| 项 | 内容 |
|
||
|------------|-----------------------------------------------------------------------------|
|
||
| **新增 RPC** | `FindMergeBase` |
|
||
| **Proto** | 扩展现有 `proto/repository.proto` |
|
||
| **工作量** | **S**（1 天） |
|
||
| **为什么必要** | diff、merge、rebase 操作都依赖 merge-base 计算。当前 GitKS 的 merge/diff 模块各自计算，缺少独立 API |
|
||
| **实现思路** | 调用 `gix::Repository::merge_base()` 返回两个 revision 的 merge base OID |
|
||
|
||
### P0-3. `RepositoryService` — SearchFiles（代码搜索）
|
||
|
||
| 项 | 内容 |
|
||
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `SearchFilesByContent`, `SearchFilesByName` |
|
||
| **Proto** | 扩展现有 `proto/repository.proto` |
|
||
| **工作量** | **M**（2-3 天） |
|
||
| **为什么必要** | 代码搜索是代码托管平台的基础功能，当前完全缺失 |
|
||
| **实现思路** | `SearchFilesByContent` → `git grep -I --line-number --column <pattern> <revision>`；`SearchFilesByName` → `git ls-tree -r --name-only <revision>` + 正则过滤。需注意大仓库性能（加 timeout、limit） |
|
||
|
||
### P0-4. `RepositoryService` — WriteRef
|
||
|
||
| 项 | 内容 |
|
||
|------------|------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `WriteRef` |
|
||
| **Proto** | 扩展现有 `proto/repository.proto` |
|
||
| **工作量** | **S**（0.5 天） |
|
||
| **为什么必要** | 直接写 ref 是最底层的仓库操作，Replica 同步、快照恢复都依赖此能力。当前 `sync.rs` 中 `update_local_ref` 是内部函数，应暴露为 RPC |
|
||
| **实现思路** | `git update-ref <ref> <new_oid> <old_oid?>` -- 已有 `update_local_ref` 可直接封装 |
|
||
|
||
---
|
||
|
||
## P1 — 重要功能缺失（影响高级场景）
|
||
|
||
### P1-1. `RemoteService` — 远程仓库交互
|
||
|
||
| 项 | 内容 |
|
||
|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 Service** | `RemoteService`（3 个 RPC） |
|
||
| **新增 RPC** | `FindRemoteRepository`, `FindRemoteRootRef`, `UpdateRemoteMirror` |
|
||
| **Proto** | 新建 `proto/remote.proto` |
|
||
| **工作量** | **L**（5-7 天） |
|
||
| **为什么必要** | 支持从远程 URL 导入仓库、镜像同步。`FetchRemote` 在 Gitaly 的 RepositoryService 中也有对应 |
|
||
| **实现思路** | 1. `FindRemoteRepository` → `git ls-remote <url>` 2. `FindRemoteRootRef` → 取 ls-remote 的 HEAD 3. `UpdateRemoteMirror` → `git remote add` + `git fetch --mirror` + 清理。需注意认证（支持 SSH key / token 注入） |
|
||
|
||
### P1-2. `RepositoryService` — FetchRemote / CreateRepositoryFromURL
|
||
|
||
| 项 | 内容 |
|
||
|------------|----------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `FetchRemote`, `CreateRepositoryFromURL` |
|
||
| **Proto** | 扩展现有 `proto/repository.proto` |
|
||
| **工作量** | **M**（3-4 天） |
|
||
| **为什么必要** | 仓库导入是核心 onboarding 流程，当前只能创建空仓库 |
|
||
| **实现思路** | `CreateRepositoryFromURL` → `git clone --bare --mirror <url> <path>`；`FetchRemote` → `git fetch <remote> <refspec>`。复用 RemoteService 的认证基础设施 |
|
||
|
||
### P1-3. `CommitService` — 扩展查询能力
|
||
|
||
| 项 | 内容 |
|
||
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `FindCommit`, `ListCommitsByOid`, `CommitIsAncestor`, `CheckObjectsExist`, `CommitsByMessage` |
|
||
| **Proto** | 扩展现有 `proto/commit.proto` |
|
||
| **工作量** | **M**（3-4 天） |
|
||
| **为什么必要** | 当前 `list_commits` / `get_commit` 太基础，缺少批量查询、ancestor 判断、message 搜索等常用模式 |
|
||
| **实现思路** | 1. `FindCommit` → `gix::Repository::find_object()` + 解析 Commit 2. `ListCommitsByOid` → 批量 `gix::Repository::find_commit()` 3. `CommitIsAncestor` → `gix::Repository::merge_base()` 判断 4. `CheckObjectsExist` → 批量 `gix::Repository::try_find()` 5. `CommitsByMessage` → `git log --all --grep=<pattern>` |
|
||
|
||
### P1-4. `RepositoryService` — ObjectsSize / RepositorySize
|
||
|
||
| 项 | 内容 |
|
||
|------------|---------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `ObjectsSize`, `RepositorySize` |
|
||
| **Proto** | 扩展现有 `proto/repository.proto` |
|
||
| **工作量** | **S**（1 天） |
|
||
| **为什么必要** | 前端需要展示仓库大小、文件大小，当前 `RepositoryStatistics` 只有对象计数没有大小 |
|
||
| **实现思路** | `ObjectsSize` → `git cat-file --batch-check` 批量获取对象大小；`RepositorySize` → `du -sb <repo>` 或遍历 objects 目录 |
|
||
|
||
### P1-5. `DiffService` — RawDiff / RawPatch
|
||
|
||
| 项 | 内容 |
|
||
|------------|---------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `RawDiff`, `RawPatch` |
|
||
| **Proto** | 扩展现有 `proto/diff.proto` |
|
||
| **工作量** | **S**（1 天） |
|
||
| **为什么必要** | 当前 `get_diff` 返回结构化 protobuf，对于大 diff 非常低效。Raw 格式可直接流式返回文本，用于 patch 应用、邮件发送 |
|
||
| **实现思路** | `RawDiff` → `git diff <base>..<head>` streaming stdout；`RawPatch` → `git format-patch <base>..<head>` streaming。注意大 diff 时的内存控制 |
|
||
|
||
### P1-6. `CommitService` — CommitStats / LastCommitForPath
|
||
|
||
| 项 | 内容 |
|
||
|------------|--------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `CommitStats`, `LastCommitForPath` |
|
||
| **Proto** | 扩展现有 `proto/commit.proto` |
|
||
| **工作量** | **S**（1 天） |
|
||
| **为什么必要** | 文件列表需要显示最后修改 commit，commit 详情需要统计信息。当前 `CommitStats` 内嵌在 `Commit` message 中需额外请求才填充 |
|
||
| **实现思路** | `CommitStats` → `git diff --stat <commit>^..<commit>` 解析输出；`LastCommitForPath` → `git log -1 --format=%H <revision> -- <path>` |
|
||
|
||
---
|
||
|
||
## P2 — 锦上添花（完善体验）
|
||
|
||
### P2-1. `RepositoryService` — FindLicense
|
||
|
||
| 项 | 内容 |
|
||
|------------|-----------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `FindLicense` |
|
||
| **工作量** | **S**（1 天） |
|
||
| **实现思路** | 基于 GitHub Licensee 算法：读取 `LICENSE*` / `COPYING*` 文件 → 用 go-license-detector 等价逻辑（Rust 可用 `askalono` crate）做文本匹配 |
|
||
|
||
### P2-2. `RepositoryService` — OptimizeRepository
|
||
|
||
| 项 | 内容 |
|
||
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `OptimizeRepository` |
|
||
| **工作量** | **M**（2-3 天） |
|
||
| **实现思路** | 根据仓库状态自动决定优化策略：loose objects > N → `repack -d`；packfiles > N → `repack -ad`；没有 commit-graph → `commit-graph write`；没有 bitmap → `repack -adb`。比当前单独调用 `gc`/`repack`/`write_commit_graph` 更智能 |
|
||
|
||
### P2-3. `RepositoryService` — GetRawChanges
|
||
|
||
| 项 | 内容 |
|
||
|------------|------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `GetRawChanges` |
|
||
| **工作量** | **S**（0.5 天） |
|
||
| **实现思路** | `git diff-tree --raw -r <base>..<head>` 返回纯文件级变更列表（旧模式、新模式、状态），不生成完整 diff 内容 |
|
||
|
||
### P2-4. `CommitService` — CountCommits / CountDivergingCommits
|
||
|
||
| 项 | 内容 |
|
||
|------------|-----------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `CountCommits`, `CountDivergingCommits` |
|
||
| **工作量** | **S**（0.5 天） |
|
||
| **实现思路** | `CountCommits` → `git rev-list --count <revision>`；`CountDivergingCommits` → `git rev-list --count --left-right <left>...<right>` |
|
||
|
||
### P2-5. `RefService` — FindRefsByOID / ListRefs（增强查询）
|
||
|
||
| 项 | 内容 |
|
||
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `FindRefsByOID`, `ListRefs` |
|
||
| **工作量** | **S**（1 天） |
|
||
| **实现思路** | `FindRefsByOID` → `git for-each-ref --points-at=<oid>`；`ListRefs` → `git for-each-ref --format=... --sort=...` 通用 ref 列表（当前只能在 branch/tag service 中分别查询） |
|
||
|
||
### P2-6. `DiffService` — FindChangedPaths
|
||
|
||
| 项 | 内容 |
|
||
|------------|-----------------------------------------------------------------------------------------------|
|
||
| **新增 RPC** | `FindChangedPaths` |
|
||
| **工作量** | **S**（0.5 天） |
|
||
| **实现思路** | `git diff-tree --name-status -r <base>..<head>` 只返回变更的文件路径和状态（A/M/D/R），无 diff 内容，适合只展示文件列表的场景 |
|
||
|
||
---
|
||
|
||
## P3 — 低优先级（生态特定 / 边缘场景）
|
||
|
||
### P3-1. ObjectPoolService（Fork 去重）
|
||
|
||
| 项 | 内容 |
|
||
|----------------|------------------------------------------------------------------------------|
|
||
| **新增 Service** | `ObjectPoolService`（6 个 RPC） |
|
||
| **工作量** | **XL**（2-3 周） |
|
||
| **前置依赖** | P0-1 `UpdateReferences` 稳定后 |
|
||
| **为什么低优** | Fork 去重是 GitLab.com 级别的需求。单租户或小规模部署用不上，且实现复杂（需管理 alternates、pool 生命周期、GC 协调） |
|
||
|
||
### P3-2. HookService（Server 端 gRPC Hook 回调）
|
||
|
||
| 项 | 内容 |
|
||
|----------------|------------------------------------------------------------------------------------|
|
||
| **新增 Service** | `HookService`（6 个 RPC） |
|
||
| **工作量** | **L**（1-2 周） |
|
||
| **为什么低优** | GitKS 的 hook 是内嵌脚本执行的"客户端模式"，改为 gRPC 回调的"server 模式"需要对 hook runner 彻底重构，且需要下游客户端对接 |
|
||
|
||
### P3-3. CommitService — GPG 签名相关
|
||
|
||
| 项 | 内容 |
|
||
|------------|-------------------------------------------------------------------------|
|
||
| **新增 RPC** | `GetCommitSignatures`, `FilterShasWithSignatures`, `GetTagSignatures` |
|
||
| **工作量** | **M**（2-3 天） |
|
||
| **为什么低优** | 需要 GPG 工具链依赖。可用 `gpg --verify` 或 `sequoia-openpgp`（Rust crate）实现，但非刚性需求 |
|
||
|
||
### P3-4. SmartHTTP / SSH Service — Sidechannel + SSH 支持
|
||
|
||
| 项 | 内容 |
|
||
|-----------|--------------------------------------------------------------------------------------------------|
|
||
| **新增/扩展** | `PostUploadPackWithSidechannel`, `SSHUploadPack`, `SSHReceivePack` |
|
||
| **工作量** | **XL**（3-4 周） |
|
||
| **为什么低优** | Sidechannel 需要 Unix socket 旁路，平台依赖强。SSH 支持需要完整的 SSH server 协议栈（或依赖外部 SSH → gRPC 代理）。建议通过外部网关层来解决 |
|
||
|
||
### P3-5. ServerService — 健康检查 / 磁盘统计
|
||
|
||
| 项 | 内容 |
|
||
|----------------|--------------------------------------------------------------------------------------------------------------------------|
|
||
| **新增 Service** | `ServerService`（4 个 RPC） |
|
||
| **工作量** | **S**（1 天） |
|
||
| **为什么低优** | GitKS 已有 Prometheus metrics endpoint + logging，`ServerInfo`/`ReadinessCheck`/`DiskStatistics` 更多用于 Kubernetes/平台集成。可快速补充 |
|
||
|
||
---
|
||
|
||
## 汇总
|
||
|
||
| 优先级 | Service 数 | RPC 数 | 预估总工作量 |
|
||
|--------|-------------|---------|------------------------|
|
||
| **P0** | 2（扩展现有） | 9 | ~8 天 |
|
||
| **P1** | 1 新建 + 4 扩展 | 17 | ~17 天 |
|
||
| **P2** | 3 扩展 | 9 | ~7 天 |
|
||
| **P3** | 3 新建 + 2 扩展 | 22+ | ~10 周 |
|
||
| **合计** | | **57+** | **~13 周**（P0-P2 约 5 周） |
|
||
|
||
> **建议路线**：优先完成 P0 + P1（共 26 个 RPC，约 4-5 周），可覆盖 80% 的常用场景。
|
||
> P2 在核心功能稳定后逐步添加。P3 按实际用户需求驱动，不必全部实现。
|