fix(badges): make GitHub badges reliable + surface provider failures in Sentry

[jal-co]

Problem

Badges that depend on a third-party API intermittently rendered a red "not found" and stayed broken — the single worst outcome for user trust. Root causes:

1. Errors were cached like successes → a momentary blip got pinned at the CDN for an hour.
2. No last-known-good fallback → a failed live fetch collapsed straight to "not found".
3. Only GitHub got hardened initially → every other API provider (npm, pypi, docker, crates, discord, vscode, …) still broke on a transient blip.
4. No observability and no distinction between a transient failure and a genuinely invalid resource.

Changes

Resilience — now across all ~44 API-backed providers

A single clear fetcher contract in cachedFetchStale:

• throws → TRANSIENT (network / 429 / 5xx / parse) → serve last-known-good, back off, alert if nothing cached.
• returns null → DEFINITIVE negative (upstream answered; resource absent) → short-lived "not found", never serve stale, never alert (a typo'd package can't alert-storm or show someone else's value).
• returns value → success (cached fresh + 7-day last-known-good).

Wired through the shared path so it covers everything at once:

• provider-fetch (providerFetch/providerFetchText) — throw on 429/5xx, null on other non-2xx, 7-day stale window.
• vscode (custom POST) moved onto the same contract.
• github — githubFetch throws on transient / returns null only on definitive negatives, so its stale fallback actually triggers.
• Short-lived ERROR_CACHE_HEADERS on every error/"not found" response; group responses use them when any segment is unresolved.

Observability (Sentry)

• Provider-alert channel in core (setProviderAlertCallback / reportProviderAlert), wired in web + engine to Sentry.captureMessage.
• Rate limits / outages for every provider — centralized in recordBackoff (the chokepoint all providers funnel through), fired once per backoff cycle.
• Badge actually breaks → badge_unavailable alert only when a transient failure has no last-known-good to serve.

Correctness / hardening

• GitHub 403 rate limits: GitHub signals primary limits as 403 with x-ratelimit-remaining: 0 (not only 429). Detect both so a rate limit is treated as transient (backoff + stale) instead of masquerading as "not found". handleUpstreamStatus now backs off on any 5xx.
• A genuine GitHub 404 renders invalid repository (terminal error: cached briefly, never persisted as last-known-good, short cache headers — self-heals in ~60s).
• Removed dead dependents-repo / dependents-pkg GitHub topics (registered but never implemented → would have alert-stormed).

Tests

• tsc --noEmit clean on core + engine.
• Core suite: 55 passing, including a new provider-fetch suite (5xx→stale, 404→null, 2xx→data) and cache-layer tests for the throw=transient / null=definitive contract, terminal-error non-persistence, and once-per-cycle rate-limit alerts.

Notes

• degraded_stale (served stale on failure) stays a metric counter, not a Sentry issue — the badge still renders a value.
• Possible follow-up: token-pool health (an empty/invalid pool is what triggers the unauthenticated rate-limit cascade), and bundling the resvg WASM so PNG rendering never depends on a runtime CDN fetch.

Commits

1. GitHub badges resilient to transient failures (error headers + last-known-good).
2. Sentry alerts on GitHub rate limits + "invalid repository" for 404s.
3. Extend provider alerts to all providers (centralized in recordBackoff).
4. Address review — invalid-repo caching as terminal error + remove dead topics.
5. Make all API-backed badges resilient (throw=transient / null=definitive contract) + GitHub 403 rate-limit detection.

https://claude.ai/code/session_01B5fH9ZzdStYYtWcF6QNpgw

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
shieldcn	Ready	Preview, Comment	Jun 9, 2026 4:19pm