hybrid pagination

2026-05-17 17:21:36 +03:30
parent 42d0a47226
commit 6dac5b482a
39 changed files with 696 additions and 386 deletions
@@ -0,0 +1,105 @@
+package response
+
+import (
+	"errors"
+	"fmt"
+	"strconv"
+
+	"github.com/labstack/echo/v4"
+)
+
+const (
+	// DefaultListLimit is the default page size for admin list endpoints.
+	DefaultListLimit = 10
+	// MaxListLimit is the maximum allowed page size.
+	MaxListLimit = 100
+)
+
+var (
+	// ErrInvalidPagination is returned when pagination query parameters are invalid.
+	ErrInvalidPagination = errors.New("invalid pagination parameters")
+	// ErrPaginationConflict is returned when cursor and offset are both supplied.
+	ErrPaginationConflict = errors.New("cursor and offset pagination cannot be used together")
+)
+
+// NewPagination parses and validates hybrid pagination query parameters from the request.
+func NewPagination(c echo.Context) (*Pagination, error) {
+	limit := DefaultListLimit
+	if limitStr := c.QueryParam("limit"); limitStr != "" {
+		parsed, err := strconv.Atoi(limitStr)
+		if err != nil {
+			return nil, fmt.Errorf("%w: limit must be an integer", ErrInvalidPagination)
+		}
+		limit = parsed
+	}
+	if limit < 1 || limit > MaxListLimit {
+		return nil, fmt.Errorf("%w: limit must be between 1 and %d", ErrInvalidPagination, MaxListLimit)
+	}
+
+	cursor := c.QueryParam("cursor")
+	offsetParam := c.QueryParam("offset")
+	if cursor != "" && offsetParam != "" {
+		return nil, ErrPaginationConflict
+	}
+
+	offset := 0
+	if offsetParam != "" {
+		parsed, err := strconv.Atoi(offsetParam)
+		if err != nil {
+			return nil, fmt.Errorf("%w: offset must be an integer", ErrInvalidPagination)
+		}
+		if parsed < 0 {
+			return nil, fmt.Errorf("%w: offset cannot be negative", ErrInvalidPagination)
+		}
+		offset = parsed
+	}
+
+	sortBy := c.QueryParam("sort_by")
+	if sortBy == "" {
+		sortBy = "created_at"
+	}
+
+	sortOrder := c.QueryParam("sort_order")
+	if sortOrder == "" {
+		sortOrder = "desc"
+	}
+
+	return &Pagination{
+		Limit:     limit,
+		Offset:    offset,
+		Cursor:    cursor,
+		SortBy:    sortBy,
+		SortOrder: sortOrder,
+	}, nil
+}
+
+// ListMeta builds pagination metadata for a list page.
+// pageOffset is the zero-based index of the first item in this page (from offset or cursor).
+func (p *Pagination) ListMeta(total int64, nextCursor string, hasMore bool, pageOffset int) *Meta {
+	meta := &Meta{
+		Limit:   p.Limit,
+		Offset:  pageOffset,
+		HasMore: hasMore,
+	}
+	if hasMore && nextCursor != "" {
+		meta.NextCursor = nextCursor
+	}
+	if total >= 0 {
+		meta.Total = int(total)
+		if p.Limit > 0 {
+			meta.Page = pageOffset/p.Limit + 1
+			meta.Pages = int((total + int64(p.Limit) - 1) / int64(p.Limit))
+		}
+	}
+	return meta
+}
+
+// ListMetaFromPage builds metadata from a paginated repository result.
+func (p *Pagination) ListMetaFromPage(total int64, nextCursor string, hasMore bool, pageOffset int) *Meta {
+	return p.ListMeta(total, nextCursor, hasMore, pageOffset)
+}
+
+// IsPaginationError reports whether err is a client-facing pagination error.
+func IsPaginationError(err error) bool {
+	return errors.Is(err, ErrInvalidPagination) || errors.Is(err, ErrPaginationConflict)
+}
@@ -0,0 +1,47 @@
+package response
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/labstack/echo/v4"
+)
+
+func TestNewPaginationDefaults(t *testing.T) {
+	e := echo.New()
+	req := httptest.NewRequest(http.MethodGet, "/?limit=10&offset=0&sort_by=created_at&sort_order=desc", nil)
+	rec := httptest.NewRecorder()
+	c := e.NewContext(req, rec)
+
+	p, err := NewPagination(c)
+	if err != nil {
+		t.Fatalf("NewPagination: %v", err)
+	}
+	if p.Limit != 10 || p.Offset != 0 || p.Cursor != "" {
+		t.Fatalf("unexpected pagination: %+v", p)
+	}
+}
+
+func TestNewPaginationCursorConflict(t *testing.T) {
+	e := echo.New()
+	req := httptest.NewRequest(http.MethodGet, "/?limit=10&offset=5&cursor=abc", nil)
+	rec := httptest.NewRecorder()
+	c := e.NewContext(req, rec)
+
+	_, err := NewPagination(c)
+	if !IsPaginationError(err) {
+		t.Fatalf("expected pagination conflict, got %v", err)
+	}
+}
+
+func TestListMetaOmitsNextCursorOnLastPage(t *testing.T) {
+	p := &Pagination{Limit: 10, Offset: 0}
+	meta := p.ListMeta(15, "should-not-appear", false, 0)
+	if meta.HasMore || meta.NextCursor != "" {
+		t.Fatalf("expected no next cursor on last page: %+v", meta)
+	}
+	if meta.Page != 1 || meta.Pages != 2 || meta.Total != 15 {
+		t.Fatalf("unexpected page meta: %+v", meta)
+	}
+}
@@ -1,11 +1,13 @@
 package response

 import (
+	"errors"
 	"net/http"
-	"strconv"

 	"github.com/asaskevich/govalidator"
 	"github.com/labstack/echo/v4"
+
+	orm "tm/pkg/mongo"
 )

 // APIResponse represents a standard API response structure
