feat: add polling, search, cond sub-packages; harden retry Retry-After parser

Author: pcanilho

CHANGELOG.md

@@ -5,6 +5,116 @@ All notable changes to **go-github-kit** are documented in this file.
 The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-05-02
+
+Adds three consumer-utility sub-packages that ride on top of the
+assembled `*http.Client` and compose with the existing transport
+stack: `polling` (range-over-func iterator over an HTTP endpoint on
+an interval), `search` (envelope iterator for `/search/*` endpoints
+that `pages.As[T]` cannot serve), and `cond` (visible 304 / change-
+vs-unchanged signal building on the etag layer). Hardens `retry`'s
+`Retry-After` parser as part of the same release.
+
+### Fixed
+
+- `retry`: `Retry-After` parser saturates extremely large delta-seconds
+  values (above `math.MaxInt64 / int64(time.Second)`) instead of wrapping
+  int64 nanoseconds. Clamped values route through the existing
+  `ErrRetryAfterExceedsMax` abort path.
+- `retry`: whitespace around `Retry-After` values (`" 5"`, `"5 "`) is now
+  trimmed before parsing.
+
+### Added
+
+- `polling.Poll` and `polling.As[T]`: Go 1.23 range-over-func iterator
+  that re-issues a request on a caller-tunable interval, reusing the
+  supplied `*http.Client` so retry, etag, ratelimit, throttle, and
+  oauth2 apply per attempt. Options: `WithDone` (header/status
+  predicate), `WithDoneT[T]` (typed predicate on the decoded value),
+  `WithDecode[T]` (custom decoder), `WithChangeOnly` (skip yields on
+  cache hit), `WithMaxAttempts`, `WithMaxWallClock`, `WithJitter`
+  (deterministic mid-point), `WithHonorRetryAfter`, `WithLogger`,
+  plus `WithSleepFunc` / `WithNowFunc` test seams. Sentinels
+  `ErrMaxAttemptsExceeded`, `ErrMaxWallClockExceeded` (wraps
+  `context.DeadlineExceeded`), `ErrInvalidInterval`,
+  `ErrInvalidOption`, `ErrPredicatePanic`. Boundary yields surface
+  `(lastResp, sentinel)` so the caller can inspect what triggered
+  the limit.
+- `search.Issues`, `search.Code`, `search.Repos`, `search.Users`:
+  typed iterators over GitHub's `/search/*` envelope endpoints.
+  Yields `Result[T]{Item, TotalCount, IncompleteResults}` per item;
+  surfaces the post-page-10 1000-result hard cap as
+  `ErrResultCapHit`. Reuses `pages.Pages` for Link-header walking.
+  Functional options (`WithBaseURL`, `WithPerPage`, `WithSort`,
+  `WithOrder`, `WithHeaders`) match the convention used by the rest
+  of ghkit; `WithBaseURL` overrides the GitHub default for GHES or
+  test fixtures.
+- `cond.Status`, `cond.StatusOf`, `cond.Fetch[T]`: surfaces the
+  change-vs-unchanged signal the etag layer already computes.
+  `cond.HeaderCacheStatus` is the canonical `"X-Ghkit-Cache"` header
+  the etag layer sets on synth-200 (`"hit"`) and wire-200 store
+  (`"miss"`). `StatusOf` is nil-safe and maps absent to `Updated`.
+  Sentinel errors `cond.ErrNilClient`, `cond.ErrNilContext`,
+  `cond.ErrNilRequest` for invalid `Fetch` arguments. Decode errors
+  wrap as `cond: decode: %w` for parity with pages, polling, search.
+- `etag/transport.go`: sets `cond.HeaderCacheStatus` on synth-200
+  (after header merge) and wire-200 (after `cache.Add` returns) so
+  the cache does not ingest the key. Drift detector and
+  `ComputeExpectedETag` are unaffected (the header is response-only
+  and not in the hash domain).
+- `retry.RetryAfter(resp) (time.Duration, bool)`: exported wrapper
+  around `parseRetryAfter`. Returns `(0, false)` for absent,
+  unparseable, AND negative-numeric values. Used by `polling` to
+  honor server hints without duplicating the parser.
+- `ghtest.ETagServer(t, body) (*httptest.Server, *int64)`: lifted
+  from `etag/transport_test.go`. Used by polling, cond, and any
+  future test that exercises etag composition.
+- `retry`: `retry_retry_after_unparseable` slog event at Warn when
+  the header is present but matches neither delta-seconds nor
+  HTTP-date. Carries a length-bounded, ASCII-sanitised `raw`
+  attribute (32 bytes max).
+- `retry`: `retry_sleep` event's `source` attribute gains a
+  `"malformed"` value, distinct from `"jitter"` and `"retry_after"`.
+- `retry`: `FuzzParseRetryAfter` fuzz test pinning the parser as
+  total.
+
+### Documentation
+
+- New `polling/doc.go`, `search/doc.go`, `cond/doc.go` documenting
+  contracts and sharp edges (retry compounding, throttle backpressure,
+  etag synth-200 sameness, gofri ctx-cancel observed on next
+  round-trip, header set ordering for the cond signal).
+- `retry/doc.go` documents the unparseable arm and the
+  `source="malformed"` label.
+- `pages/doc.go`: corrected the stale chain-order note (predates the
+  v1.4.0 ratelimit/throttle inversion).
+- `README.md`: Go Report Card badge added; coverage badge skipped
+  (peer cohort split: 3 of 4 transport-utility libraries do not
+  carry one).
+
+### Examples
+
+- New `examples/poll-workflow-run/`: waits for a workflow run to
+  reach `status="completed"` via `polling.As[*github.WorkflowRun]`
+  with `WithDoneT`, `WithMaxWallClock`, `WithJitter`. Pairs polling
+  with `WithETagCache` so unchanged ticks short-circuit at the etag
+  layer.
+- New `examples/search-issues/`: walks `/search/issues` with
+  `search.Issues[*github.Issue]`, surfaces `incomplete_results` and
+  the 1000-result cap.
+- New `examples/conditional-fetch/`: visible 304 via
+  `cond.Fetch[*github.Repository]`; the second call returns
+  `cond.Unchanged` so downstream work can be skipped.
+
+### Tooling
+
+- `polling`, `search`, and `cond` introduce no new runtime
+  dependencies in the root module. The `ghtest.ETagServer` lift adds
+  no module surface; `cond` is stdlib-only; `polling` imports `cond`
+  and `retry`; `search` imports `pages`. The import graph remains
+  acyclic (`etag -> cond`, `polling -> cond, retry`, `search ->
+  pages`).
+
 ## [1.4.0] - 2026-05-02
 
 Adds a `pages` sub-package: a Go 1.23 range-over-func iterator for
