search

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
  • func WithBaseURL(u string) Option
  • func WithHeaders(h http.Header) Option
  • func WithOrder(o string) Option
  • func WithPerPage(n int) Option
  • func WithSort(s string) 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).

func Repos

func Repos[T any](ctx context.Context, c *http.Client, q string, opts ...Option) iter.Seq2[Result[T], error]

Repos iterates `/search/repositories`.

func Users

func Users[T any](ctx context.Context, c *http.Client, q string, opts ...Option) iter.Seq2[Result[T], error]

Users iterates `/search/users`.

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

func WithBaseURL(u string) Option

WithBaseURL overrides the default GitHub API root. Use for GHES or fixture servers.

func WithHeaders

func WithHeaders(h http.Header) Option

WithHeaders sets the request headers (cloned per page by the underlying pages.Pages iterator).

func WithOrder

func WithOrder(o string) Option

WithOrder sets the sort order ("asc" or "desc").

func WithPerPage

func WithPerPage(n int) Option

WithPerPage sets the per-page count. Range [1, 100]; values above 100 are clamped. Zero or negative values are ignored (GitHub default applies).

func WithSort

func WithSort(s string) Option

WithSort sets the sort field (endpoint-specific; e.g. "updated" for issues, "stars" for repositories).

type Result

type Result[T any] struct {
	Item              T
	TotalCount        int
	IncompleteResults bool
}

Result wraps each yielded item with the envelope's TotalCount and IncompleteResults flags. IncompleteResults is set per-page when GitHub's server timed out for that page; consumers OR across pages.