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 链接用(`//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 }