This is the opt-in surface for the new go-gh aggressive caching
support. Setting GH_AGGRESSIVE_CACHING_TTL to a Go duration string
(e.g. 30s, 1m, 5m, 1h) enables process-wide TTL caching for cacheable
REST and GraphQL requests on the standard authenticated HTTP client.
Motivation: heavy users running multiple parallel agent harnesses
(e.g. several Codex agents in lockstep) issue duplicate identical
requests within seconds of each other, exhausting the GitHub primary
REST rate limit and tripping secondary limits. A short TTL (~30s)
dedupes the lockstep traffic without changing what gh fundamentally
is. The trade-off (bounded staleness) is acceptable when explicitly
opted into.
Wiring:
- api/http_client.go: NewHTTPClient reads GH_AGGRESSIVE_CACHING_TTL
after honoring caller-supplied EnableCache. The env var only
activates when:
- opts.EnableCache is not already true (caller config wins)
- opts.SkipDefaultHeaders is false (PlainHttpClient bypasses
defaults and must not opt into caching by env var)
Per-request X-GH-CACHE-TTL: 0 still bypasses for individual calls.
- parseAggressiveCachingTTL is silent on failure: empty, '0',
negative, or unparseable values disable the feature. Matches the
convention for other GH_* env vars and avoids stderr noise from
a transport layer. Users diagnose via the X-GH-Cache-Status
response header.
- help_topic.go: documents the env var, format, staleness caveat,
intended use case, observability hook, cleanup path
(gh config clear-cache), and explicit precedence rules.
Tests cover:
- parseAggressiveCachingTTL edge cases (empty, valid, zero,
negative, unparseable, missing unit, plain number).
- Env var with positive duration enables caching end-to-end
(miss -> hit pattern, network call only on first request).
- Env var unset or with invalid value leaves caching disabled.
- Caller-set EnableCache + CacheTTL takes precedence over env var.
- SkipDefaultHeaders (PlainHttpClient path) bypasses aggressive
caching even when env var is set.
- Per-request X-GH-CACHE-TTL: 0 hard-bypasses cache when env var
is set, and does not pollute the cached entry.
Manual smoke verified against live api.github.com:
- REST GET: miss -> hit transitions work, X-GH-Cache-Status
visible via 'gh api -i'.
- GraphQL query: same miss -> hit pattern works.
- Per-request opt-out: header returns no X-GH-Cache-Status,
confirming bypass.
- 'gh auth status', 'gh config clear-cache' continue to work.
Out of scope here:
- ETag / If-None-Match revalidation (planned follow-up that layers
on top of the same transport).
- Rewriting commands like 'gh pr checks --watch' to take advantage
of REST + ETag (separate decision, separate PR).
Depends on go-gh changes:
- 'Fix per-request cache opt-out when global TTL is configured'
- 'Restrict cacheable responses to 2xx'
- 'Skip caching of GraphQL mutations and subscriptions'
- 'Use atomic temp-file + rename for cache writes'
- 'Vary cache key by Accept-Encoding, X-GitHub-Api-Version, ...'
- 'Emit X-GH-Cache-Status response header for cache observability'
Related: cli/cli#13279, cli/cli#13293
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
35c2439fd9