Files

T

zhenyi 66afd932ed feat(api): extend commit and diff services with new functionality

- 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

2026-06-08 15:37:08 +08:00

24 KiB

Raw Blame History

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 按实际用户需求驱动，不必全部实现。

24 KiB Raw Blame History Unescape Escape

GitKS RPC 补齐任务

P0 — 核心功能缺失（影响基本使用场景）

P0-1. RefService — 原子性引用操作

P0-2. RepositoryService — FindMergeBase

P0-3. RepositoryService — SearchFiles（代码搜索）

P0-4. RepositoryService — WriteRef

P1 — 重要功能缺失（影响高级场景）

P1-1. RemoteService — 远程仓库交互

P1-2. RepositoryService — FetchRemote / CreateRepositoryFromURL

P1-3. CommitService — 扩展查询能力

P1-4. RepositoryService — ObjectsSize / RepositorySize

P1-5. DiffService — RawDiff / RawPatch

P1-6. CommitService — CommitStats / LastCommitForPath

P2 — 锦上添花（完善体验）

P2-1. RepositoryService — FindLicense

P2-2. RepositoryService — OptimizeRepository

P2-3. RepositoryService — GetRawChanges

P2-4. CommitService — CountCommits / CountDivergingCommits

P2-5. RefService — FindRefsByOID / ListRefs（增强查询）

P2-6. DiffService — FindChangedPaths

P3 — 低优先级（生态特定 / 边缘场景）

P3-1. ObjectPoolService（Fork 去重）

P3-2. HookService（Server 端 gRPC Hook 回调）

P3-3. CommitService — GPG 签名相关

P3-4. SmartHTTP / SSH Service — Sidechannel + SSH 支持

P3-5. ServerService — 健康检查 / 磁盘统计

汇总

24 KiB

Raw Blame History

P0-1. `RefService` — 原子性引用操作

P0-2. `RepositoryService` — FindMergeBase

P0-3. `RepositoryService` — SearchFiles（代码搜索）

P0-4. `RepositoryService` — WriteRef

P1-1. `RemoteService` — 远程仓库交互

P1-2. `RepositoryService` — FetchRemote / CreateRepositoryFromURL

P1-3. `CommitService` — 扩展查询能力

P1-4. `RepositoryService` — ObjectsSize / RepositorySize

P1-5. `DiffService` — RawDiff / RawPatch

P1-6. `CommitService` — CommitStats / LastCommitForPath

P2-1. `RepositoryService` — FindLicense

P2-2. `RepositoryService` — OptimizeRepository

P2-3. `RepositoryService` — GetRawChanges

P2-4. `CommitService` — CountCommits / CountDivergingCommits

P2-5. `RefService` — FindRefsByOID / ListRefs（增强查询）

P2-6. `DiffService` — FindChangedPaths