Documentation
¶
Overview ¶
Package search iterates GitHub's /search/* envelope endpoints (`{total_count, incomplete_results, items[]}`). The iterator reuses pages.Pages for Link-header walking, so the configured transport stack (RateLimit, Throttle, Retry, oauth2, ETag) applies per page.
Each Result[T] carries the per-page TotalCount and IncompleteResults flag alongside the typed Item. ErrResultCapHit signals GitHub's 1000-result hard cap (a 422 after page 10).
Four endpoints are exposed: Issues, Code, Repos, Users. They share one private iteration core; the typed parameter T lets callers pick the decode target (e.g. *github.Issue, *github.Repository) without pulling go-github into ghkit.
Per-resource rate limit: /search/* uses a separate `search` budget; /search/code uses `code_search`. gofri's ratelimit handles the routing transparently (no search-specific ghkit option needed).
Options use the functional pattern (WithBaseURL, WithPerPage, WithSort, WithOrder, WithHeaders) for parity with the rest of ghkit. Each call materializes its own config; sharing options across goroutines is safe by construction.
Body lifecycle: the iterator owns each per-page response body and closes it via defer in decodeEnvelope. Non-2xx error bodies are read (capped at 4 KiB on 422, 1 KiB otherwise) and the remainder drained so connections return cleanly to the keep-alive pool.
Error messages on 4xx/422 echo bounded upstream bytes; operators piping errors into structured logs should escape if downstream handlers are sensitive to control characters.
Index ¶
- Constants
- Variables
- func Code[T any](ctx context.Context, c *http.Client, q string, opts ...Option) iter.Seq2[Result[T], error]
- func Issues[T any](ctx context.Context, c *http.Client, q string, opts ...Option) iter.Seq2[Result[T], error]
- func Repos[T any](ctx context.Context, c *http.Client, q string, opts ...Option) iter.Seq2[Result[T], error]
- func Users[T any](ctx context.Context, c *http.Client, q string, opts ...Option) iter.Seq2[Result[T], error]
- type Option
- type Result
Constants ¶
const DefaultBaseURL = "https://api.github.com"
DefaultBaseURL is the GitHub API root used when WithBaseURL is not supplied. Override via WithBaseURL to target GHES or a fixture server.
Variables ¶
var ErrResultCapHit = errors.New("search: GitHub 1000-result cap reached")
ErrResultCapHit signals that GitHub's 1000-result hard cap was reached. The cap surfaces as 422 with a documented body substring after page 10 (10 * per_page=100 = 1000 items).
Functions ¶
func Code ¶
func Code[T any](ctx context.Context, c *http.Client, q string, opts ...Option) iter.Seq2[Result[T], error]
Code iterates `/search/code`. Has a separate `code_search` rate budget on the gofri side; gofri handles routing transparently.
func Issues ¶
func Issues[T any](ctx context.Context, c *http.Client, q string, opts ...Option) iter.Seq2[Result[T], error]
Issues iterates `/search/issues` (issues + pull requests).
Types ¶
type Option ¶
type Option func(*config)
Option configures a search iterator. Mirrors the functional-options convention used across ghkit (etag, retry, ratelimit, throttle, polling).
func WithBaseURL ¶
WithBaseURL overrides the default GitHub API root. Use for GHES or fixture servers.
func WithHeaders ¶
WithHeaders sets the request headers (cloned per page by the underlying pages.Pages iterator).
func WithPerPage ¶
WithPerPage sets the per-page count. Range [1, 100]; values above 100 are clamped. Zero or negative values are ignored (GitHub default applies).
Source Files