feat(stats): server-side GitHub stats cache + client swap (stop burning visitor rate limit)

[LakshmanTurlapati]

Summary

Move all GitHub API calls off the Angular client onto a server-side 5-min poller backed by SQLite. The /stats page now reads from same-origin /api/public-stats/github/:endpoint_id instead of api.github.com directly. Stops every visitor's browser from burning the shared 60-req/hr unauthenticated GitHub rate limit and lets one authenticated server poller use the 5000-req/hr quota.

Why now

Quick task 260514-r6i had to widen the showcase CSP to allow api.github.com because /stats was hitting GitHub from the visitor's browser. Under any non-trivial traffic the shared per-IP rate limit gets exhausted and charts go dark. The right pattern is: server polls once, persists, serves from cache; this PR implements that.

Design

Cache table (showcase/server/src/db/schema.js)
github_cache keyed by endpoint_id PRIMARY KEY, with payload_json / etag / fetched_at / http_status / rate_limit_remaining / rate_limit_reset. Added inside the existing idempotent CREATE TABLE IF NOT EXISTS block so deploy auto-creates it on the Fly volume.

Poller (showcase/server/src/telemetry/github-poller.js)
Mirrors the existing housekeeper.js cron pattern: setImmediate first tick + setInterval every 5 minutes, defensive try/catch wrapping each endpoint and the outer tick body (never throws), pollerBusy overlap guard. Reads GITHUB_TOKEN once at module load — works with (5000/hr authenticated) and without (60/hr unauthenticated, single boot warning, no per-tick noise). 7 endpoints: repo-summary, stars, issues, forks, pulls, commits, releases. If-None-Match ETag round-trip turns steady-state cycles into mostly-304s that don't count against the rate budget.

Endpoint (showcase/server/src/routes/public-stats.js)
New sub-route GET /api/public-stats/github/:endpoint_id mirroring the existing /global patterns: in-process Map memo, sha256 ETag, Cache-Control: public, max-age=60, defensive res.removeHeader('Set-Cookie'), allowlist guard returning 400 on unknown endpoint_id, 503 + Retry-After: 60 on cold cache, 304 on If-None-Match match.

Angular swap (showcase/angular/src/app/core/stats/github-stats.service.ts)
API_BASE, MAX_PAGES, PER_PAGE, fetchPaginated, emitRateLimited, the 403 rate-limit branch, and the X-GitHub-Api-Version header are all gone. API_ROOT = '/api/public-stats/github' with credentials: 'same-origin'. Aggregator functions and component consumers are unchanged.

CSP cleanup (showcase/server/server.js:63)
connect-src tightened from 'self' https://api.github.com to 'self'. The now-obsolete tests/showcase-csp-allows-github-api.test.js is deleted and removed from the npm test chain.

Tests

• tests/server-github-cache.test.js (NEW, 17/17 PASS): 200+ETag round-trip, 304 path, 503+Retry-After on cold cache, 400 on unknown id, no Set-Cookie leak, memo rebuild.
• tests/server-github-poller.test.js (NEW, 31/31 PASS): tick upserts, 304 preserves payload, error resilience, GITHUB_TOKEN header on/off, pagination concat, allowlist invariant, T8 source-grep guard that MAX_PAGES_COMMITS >= 30 (regression migrated from the now-irrelevant client-side MAX_PAGES = 30 assertion in cumulative-commits-aggregator.test.js).
• tests/cumulative-commits-aggregator.test.js: trimmed by 2 assertions (MAX_PAGES moved to poller test); aggregator function coverage unchanged.

Validation gates

• node scripts/validate-extension.mjs — OK (manifest valid, 245 JS files parsed clean)
• npm --prefix showcase/angular run build — exit 0
• npm test — exit 0 (full root suite)

Verifier verdict

human_needed — 13/15 code-level truths verified by static analysis + unit tests; 2 truths route to post-deploy DevTools confirmation:

1. Visitor's browser makes ZERO api.github.com requests on /stats (provable indirectly via CSP + service source, final confirmation needs Network panel inspection).
2. All /stats charts render with real data after the first server poll cycle (aggregator code unchanged, cache test asserts byte-for-byte payload preservation, but no automated SVG output check).

Operational follow-up (user-gated)

Set the GitHub token on Fly so the poller uses the 5000/hr authenticated quota instead of the 60/hr unauthenticated fallback:

fly secrets set GITHUB_TOKEN=<github-token-with-public_repo-read-scope> -a fsb-server

The poller works without it (single boot warning, falls to unauthenticated 60/hr — still vastly better than every visitor sharing that pool). Do NOT put the token in fly.toml.

Test plan

• Merge and deploy.
• Set GITHUB_TOKEN via fly secrets.
• Confirm /api/public-stats/github/repo-summary returns 200 after the first 5-min tick.
• Open /stats with DevTools Network panel filter api.github.com — confirm ZERO requests, all GitHub data sourced from same-origin.
• Confirm charts render unchanged.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.