Server-side download fallback settings via a manifest.json document on GitHub Pages #1810

Follow-up to #1806 / #1807.

Goal

Download fallback settings live server-side, so mirror order and artifact locations change without an fbuild release. The document uses the zackees/manifest.json format and is published on FastLED/fbuild's GitHub Pages.

Design

• Document: a manifest.json v1 Release (tool: fbuild-download-mirror). Each components[].asset lists urls[] in the order fbuild should try them: the fbuild bucket and then the vendor URL, plus size_bytes and an optional sha256. Source of truth is site/mirror/manifest.json in this repo, generated by ci/gen_mirror_manifest.py (HEAD-checks the bucket, so only present objects are listed) and validated against the published schema.
• Hosting: the Pages publish step in benchmark-build-comparison.yml copies site/mirror/ into the site, so it is served at https://fastled.github.io/fbuild/mirror/manifest.json. raw.githubusercontent.com/FastLED/fbuild/main/site/mirror/manifest.json is the second URL.
• Client (fbuild-packages-fetch):
  • Fetch and cache: fetch once per process with a short timeout. Cache in the fbuild cache root with a 24 h TTL; if the fetch fails, use the stale cached copy, and if there is none, use the built-in {path} default from feat(fetch): download from fbuild's mirror bucket by default (#1806) #1807.
  • Matching: look up a download by any URL its asset lists. The manifest's order wins, and the primary URL is always kept as a candidate.
  • Opting out: an explicit FBUILD_DOWNLOAD_MIRRORS still overrides everything. FBUILD_MIRROR_MANIFEST_URL overrides the manifest location, and setting it empty disables the manifest.
  • Rejected documents: a wrong kind, an unknown schema_version, non-HTTPS URLs or an oversized body are rejected, and fbuild keeps the previous rung of the fallback ladder.
  • Yanked assets: fbuild goes straight to the vendor URL.
  • Checksums: bytes served by a mirror are checked against the manifest's sha256 when one is present. A mismatch counts as that mirror failing, and fbuild moves on to the next URL.

Acceptance

Adversarial tests covering: malformed or hostile documents, a server that is down with a stale cache, no cache, a mirror serving wrong bytes, yanked assets, env overrides, and a live end-to-end resolve against the published Pages URL.