@@ -470,6 +580,8 @@ and rotating PATs alike.
 - `golang.org/x/oauth2` v0.36.0
 - `golang.org/x/time` v0.15.0
 
+[1.5.0]: https://github.com/pcanilho/go-github-kit/releases/tag/v1.5.0
+[1.4.0]: https://github.com/pcanilho/go-github-kit/releases/tag/v1.4.0
 [1.3.1]: https://github.com/pcanilho/go-github-kit/releases/tag/v1.3.1
 [1.3.0]: https://github.com/pcanilho/go-github-kit/releases/tag/v1.3.0
 [1.2.1]: https://github.com/pcanilho/go-github-kit/releases/tag/v1.2.1

MIGRATION.md

@@ -211,3 +211,55 @@ After swapping, before merging:
 - `go test ./...` and `go vet ./...` in your repo: tests that mocked the in-tree etag transport will need to mock against ghkit's `etag.NewTransport` or against a higher-level `*http.Client`.
 - Confirm `errors.As(err, &primaryRateLimit)` still unwraps the `*github_primary_ratelimit.RateLimitReachedError` your controller relies on (it does, ghkit re-uses gofri unchanged).
 - If you keep your own metric emitter, wrap it as a RoundTripper above the `*http.Client` returned by `ghkit.HTTPClient(...)` rather than relying on ghkit's slog events for per-route labels.
