Live catalog of known external PhoenixKit packages fetched from Hex.pm.

Fetched on demand and cached in an ETS table for 10 minutes. On Hex failure, returns stale cached data when within the 24h max-stale-age cap, otherwise returns extra_known_packages config entries only.

Cache uses an ETS named table (:phoenix_kit_known_packages_cache) with read_concurrency: true rather than :persistent_term, to avoid global-GC write amplification on multi-node cold deploys.

Public API

• list/0 and list/1 — return the catalog (cached).
• clear_cache/0 — wipes the cache (for tests).

list/1 accepts opts (intended for tests, not production):

• :ttl_ms — cache TTL (default :timer.minutes(10))
• :max_stale_age_ms — how long stale data may be served on Hex failure (default :timer.hours(24))
• :req_options — pass-through to Req.get/2

Operational signals

Hex outages emit Logger entries at three levels — each maps to a distinct degradation state operators can alert on:

• :warning "Hex fetch failed … serving stale data" — cache hit within max_stale_age_ms. Catalog still works; Hex briefly unavailable. Transient.
• :warning "Hex fetch failed … no cached data" — Hex unreachable AND cache empty. Catalog shows config extras only. Visible degradation, but not a crisis (admin Modules page is the only consumer).
• :error "Hex fetch failed … exceeds max stale age" — Hex unreachable for over max_stale_age_ms. Cached entries dropped, catalog falls back to config extras. The escalation level: page on this if it persists.