[API] generalize list header (go-gitea#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

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

models/issue_milestone_test.go

@@ -50,7 +50,7 @@ func TestGetMilestonesByRepoID(t *testing.T) {
 	assert.NoError(t, PrepareTestDatabase())
 	test := func(repoID int64, state api.StateType) {
 		repo := AssertExistsAndLoadBean(t, &Repository{ID: repoID}).(*Repository)
-		milestones, err := GetMilestones(GetMilestonesOption{
+		milestones, _, err := GetMilestones(GetMilestonesOption{
 			RepoID: repo.ID,
 			State:  state,
 		})
@@ -87,7 +87,7 @@ func TestGetMilestonesByRepoID(t *testing.T) {
 	test(3, api.StateClosed)
 	test(3, api.StateAll)
 
-	milestones, err := GetMilestones(GetMilestonesOption{
+	milestones, _, err := GetMilestones(GetMilestonesOption{
 		RepoID: NonexistentID,
 		State:  api.StateOpen,
 	})
@@ -100,7 +100,7 @@ func TestGetMilestones(t *testing.T) {
 	repo := AssertExistsAndLoadBean(t, &Repository{ID: 1}).(*Repository)
 	test := func(sortType string, sortCond func(*Milestone) int) {
 		for _, page := range []int{0, 1} {
-			milestones, err := GetMilestones(GetMilestonesOption{
+			milestones, _, err := GetMilestones(GetMilestonesOption{
 				ListOptions: ListOptions{
 					Page:     page,
 					PageSize: setting.UI.IssuePagingNum,
@@ -117,7 +117,7 @@ func TestGetMilestones(t *testing.T) {
 			}
 			assert.True(t, sort.IntsAreSorted(values))
 
-			milestones, err = GetMilestones(GetMilestonesOption{
+			milestones, _, err = GetMilestones(GetMilestonesOption{
 				ListOptions: ListOptions{
 					Page:     page,
 					PageSize: setting.UI.IssuePagingNum,

models/issue_stopwatch.go

@@ -55,6 +55,11 @@ func GetUserStopwatches(userID int64, listOptions ListOptions) ([]*Stopwatch, er
 	return sws, nil
 }
 
+// CountUserStopwatches return count of all stopwatches of a user
+func CountUserStopwatches(userID int64) (int64, error) {
+	return x.Where("user_id = ?", userID).Count(&Stopwatch{})
+}
+
 // StopwatchExists returns true if the stopwatch exists
 func StopwatchExists(userID, issueID int64) bool {
 	_, exists, _ := getStopwatch(x, userID, issueID)

models/issue_tracked_time.go

@@ -79,8 +79,8 @@ type FindTrackedTimesOptions struct {
 	CreatedBeforeUnix int64
 }
 
-// ToCond will convert each condition into a xorm-Cond
-func (opts *FindTrackedTimesOptions) ToCond() builder.Cond {
+// toCond will convert each condition into a xorm-Cond
+func (opts *FindTrackedTimesOptions) toCond() builder.Cond {
 	cond := builder.NewCond().And(builder.Eq{"tracked_time.deleted": false})
 	if opts.IssueID != 0 {
 		cond = cond.And(builder.Eq{"issue_id": opts.IssueID})
@@ -103,14 +103,14 @@ func (opts *FindTrackedTimesOptions) ToCond() builder.Cond {
 	return cond
 }
 
-// ToSession will convert the given options to a xorm Session by using the conditions from ToCond and joining with issue table if required
-func (opts *FindTrackedTimesOptions) ToSession(e Engine) Engine {
+// toSession will convert the given options to a xorm Session by using the conditions from toCond and joining with issue table if required
+func (opts *FindTrackedTimesOptions) toSession(e Engine) Engine {
 	sess := e
 	if opts.RepositoryID > 0 || opts.MilestoneID > 0 {
 		sess = e.Join("INNER", "issue", "issue.id = tracked_time.issue_id")
 	}
 
-	sess = sess.Where(opts.ToCond())
+	sess = sess.Where(opts.toCond())
 
 	if opts.Page != 0 {
 		sess = opts.setEnginePagination(sess)
@@ -119,18 +119,27 @@ func (opts *FindTrackedTimesOptions) ToSession(e Engine) Engine {
 	return sess
 }
 
-func getTrackedTimes(e Engine, options FindTrackedTimesOptions) (trackedTimes TrackedTimeList, err error) {
-	err = options.ToSession(e).Find(&trackedTimes)
+func getTrackedTimes(e Engine, options *FindTrackedTimesOptions) (trackedTimes TrackedTimeList, err error) {
+	err = options.toSession(e).Find(&trackedTimes)
 	return
 }
 
 // GetTrackedTimes returns all tracked times that fit to the given options.
-func GetTrackedTimes(opts FindTrackedTimesOptions) (TrackedTimeList, error) {
+func GetTrackedTimes(opts *FindTrackedTimesOptions) (TrackedTimeList, error) {
 	return getTrackedTimes(x, opts)
 }
 
+// CountTrackedTimes returns count of tracked times that fit to the given options.
+func CountTrackedTimes(opts *FindTrackedTimesOptions) (int64, error) {
+	sess := x.Where(opts.toCond())
+	if opts.RepositoryID > 0 || opts.MilestoneID > 0 {
+		sess = sess.Join("INNER", "issue", "issue.id = tracked_time.issue_id")
+	}
+	return sess.Count(&TrackedTime{})
+}
+
 func getTrackedSeconds(e Engine, opts FindTrackedTimesOptions) (trackedSeconds int64, err error) {
-	return opts.ToSession(e).SumInt(&TrackedTime{}, "time")
+	return opts.toSession(e).SumInt(&TrackedTime{}, "time")
 }
 
 // GetTrackedSeconds return sum of seconds
@@ -188,7 +197,7 @@ func addTime(e Engine, user *User, issue *Issue, amount int64, created time.Time
 }
 
 // TotalTimes returns the spent time for each user by an issue
-func TotalTimes(options FindTrackedTimesOptions) (map[*User]string, error) {
+func TotalTimes(options *FindTrackedTimesOptions) (map[*User]string, error) {
 	trackedTimes, err := GetTrackedTimes(options)
 	if err != nil {
 		return nil, err
@@ -288,7 +297,7 @@ func deleteTimes(e Engine, opts FindTrackedTimesOptions) (removedTime int64, err
 		return
 	}
 
-	_, err = opts.ToSession(e).Table("tracked_time").Cols("deleted").Update(&TrackedTime{Deleted: true})
+	_, err = opts.toSession(e).Table("tracked_time").Cols("deleted").Update(&TrackedTime{Deleted: true})
 	return
 }