[API] generalize list header (#16551)

* Add info about list endpoints to CONTRIBUTING.md

* Let all list endpoints return X-Total-Count header 

* Add TODOs for GetCombinedCommitStatusByRef

* Fix models/issue_stopwatch.go

* Rrefactor models.ListDeployKeys

* Introduce helper func and use them for SetLinkHeader related func

Author: 6543

CONTRIBUTING.md

@@ -207,6 +207,10 @@ In general, HTTP methods are chosen as follows:
 
 An endpoint which changes/edits an object expects all fields to be optional (except ones to identify the object, which are required).
 
+### Endpoints returning lists should
+ * support pagination (`page` & `limit` options in query)
+ * set `X-Total-Count` header via **SetTotalCountHeader** ([example](https://github.com/go-gitea/gitea/blob/7aae98cc5d4113f1e9918b7ee7dd09f67c189e3e/routers/api/v1/repo/issue.go#L444))
+
 
 ## Developer Certificate of Origin (DCO)
 
@@ -231,8 +235,8 @@ on, finishing, and issuing releases. The overall goal is to make a
 minor release every three or four months, which breaks down into two or three months of
 general development followed by one month of testing and polishing
 known as the release freeze. All the feature pull requests should be
-merged before feature freeze. And, during the frozen period, a corresponding 
-release branch is open for fixes backported from main branch. Release candidates 
+merged before feature freeze. And, during the frozen period, a corresponding
+release branch is open for fixes backported from main branch. Release candidates
 are made during this period for user testing to
 obtain a final version that is maintained in this branch. A release is
 maintained by issuing patch releases to only correct critical problems

integrations/api_issue_tracked_time_test.go

@@ -30,7 +30,7 @@ func TestAPIGetTrackedTimes(t *testing.T) {
 	resp := session.MakeRequest(t, req, http.StatusOK)
 	var apiTimes api.TrackedTimeList
 	DecodeJSON(t, resp, &apiTimes)
-	expect, err := models.GetTrackedTimes(models.FindTrackedTimesOptions{IssueID: issue2.ID})
+	expect, err := models.GetTrackedTimes(&models.FindTrackedTimesOptions{IssueID: issue2.ID})
 	assert.NoError(t, err)
 	assert.Len(t, apiTimes, 3)
 

integrations/api_repo_topic_test.go

@@ -7,6 +7,7 @@ package integrations
 import (
 	"fmt"
 	"net/http"
+	"net/url"
 	"testing"
 
 	"code.gitea.io/gitea/models"
@@ -15,6 +16,38 @@ import (
 	"github.com/stretchr/testify/assert"
 )
 
+func TestAPITopicSearch(t *testing.T) {
+	defer prepareTestEnv(t)()
+	searchURL, _ := url.Parse("/api/v1/topics/search")
+	var topics struct {
+		TopicNames []*api.TopicResponse `json:"topics"`
+	}
+
+	query := url.Values{"page": []string{"1"}, "limit": []string{"4"}}
+
+	searchURL.RawQuery = query.Encode()
+	res := MakeRequest(t, NewRequest(t, "GET", searchURL.String()), http.StatusOK)
+	DecodeJSON(t, res, &topics)
+	assert.Len(t, topics.TopicNames, 4)
+	assert.EqualValues(t, "6", res.Header().Get("x-total-count"))
+
+	query.Add("q", "topic")
+	searchURL.RawQuery = query.Encode()
+	res = MakeRequest(t, NewRequest(t, "GET", searchURL.String()), http.StatusOK)
+	DecodeJSON(t, res, &topics)
+	assert.Len(t, topics.TopicNames, 2)
+
+	query.Set("q", "database")
+	searchURL.RawQuery = query.Encode()
+	res = MakeRequest(t, NewRequest(t, "GET", searchURL.String()), http.StatusOK)
+	DecodeJSON(t, res, &topics)
+	if assert.Len(t, topics.TopicNames, 1) {
+		assert.EqualValues(t, 2, topics.TopicNames[0].ID)
+		assert.EqualValues(t, "database", topics.TopicNames[0].Name)
+		assert.EqualValues(t, 1, topics.TopicNames[0].RepoCount)
+	}
+}
+
 func TestAPIRepoTopic(t *testing.T) {
 	defer prepareTestEnv(t)()
 	user2 := models.AssertExistsAndLoadBean(t, &models.User{ID: 2}).(*models.User) // owner of repo2

models/access.go

@@ -246,7 +246,7 @@ func (repo *Repository) recalculateTeamAccesses(e Engine, ignTeamID int64) (err
 		return fmt.Errorf("refreshCollaboratorAccesses: %v", err)
 	}
 
-	if err = repo.Owner.getTeams(e); err != nil {
+	if err = repo.Owner.loadTeams(e); err != nil {
 		return err
 	}
 

models/commit_status.go

@@ -159,7 +159,7 @@ func getLatestCommitStatus(e Engine, repoID int64, sha string, listOptions ListO
 	if len(ids) == 0 {
 		return statuses, nil
 	}
-	return statuses, x.In("id", ids).Find(&statuses)
+	return statuses, e.In("id", ids).Find(&statuses)
 }
 
 // FindRepoRecentCommitStatusContexts returns repository's recent commit status contexts

models/gpg_key.go

@@ -71,6 +71,11 @@ func listGPGKeys(e Engine, uid int64, listOptions ListOptions) ([]*GPGKey, error
 	return keys, sess.Find(&keys)
 }
 
+// CountUserGPGKeys return number of gpg keys a user own
+func CountUserGPGKeys(userID int64) (int64, error) {
+	return x.Where("owner_id=? AND primary_key_id=''", userID).Count(&GPGKey{})
+}
+
 // GetGPGKeyByID returns public key by given ID.
 func GetGPGKeyByID(keyID int64) (*GPGKey, error) {
 	key := new(GPGKey)

models/issue.go

@@ -89,7 +89,7 @@ func init() {
 
 func (issue *Issue) loadTotalTimes(e Engine) (err error) {
 	opts := FindTrackedTimesOptions{IssueID: issue.ID}
-	issue.TotalTrackedTime, err = opts.ToSession(e).SumInt(&TrackedTime{}, "time")
+	issue.TotalTrackedTime, err = opts.toSession(e).SumInt(&TrackedTime{}, "time")
 	if err != nil {
 		return err
 	}
@@ -214,7 +214,7 @@ func (issue *Issue) loadCommentsByType(e Engine, tp CommentType) (err error) {
 	if issue.Comments != nil {
 		return nil
 	}
-	issue.Comments, err = findComments(e, FindCommentsOptions{
+	issue.Comments, err = findComments(e, &FindCommentsOptions{
 		IssueID: issue.ID,
 		Type:    tp,
 	})

models/issue_comment.go

@@ -999,7 +999,7 @@ func (opts *FindCommentsOptions) toConds() builder.Cond {
 	return cond
 }
 
-func findComments(e Engine, opts FindCommentsOptions) ([]*Comment, error) {
+func findComments(e Engine, opts *FindCommentsOptions) ([]*Comment, error) {
 	comments := make([]*Comment, 0, 10)
 	sess := e.Where(opts.toConds())
 	if opts.RepoID > 0 {
@@ -1019,10 +1019,19 @@ func findComments(e Engine, opts FindCommentsOptions) ([]*Comment, error) {
 }
 
 // FindComments returns all comments according options
-func FindComments(opts FindCommentsOptions) ([]*Comment, error) {
+func FindComments(opts *FindCommentsOptions) ([]*Comment, error) {
 	return findComments(x, opts)
 }
 
+// CountComments count all comments according options by ignoring pagination
+func CountComments(opts *FindCommentsOptions) (int64, error) {
+	sess := x.Where(opts.toConds())
+	if opts.RepoID > 0 {
+		sess.Join("INNER", "issue", "issue.id = comment.issue_id")
+	}
+	return sess.Count(&Comment{})
+}
+
 // UpdateComment updates information of comment.
 func UpdateComment(c *Comment, doer *User) error {
 	sess := x.NewSession()

models/issue_label.go

@@ -444,6 +444,11 @@ func GetLabelsByRepoID(repoID int64, sortType string, listOptions ListOptions) (
 	return getLabelsByRepoID(x, repoID, sortType, listOptions)
 }
 
+// CountLabelsByRepoID count number of all labels that belong to given repository by ID.
+func CountLabelsByRepoID(repoID int64) (int64, error) {
+	return x.Where("repo_id = ?", repoID).Count(&Label{})
+}
+
 // ________
 // \_____  \_______  ____
 //  /   |   \_  __ \/ ___\
@@ -556,6 +561,11 @@ func GetLabelsByOrgID(orgID int64, sortType string, listOptions ListOptions) ([]
 	return getLabelsByOrgID(x, orgID, sortType, listOptions)
 }
 
+// CountLabelsByOrgID count all labels that belong to given organization by ID.
+func CountLabelsByOrgID(orgID int64) (int64, error) {
+	return x.Where("org_id = ?", orgID).Count(&Label{})
+}
+
 // .___
 // |   | ______ ________ __   ____
 // |   |/  ___//  ___/  |  \_/ __ \

models/issue_milestone.go

@@ -380,24 +380,33 @@ type GetMilestonesOption struct {
 	SortType string
 }
 
-// GetMilestones returns milestones filtered by GetMilestonesOption's
-func GetMilestones(opts GetMilestonesOption) (MilestoneList, error) {
-	sess := x.Where("repo_id = ?", opts.RepoID)
+func (opts GetMilestonesOption) toCond() builder.Cond {
+	cond := builder.NewCond()
+	if opts.RepoID != 0 {
+		cond = cond.And(builder.Eq{"repo_id": opts.RepoID})
+	}
 
 	switch opts.State {
 	case api.StateClosed:
-		sess = sess.And("is_closed = ?", true)
+		cond = cond.And(builder.Eq{"is_closed": true})
 	case api.StateAll:
 		break
 	// api.StateOpen:
 	default:
-		sess = sess.And("is_closed = ?", false)
+		cond = cond.And(builder.Eq{"is_closed": false})
 	}
 
 	if len(opts.Name) != 0 {
-		sess = sess.And(builder.Like{"name", opts.Name})
+		cond = cond.And(builder.Like{"name", opts.Name})
 	}
 
+	return cond
+}
+
+// GetMilestones returns milestones filtered by GetMilestonesOption's
+func GetMilestones(opts GetMilestonesOption) (MilestoneList, int64, error) {
+	sess := x.Where(opts.toCond())
+
 	if opts.Page != 0 {
 		sess = opts.setSessionPagination(sess)
 	}
@@ -420,7 +429,8 @@ func GetMilestones(opts GetMilestonesOption) (MilestoneList, error) {
 	}
 
 	miles := make([]*Milestone, 0, opts.PageSize)
-	return miles, sess.Find(&miles)
+	total, err := sess.FindAndCount(&miles)
+	return miles, total, err
 }
 
 // SearchMilestones search milestones