Documentation
¶
Overview ¶
Package pages walks paginated GitHub REST responses by following the RFC 8288 Link header, exposing the iteration as a Go 1.23 range-over-func iterator.
The iterator runs on a caller-supplied *http.Client, so the configured transport stack (RateLimit, Throttle, Retry, oauth2, ETag) applies per page with no extra wiring. Use ghkit.HTTPClient or any *http.Client the caller already has.
Two entry points:
- Pages: yields *http.Response per page. The caller decodes and closes each body. Use this when the caller wants to handle the response shape directly or is decoding into types other than the element-per-page model.
- As[T]: decodes each page into []T and yields one element at a time. The iterator owns the response body and closes it after decoding, including on caller break or context cancellation.
Errors are surfaced through the iterator's error slot and stop iteration after one yield. ErrInvalidLinkHeader is returned when the response Link header is structurally malformed; a header with no rel="next" is treated as a clean end of pagination, not an error.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidLinkHeader = errors.New("pages: malformed Link header")
ErrInvalidLinkHeader signals a structurally malformed Link header. A clean end of pagination (a Link with no rel="next" entry, or a missing Link altogether) stops iteration silently and is not an error.
Functions ¶
func As ¶
func As[T any]( ctx context.Context, client *http.Client, method, url string, headers http.Header, ) iter.Seq2[T, error]
As decodes each paginated response into elements of type T and yields one element per iteration. The iterator owns the response body and closes it after decoding, including on caller break, on context cancellation, and on a panic from json.Decode. T has no constraint: types from go-github such as *github.Repository decode via the standard reflection path.
A page that decodes to an empty slice is skipped silently; iteration continues to the next page. A decode error stops iteration after yielding (zero, err) once.
func Pages ¶
func Pages( ctx context.Context, client *http.Client, method, url string, headers http.Header, ) iter.Seq2[*http.Response, error]
Pages iterates paginated HTTP responses by following the Link: rel="next" header. The configured *http.Client carries the full transport stack (RateLimit, Throttle, Retry, oauth2, ETag in outermost-to-innermost order), so each page goes through it. The caller drains and closes each response body.
On error (request build, transport, context cancellation, malformed Link header), the iterator yields (nil, err) once and stops. A response without a rel="next" Link is treated as a clean end of pagination, not an error.
The iterator follows whatever absolute URL the server returns in the rel="next" entry, including across hosts. GitHub Enterprise and hostname migration scenarios depend on this; callers concerned about SSRF in untrusted-server environments should validate the URL before looping.
Types ¶
This section is empty.
Source Files