snapshot of https://github.com/ory/kratos.git (master, 2026-09-15; blobs > 131072B omitted)

oryx/pagination/pagepagination/header.go

@@ -0,0 +1,82 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package pagepagination
+
+// Pagination Request Parameters
+//
+// The `Link` HTTP header contains multiple links (`first`, `next`, `last`, `previous`) formatted as:
+// `<https://{project-slug}.projects.oryapis.com/admin/clients?page_size={limit}&page_token={offset}>; rel="{page}"`
+//
+// For details on pagination please head over to the [pagination documentation](https://www.ory.com/docs/ecosystem/api-design#pagination).
+//
+// swagger:model pagePaginationRequestParameters
+type RequestParameters struct {
+	// Legacy Items per Page
+	//
+	// A DEPRECATED alias for `page_size`. Please transition to using `page_size` going forward.
+	//
+	// required: false
+	// in: query
+	// default: 250
+	// min: 1
+	// max: 1000
+	PerPage int `json:"per_page"`
+
+	// Legacy Pagination Page
+	//
+	// A DEPRECATED alias for `page_token`. Please transition to using `page_token` going forward.
+	//
+	// required: false
+	// in: query
+	// default: 1
+	// min: 1
+	Page int `json:"page"`
+
+	// Items per Page
+	//
+	// This is the number of items per page to return. For details on pagination please head over to the
+	// [pagination documentation](https://www.ory.com/docs/ecosystem/api-design#pagination).
+	//
+	// required: false
+	// in: query
+	// default: 250
+	// min: 1
+	// max: 500
+	PageSize int `json:"page_size"`
+
+	// Next Page Token
+	//
+	// The next page token. For details on pagination please head over to the
+	// [pagination documentation](https://www.ory.com/docs/ecosystem/api-design#pagination).
+	//
+	// required: false
+	// in: query
+	PageToken string `json:"page_token"`
+}
+
+// swagger:model pagePaginationResponseHeaders
+type ResponseHeaderAnnotation struct {
+	// The Link HTTP Header
+	//
+	// The `Link` header contains a comma-delimited list of links to the following pages:
+	//
+	// - first: The first page of results.
+	// - next: The next page of results.
+	// - prev: The previous page of results.
+	// - last: The last page of results.
+	//
+	// Pages are omitted if they do not exist. For example, if there is no next page, the `next` link is omitted.
+	//
+	// This header will include the `per_page` and `page` parameters for legacy reasons, but these parameters will eventually be removed.
+	//
+	//	Example: Link: </clients?page_size=5&page_token=0>; rel="first",</clients?page_size=5&page_token=15>; rel="next",</clients?page_size=5&page_token=5>; rel="prev",</clients?page_size=5&page_token=20>; rel="last"
+	Link string `json:"link"`
+
+	// The X-Total-Count HTTP Header
+	//
+	// The `X-Total-Count` header contains the total number of items in the collection.
+	//
+	// Example: 123
+	TotalCount int `json:"x-total-count"`
+}

oryx/pagination/pagepagination/pagination.go

@@ -0,0 +1,79 @@
+// Copyright © 2023 Ory Corp
+// SPDX-License-Identifier: Apache-2.0
+
+package pagepagination
+
+import (
+	"fmt"
+	"net/http"
+	"net/url"
+	"strconv"
+
+	"github.com/ory/x/pagination"
+)
+
+type PagePaginator struct {
+	MaxItems     int
+	DefaultItems int
+}
+
+func (p *PagePaginator) defaults() {
+	if p.MaxItems == 0 {
+		p.MaxItems = 1000
+	}
+
+	if p.DefaultItems == 0 {
+		p.DefaultItems = 250
+	}
+}
+
+// ParsePagination parses limit and page from *http.Request with given limits and defaults.
+func (p *PagePaginator) ParsePagination(r *http.Request) (page, itemsPerPage int) {
+	p.defaults()
+
+	if offsetParam := r.URL.Query().Get("page"); offsetParam == "" {
+		page = 0
+	} else {
+		if offset, err := strconv.ParseInt(offsetParam, 10, 0); err != nil {
+			page = 0
+		} else {
+			page = int(offset)
+		}
+	}
+
+	if limitParam := r.URL.Query().Get("per_page"); limitParam == "" {
+		itemsPerPage = p.DefaultItems
+	} else {
+		if limit, err := strconv.ParseInt(limitParam, 10, 0); err != nil {
+			itemsPerPage = p.DefaultItems
+		} else {
+			itemsPerPage = int(limit)
+		}
+	}
+
+	if itemsPerPage > p.MaxItems {
+		itemsPerPage = p.MaxItems
+	}
+
+	if itemsPerPage < 1 {
+		itemsPerPage = 1
+	}
+
+	if page < 0 {
+		page = 0
+	}
+
+	return
+}
+
+func header(u *url.URL, rel string, limit, offset int64) string {
+	q := u.Query()
+	q.Set("per_page", fmt.Sprintf("%d", limit))
+	q.Set("page", fmt.Sprintf("%d", offset/limit))
+	u.RawQuery = q.Encode()
+	return fmt.Sprintf("<%s>; rel=\"%s\"", u.String(), rel)
+}
+
+func PaginationHeader(w http.ResponseWriter, u *url.URL, total int64, page, itemsPerPage int) {
+	pagination.HeaderWithFormatter(w, u, total, page, itemsPerPage, header)
+}