+
+## Recipe 4 (1.5): consumer utilities round (`polling`, `search`, `cond`)
+
+Three consumer-facing iterators ship in v1.5.0. Each composes with the
+existing transport stack via the shared `*http.Client` and adds no new
+runtime dependencies in the root module.
+
+### `polling`: long-running operations
+
+Replace ad-hoc `time.Ticker` loops with a range-over-func iterator:
+
+```go
+seq := polling.As[*github.WorkflowRun](ctx, hc, http.MethodGet, runURL, headers, nil,
+    15*time.Second,
+    polling.WithDoneT(func(r *github.WorkflowRun) bool { return r.GetStatus() == "completed" }),
+    polling.WithMaxWallClock(30*time.Minute),
+)
+for run, err := range seq { /* ... */ }
+```
+
+Each `c.Do` benefits from retry, etag, ratelimit, throttle, oauth2.
+Recommend `retry.WithMaxAttempts(1)` on the client when polling owns
+the outer loop, otherwise retry's per-attempt jitter compounds with
+the polling interval.
+
+### `search`: envelope-shaped pagination
+
+`pages.As[T]` cannot serve `/search/*` (envelope, not array). Use
+`search.Issues[T]` etc. and surface `IncompleteResults` /
+`ErrResultCapHit` per page:
+
+```go
+for r, err := range search.Issues[*github.Issue](ctx, hc, q, search.WithPerPage(100)) {
+    if errors.Is(err, search.ErrResultCapHit) { /* refine query */ break }
+    /* ... */
+}
+```
+
+### `cond`: visible 304
+
+The etag layer used to erase the change-vs-unchanged signal before the
+caller saw it. v1.5.0 surfaces it via `cond.HeaderCacheStatus`
+(`"X-Ghkit-Cache"`) on the response, mapped to `cond.Status` by
+`cond.StatusOf(resp)`. Use `cond.Fetch[T]` for one-shot conditional
+GETs, or `polling.WithChangeOnly` to silently skip polling iterations
+on cache hits.
+
+No API breaks. The new `X-Ghkit-Cache` response header is additive;
+existing consumers ignore it. The exported `retry.RetryAfter` is a
+new symbol consumed internally by `polling`; consumers can use it for
+their own Retry-After parsing without depending on the unexported
+`parseOutcome` enum.

README.md

