Files
knowledge-governance/internal/versionhistory/gitea.go
T
姚章浩 013ce4a24e
build / build (push) Successful in 1m3s
fix(version): 补全开发快照记录与同步交付闭环
收录 main、注释开发快照和完整运行 SHA;开发说明绑定原提交,补记 0.1.1–0.1.25。
进行中同步按仓库合并,完成后重新执行;启动入队,部署脚本读回版本证据。
开发快照独立于正式标签与 Release,既有冲突标签不移动。

已运行:整仓 make verify,Go 673 通过、前端 274 通过,92 个已声明可选跳过,必需跳过 0。
隔离 PostgreSQL 重复同步队列用例及 -race 通过;未更新现有 8088、未修改生产问答。
2026-10-18 18:11:49 +08:00

365 lines
13 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package versionhistory
import (
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"strings"
"time"
)
// GiteaConfig 是只读客户端的配置。**只用匿名请求**:本客户端不会携带任何凭据,
// 也不接受调用方传入任意 URL —— base 必须在白名单里,仓库只允许配置的那一个。
type GiteaConfig struct {
BaseURL string
AllowedBaseURLs []string
// LinkOrigin 是**给人看的链接**用的 origin(例如公网 https://gitea.example)。
// 抓取用内网地址、点链接的人在内网外 —— 两者必须能分开,否则页面上的链接打不开。
// 留空则与 BaseURL 相同。它只用于拼展示链接,不参与任何请求。
LinkOrigin string
Repo string
HTTPClient *http.Client
Timeout time.Duration
MaxResponseBytes int64
MaxRetries int
Sleep func(time.Duration)
PageSize int
}
// GiteaClient 只读地访问 Gitea 的提交、tag 与仓库内文件。
type GiteaClient struct {
baseURL *url.URL
linkOrigin string
repo string
client *http.Client
maxBytes int64
maxRetries int
sleep func(time.Duration)
pageSize int
}
const (
giteaDefaultTimeout = 15 * time.Second
giteaDefaultMaxBytes = 5 << 20 // 单个响应上限 5MB
giteaDefaultRetries = 3
giteaDefaultPageSize = 50 // Gitea 的 commits/tags 上限就是 50
giteaCommitURLSuffix = "/commit/"
)
// NewGiteaClient 校验并构造客户端。校验失败一律返回错误(宁可不接线)。
func NewGiteaClient(config GiteaConfig) (*GiteaClient, error) {
base, err := url.Parse(strings.TrimSpace(config.BaseURL))
if err != nil || base.Host == "" || (base.Scheme != "http" && base.Scheme != "https") {
return nil, errors.New("版本记录:Gitea base URL 非法(必须是 http(s) 绝对地址)")
}
allowed := false
for _, candidate := range config.AllowedBaseURLs {
parsed, perr := url.Parse(strings.TrimSpace(candidate))
if perr == nil && parsed.Host != "" && parsed.Scheme == base.Scheme && parsed.Host == base.Host {
allowed = true
break
}
}
if !allowed {
return nil, fmt.Errorf("版本记录:Gitea base URL %q 不在白名单里(拒绝任意 URL 请求)", config.BaseURL)
}
repo := strings.Trim(strings.TrimSpace(config.Repo), "/")
if strings.Count(repo, "/") != 1 || strings.ContainsAny(repo, " \t?#") {
return nil, errors.New("版本记录:仓库必须是 owner/name 形式")
}
maxBytes := config.MaxResponseBytes
if maxBytes <= 0 {
maxBytes = giteaDefaultMaxBytes
}
timeout := config.Timeout
if timeout <= 0 {
timeout = giteaDefaultTimeout
}
retries := config.MaxRetries
if retries <= 0 {
retries = giteaDefaultRetries
}
pageSize := config.PageSize
if pageSize <= 0 || pageSize > giteaDefaultPageSize {
pageSize = giteaDefaultPageSize
}
client := config.HTTPClient
if client == nil {
client = &http.Client{Timeout: timeout}
}
// 只允许回到同一个 host:重定向到别处一律拒绝(防 SSRF)。
sameHost := *client
sameHost.CheckRedirect = func(req *http.Request, via []*http.Request) error {
if req.URL.Scheme != base.Scheme || req.URL.Host != base.Host {
return newGiteaError(KindRedirect, 0, "版本记录:拒绝重定向到其它主机", nil)
}
return nil
}
sleep := config.Sleep
if sleep == nil {
sleep = time.Sleep
}
linkOrigin := strings.TrimRight(strings.TrimSpace(config.LinkOrigin), "/")
if linkOrigin == "" {
linkOrigin = strings.TrimRight(base.String(), "/")
} else if parsed, perr := url.Parse(linkOrigin); perr != nil || parsed.Host == "" ||
(parsed.Scheme != "http" && parsed.Scheme != "https") {
return nil, fmt.Errorf("版本记录:链接 origin %q 非法(必须是 http(s) 绝对地址)", config.LinkOrigin)
}
return &GiteaClient{baseURL: base, linkOrigin: linkOrigin, repo: repo, client: &sameHost,
maxBytes: maxBytes, maxRetries: retries, sleep: sleep, pageSize: pageSize}, nil
}
// PageSize 是抓取页大小(外层据此做完整性对账)。
func (c *GiteaClient) PageSize() int { return c.pageSize }
// CommitURLBase 给记录页拼提交链接用(**给人看的** origin + 固定仓库,不接受外部传入)。
// 抓取走内网、链接走公网 —— 两者分开,页面上的链接才点得开。
func (c *GiteaClient) CommitURLBase() string {
return c.linkOrigin + "/" + c.repo + giteaCommitURLSuffix
}
// TagURLBase 给记录页拼 tag 链接用(`<link origin>/<repo>/src/tag/`)。
func (c *GiteaClient) TagURLBase() string {
return c.linkOrigin + "/" + c.repo + "/src/tag/"
}
func (c *GiteaClient) apiURL(path string, query url.Values) string {
target := *c.baseURL
target.Path = strings.TrimRight(c.baseURL.Path, "/") + "/api/v1/repos/" + c.repo + path
target.RawQuery = query.Encode()
return target.String()
}
// get 发一次匿名 GET(**不设 Authorization 头**),带超时、响应上限与退避重试。
func (c *GiteaClient) get(ctx context.Context, rawURL string) ([]byte, http.Header, error) {
var lastErr error
for attempt := 0; attempt <= c.maxRetries; attempt++ {
if attempt > 0 {
c.sleep(time.Duration(attempt) * 500 * time.Millisecond)
}
request, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
if err != nil {
return nil, nil, newGiteaError(KindParse, 0, "版本记录:构造请求失败", err)
}
request.Header.Set("Accept", "application/json")
response, err := c.client.Do(request)
if err != nil {
lastErr = newGiteaError(KindUnreachable, 0, "版本记录:Gitea 不可达", err)
continue
}
body, readErr := io.ReadAll(io.LimitReader(response.Body, c.maxBytes+1))
closeErr := response.Body.Close()
if readErr != nil {
lastErr = newGiteaError(KindUnreachable, 0, "版本记录:读取响应失败", readErr)
continue
}
if closeErr != nil {
lastErr = newGiteaError(KindUnreachable, 0, "版本记录:关闭响应失败", closeErr)
continue
}
if int64(len(body)) > c.maxBytes {
return nil, nil, newGiteaError(KindTooLarge, response.StatusCode,
fmt.Sprintf("版本记录:响应超过 %d 字节上限(已丢弃)", c.maxBytes), nil)
}
switch {
case response.StatusCode == http.StatusOK:
return body, response.Header, nil
case response.StatusCode == http.StatusNotFound:
return nil, response.Header, errGiteaNotFound
case response.StatusCode == http.StatusTooManyRequests || response.StatusCode >= 500:
lastErr = newGiteaError(KindStatus, response.StatusCode, "版本记录:Gitea 返回可重试错误", nil)
continue
default:
return nil, response.Header, newGiteaError(KindStatus, response.StatusCode, "版本记录:Gitea 返回错误", nil)
}
}
if lastErr == nil {
lastErr = newGiteaError(KindUnreachable, 0, "版本记录:Gitea 请求失败", nil)
}
return nil, nil, lastErr
}
var errGiteaNotFound = newGiteaError(KindNotFound, http.StatusNotFound, "版本记录:Gitea 上没有该对象", nil)
// ListCommits 读一页提交;同时返回 X-Total-Count(用于完整性对账,不做假 total)。
func (c *GiteaClient) ListCommits(ctx context.Context, page, limit int) ([]RawCommit, int, error) {
return c.ListCommitsAtRef(ctx, "main", page, limit)
}
func (c *GiteaClient) ListCommitsAtRef(ctx context.Context, ref string, page, limit int) ([]RawCommit, int, error) {
if ref != "main" && !fullSHA.MatchString(ref) {
return nil, 0, newGiteaError(KindParse, 0, "版本记录:只接受 main 或完整提交 SHA", nil)
}
if limit <= 0 || limit > giteaDefaultPageSize {
limit = giteaDefaultPageSize
}
query := url.Values{}
query.Set("limit", fmt.Sprintf("%d", limit))
query.Set("page", fmt.Sprintf("%d", page))
query.Set("stat", "false")
query.Set("verification", "false")
query.Set("sha", ref)
body, header, err := c.get(ctx, c.apiURL("/commits", query))
if err != nil {
return nil, 0, err
}
var payload []struct {
SHA string `json:"sha"`
Parents []struct {
SHA string `json:"sha"`
} `json:"parents"`
Created string `json:"created"`
Commit struct {
Message string `json:"message"`
Author struct {
Name string `json:"name"`
Date string `json:"date"`
} `json:"author"`
Committer struct {
Name string `json:"name"`
Date string `json:"date"`
} `json:"committer"`
} `json:"commit"`
}
if err := json.Unmarshal(body, &payload); err != nil {
return nil, 0, newGiteaError(KindParse, 0, "版本记录:提交响应无法解析", err)
}
total := 0
if raw := header.Get("X-Total-Count"); raw != "" {
if _, err := fmt.Sscanf(raw, "%d", &total); err != nil {
total = 0
}
}
commits := make([]RawCommit, 0, len(payload))
for _, item := range payload {
if !fullSHA.MatchString(item.SHA) {
continue
}
parents := make([]string, 0, len(item.Parents))
for _, parent := range item.Parents {
parents = append(parents, parent.SHA)
}
subject, body := splitMessage(item.Commit.Message)
when := parseGiteaTime(item.Commit.Committer.Date)
if when.IsZero() {
when = parseGiteaTime(item.Commit.Author.Date)
}
if when.IsZero() {
when = parseGiteaTime(item.Created)
}
author := item.Commit.Author.Name
if author == "" {
author = item.Commit.Committer.Name
}
commits = append(commits, RawCommit{SHA: item.SHA, Parents: parents, CommittedAt: when,
AuthorDisplay: author, Subject: subject, Body: body})
}
return commits, total, nil
}
// BranchHeadSHA 读分支 HEAD 的完整 SHA(同步记录里的 source_head_sha 用它)。
func (c *GiteaClient) BranchHeadSHA(ctx context.Context, branch string) (string, error) {
if strings.ContainsAny(branch, " /?#") || branch == "" {
return "", newGiteaError(KindParse, 0, "版本记录:分支名非法", nil)
}
body, _, err := c.get(ctx, c.apiURL("/branches/"+branch, url.Values{}))
if err != nil {
return "", err
}
var payload struct {
Commit struct {
ID string `json:"id"`
} `json:"commit"`
}
if err := json.Unmarshal(body, &payload); err != nil {
return "", newGiteaError(KindParse, 0, "版本记录:分支响应无法解析", err)
}
if !fullSHA.MatchString(payload.Commit.ID) {
return "", newGiteaError(KindParse, 0, "版本记录:分支 HEAD 不是完整 SHA", nil)
}
return payload.Commit.ID, nil
}
// ListTags 读全部 tag,并逐个核验它是不是**注释 tag** 以及它指向哪个提交。
// 轻量 tag(object.type == "commit")不会被当作正式版本的证据。
func (c *GiteaClient) ListTags(ctx context.Context) ([]RawTag, error) {
type ref struct {
Ref string `json:"ref"`
Object struct {
Type string `json:"type"`
SHA string `json:"sha"`
} `json:"object"`
}
refs := make([]ref, 0)
for page := 1; page <= 40; page++ {
query := url.Values{}
query.Set("limit", "50")
query.Set("page", fmt.Sprintf("%d", page))
body, _, err := c.get(ctx, c.apiURL("/git/refs/tags", query))
if err != nil {
return nil, err
}
var pageRefs []ref
if err := json.Unmarshal(body, &pageRefs); err != nil {
return nil, newGiteaError(KindParse, 0, "版本记录:tag 列表无法解析", err)
}
refs = append(refs, pageRefs...)
// 短页 = 最后一页(也防住"服务端忽略 page 参数"导致的死循环)
if len(pageRefs) < 50 {
break
}
}
tags := make([]RawTag, 0, len(refs))
for _, item := range refs {
name := strings.TrimPrefix(item.Ref, "refs/tags/")
if name == "" {
continue
}
tag := RawTag{Name: name, TargetSHA: item.Object.SHA}
if item.Object.Type == "tag" {
tag.Annotated = true
tag.TagSHA = item.Object.SHA
// 注释 tag:解引用到真正的提交(tag 对象里的 object.sha)
body, _, err := c.get(ctx, c.apiURL("/git/tags/"+item.Object.SHA, url.Values{}))
if err != nil {
return nil, err
}
var annotated struct {
Message string `json:"message"`
Object struct {
SHA string `json:"sha"`
} `json:"object"`
}
if err := json.Unmarshal(body, &annotated); err != nil {
return nil, newGiteaError(KindParse, 0, "版本记录:注释 tag 无法解析", err)
}
if !fullSHA.MatchString(annotated.Object.SHA) {
continue
}
tag.TargetSHA = annotated.Object.SHA
tag.Message = annotated.Message
}
tags = append(tags, tag)
}
return tags, nil
}
// ReadFile 读某个提交内的文件(用于取该提交的 CHANGELOG.md)。
func (c *GiteaClient) ReadFile(ctx context.Context, sha, path string) (string, error) {
if !fullSHA.MatchString(sha) {
return "", newGiteaError(KindParse, 0, "版本记录:提交必须是完整 40 位 SHA", nil)
}
if strings.Contains(path, "..") || strings.HasPrefix(path, "/") {
return "", newGiteaError(KindParse, 0, "版本记录:文件路径非法", nil)
}
body, _, err := c.get(ctx, c.apiURL("/raw/"+path, url.Values{"ref": []string{sha}}))
if err != nil {
return "", err
}
return string(body), nil
}