@@ -26,17 +28,17 @@ type APIError struct {

 // Meta represents metadata for paginated responses
 type Meta struct {
-	Total      int    `json:"total,omitempty"`
+	Total      int    `json:"total"`
 	Limit      int    `json:"limit"`
 	Offset     int    `json:"offset"`
-	Page       int    `json:"page,omitempty"`
-	Pages      int    `json:"pages,omitempty"`
+	Page       int    `json:"page"`
+	Pages      int    `json:"pages"`
+	HasMore    bool   `json:"has_more"`
 	NextCursor string `json:"next_cursor,omitempty"`
-	HasMore    bool   `json:"has_more,omitempty"`
 }

 type Pagination struct {
-	Limit     int    `query:"limit" valid:"optional,range(1|100)" default:"20"`
+	Limit     int    `query:"limit" valid:"optional,range(1|100)" default:"10"`
 	Offset    int    `query:"offset" valid:"optional,range(0|1000000)" default:"0"`
 	Cursor    string `query:"cursor" valid:"optional"`
 	SortBy    string `query:"sort_by" valid:"optional"`
@@ -192,59 +194,16 @@ func Parse[T any](c echo.Context) (*T, error) {
 	return &form, nil
 }

-func NewPagination(c echo.Context) *Pagination {
-	limit, err := strconv.Atoi(c.QueryParam("limit"))
-	if err != nil {
-		limit = 20
-	}
-
-	offset, err := strconv.Atoi(c.QueryParam("offset"))
-	if err != nil {
-		offset = 0
-	}
-
-	sortBy := c.QueryParam("sort_by")
-	if sortBy == "" {
-		sortBy = "created_at"
-	}
-
-	sortOrder := c.QueryParam("sort_order")
-	if sortOrder == "" {
-		sortOrder = "desc"
-	}
-
-	cursor := c.QueryParam("cursor")
-
-	return &Pagination{
-		Limit:     limit,
-		Offset:    offset,
-		Cursor:    cursor,
-		SortBy:    sortBy,
-		SortOrder: sortOrder,
+// PaginationBadRequest writes a 400 response for invalid list pagination parameters.
+func PaginationBadRequest(c echo.Context, err error) error {
+	msg := "Invalid pagination parameters"
+	if errors.Is(err, orm.ErrInvalidCursor) {
+		msg = "Invalid pagination cursor"
 	}
+	return BadRequest(c, msg, err.Error())
 }

-// Response calculates offset-based pagination metadata.
-func (p *Pagination) Response(total int64) *Meta {
-	return p.ListMeta(total, "", false)
-}
-
-// ListMeta builds pagination metadata for list endpoints (offset and/or cursor).
-// When total is negative, total/page/pages are omitted (count was skipped).
-func (p *Pagination) ListMeta(total int64, nextCursor string, hasMore bool) *Meta {
-	meta := &Meta{
-		Limit:      p.Limit,
-		Offset:     p.Offset,
-		NextCursor: nextCursor,
-		HasMore:    hasMore,
-	}
-	if total >= 0 {
-		pages := (total + int64(p.Limit) - 1) / int64(p.Limit)
-		meta.Total = int(total)
-		if p.Limit > 0 {
-			meta.Page = p.Offset/p.Limit + 1
-		}
-		meta.Pages = int(pages)
-	}
-	return meta
+// IsListPaginationError reports client-facing pagination errors from list queries.
+func IsListPaginationError(err error) bool {
+	return IsPaginationError(err) || errors.Is(err, orm.ErrInvalidCursor) || errors.Is(err, orm.ErrInvalidPagination)
 }