@@ -4,6 +4,7 @@ A small Go toolkit that wraps [`github.com/google/go-github`](https://github.com
 
 [![CI](https://github.com/pcanilho/go-github-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/pcanilho/go-github-kit/actions/workflows/ci.yml)
 [![Go Reference](https://pkg.go.dev/badge/github.com/pcanilho/go-github-kit.svg)](https://pkg.go.dev/github.com/pcanilho/go-github-kit)
+[![Go Report Card](https://goreportcard.com/badge/github.com/pcanilho/go-github-kit)](https://goreportcard.com/report/github.com/pcanilho/go-github-kit)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ## Why?
@@ -166,6 +167,135 @@ fmt.Printf("total: %d\n", n)
 For tests, `ghtest.LinkHeader(baseURL, page, perPage, lastPage)` builds RFC 8288 Link header values. See [`examples/list-all-repos/`](examples/list-all-repos/main.go) for a runnable end-to-end demo.
 </details>
 
+<details>
+<summary><b>Polling a long-running operation (workflow run, check run, deployment)</b></summary>
+
+The `polling` sub-package iterates an HTTP endpoint on a caller-tunable interval, reusing the configured `*http.Client` so retry, etag, ratelimit, throttle, and oauth2 apply per attempt. `polling.As[T]` decodes each response into `T`; `WithDoneT` stops on the decoded value; `WithMaxWallClock` caps total time and wraps `context.DeadlineExceeded`.
+
+```go
+import (
+    "context"
+    "errors"
+    "log"
+    "net/http"
+    "os"
+    "time"
+
+    "github.com/google/go-github/v85/github"
+    ghkit "github.com/pcanilho/go-github-kit"
+    "github.com/pcanilho/go-github-kit/polling"
+    "github.com/pcanilho/go-github-kit/retry"
+)
+
+hc, err := ghkit.HTTPClient(
+    ghkit.WithToken(os.Getenv("GITHUB_TOKEN")),
+    ghkit.WithRetry(retry.WithMaxAttempts(1)), // polling owns the loop
+    ghkit.WithETagCache(),
+)
+if err != nil { panic(err) }
+
+ctx, cancel := context.WithTimeout(context.Background(), 35*time.Minute)
+defer cancel()
+
+url := "https://api.github.com/repos/owner/repo/actions/runs/12345"
+seq := polling.As[*github.WorkflowRun](
+    ctx, hc, http.MethodGet, url,
+    http.Header{"Accept": []string{"application/vnd.github+json"}},
+    nil, 15*time.Second,
+    polling.WithDoneT(func(r *github.WorkflowRun) bool { return r.GetStatus() == "completed" }),
+    polling.WithMaxWallClock(30*time.Minute),
+    polling.WithJitter(0.2),
+)
+
+var run *github.WorkflowRun
+for r, err := range seq {
+    if err != nil {
+        if errors.Is(err, polling.ErrMaxWallClockExceeded) { log.Fatal("budget exceeded") }
+        log.Fatal(err)
+    }
+    run = r
+}
+log.Printf("conclusion=%s", run.GetConclusion())
+```
+
+Sharp edges: each `c.Do` may itself loop through `retry.Transport` (pass `retry.WithMaxAttempts(1)` when polling owns the outer loop); `throttle.WithRequestsPerSecond` below `1/interval` dominates cadence; with `WithETagCache` an unchanged resource yields identical decoded bytes per tick (pair with `polling.WithChangeOnly` to skip those silently). Pages-shape body ownership: `Poll` yields `*http.Response` and the caller closes; `As[T]` owns and closes via defer.
+
+See [`examples/poll-workflow-run/`](examples/poll-workflow-run/main.go) for a runnable demo.
+</details>
+
+<details>
+<summary><b>Searching with envelope pagination (1000-cap aware)</b></summary>
+
+GitHub's `/search/*` endpoints return an envelope (`{total_count, incomplete_results, items[]}`), so `pages.As[T]` cannot serve them directly. The `search` sub-package wraps the four common endpoints (`Issues`, `Code`, `Repos`, `Users`) and surfaces both `IncompleteResults` (timed-out queries) and the post-page-10 1000-result hard cap as `ErrResultCapHit`.
+
+```go
+import (
+    "context"
+    "errors"
+    "fmt"
+
+    "github.com/google/go-github/v85/github"
+    "github.com/pcanilho/go-github-kit/search"
+)
+
+for r, err := range search.Issues[*github.Issue](
+    context.Background(), hc, "is:open is:pr author:torvalds",
+    search.WithPerPage(100),
+    search.WithSort("updated"),
+    search.WithOrder("desc"),
+) {
+    if err != nil {
+        if errors.Is(err, search.ErrResultCapHit) {
+            // Refine the query with a `created:<...` date filter.
+            break
+        }
+        panic(err)
+    }
+    if r.IncompleteResults {
+        // GitHub timed out server-side on this page; results may be partial.
+    }
+    fmt.Printf("[%d] %s\n", r.TotalCount, r.Item.GetHTMLURL())
+}
+```
+
+Implementation reuses `pages.Pages` for Link-header walking, so per-page retry/etag/ratelimit/throttle composition is automatic. Search has its own `X-RateLimit-Resource` budget; gofri routes requests transparently. See [`examples/search-issues/`](examples/search-issues/main.go).
+</details>
+
+<details>
+<summary><b>Detecting unchanged resources (visible 304)</b></summary>
+
+The `etag` layer transparently converts 304 responses into synthesised 200s with the cached body. The `cond` sub-package surfaces the change-vs-unchanged signal that is otherwise erased, letting consumers skip JSON parse, structural diff, DB writes, and webhook fan-out when nothing changed.
+
+```go
+import (
+    "context"
+    "encoding/json"
+    "io"
+    "net/http"
+
+    "github.com/google/go-github/v85/github"
+    "github.com/pcanilho/go-github-kit/cond"
+)
+
+req, _ := http.NewRequest(http.MethodGet, "https://api.github.com/repos/google/go-github", nil)
+req.Header.Set("Accept", "application/vnd.github+json")
+
+repo, status, err := cond.Fetch(context.Background(), hc, req,
+    func(r io.Reader) (*github.Repository, error) {
+        var v github.Repository
+        return &v, json.NewDecoder(r).Decode(&v)
+    },
+)
+if err != nil { panic(err) }
+switch status {
+case cond.Updated:    // wire 200 (or no etag layer in chain)
+case cond.Unchanged:  // synth 200 from cache hit; resource hasn't changed
+}
+```
+
+Mechanics: the etag layer sets `cond.HeaderCacheStatus` (`"X-Ghkit-Cache"`) on synth-200 (`"hit"`) and wire-200-store (`"miss"`) paths. `cond.StatusOf(resp)` reads the header. Absent header → `Updated` (no etag layer in chain → caller behaves as if every response is fresh). Pair with `polling.WithChangeOnly` to silently skip yields when polling an unchanged resource. See [`examples/conditional-fetch/`](examples/conditional-fetch/main.go).
+</details>
+
 <details>
 <summary><b>GitHub App installation tokens (JIT auth, shared cache)</b></summary>