fix(container): fall back to the GitHub mirror for nv-codec-headers (ADR-1200)

[lusoris]

Summary

dev/Containerfile fetched nv-codec-headers from a single host, code.ffmpeg.org. That host has been unreachable for over six hours today — curl returning HTTP 000 after a 30-second timeout on every attempt — and the layer simply stalled. Under CLAUDE.md rule 15 and ADR-1102 the dev container is the canonical build and measurement environment, so for that whole window it could not be built at all, with no symptom beyond an apparent hang.

The stated reason for the single source does not apply to the pin in use. The comment read "GitHub mirror lags so use code.ffmpeg.org" — true of an unreleased commit, false of a tag. NV_CODEC_HEADERS_REF is n13.1.15.0, that tag is published on both hosts, and the GitHub tarball carries the cuStreamCreateWithPriority declaration in include/ffnvcodec/dynlink_loader.h that the pin exists for. Checked, not assumed.

What changes

• Upstream stays first; GitHub runs only when it fails outright.
• The archive is asserted, not trusted: the build requires include/ffnvcodec/dynlink_cuda.h and greps dynlink_loader.h for cuStreamCreateWithPriority before make install. A fallback that silently installs the wrong headers would be worse than the outage it replaces.
• The two archives unpack to different top-level directory names (nv-codec-headers vs nv-codec-headers-<tag>), so the build cds into whatever was extracted rather than the hard-coded name that would have broken on the mirror.
• The primary gets a short leash. Measured: the first draft's --retry 3 --max-time 120 took 487 s to fall through and succeed; --retry 1 --max-time 60 takes 123 s. The healthy path is one 0.5 s fetch either way.

Type

• build / ci — tooling / infra

Checklist

• Commits follow Conventional Commits.
• make format && make lint green locally — pre-commit run --files clean on all eight touched files.
• Unit tests pass: meson test -C build. — no library code is touched; the change is a container build layer plus documentation.
• SIMD/GPU code path — none touched.
• Feature extractor twins — none touched.
• New .c / .cpp / .cu / .h — none added.
• Breaking change — no. Same package, same tag; a second source is consulted only when the first fails.
• ADR row lives in docs/adr/_index_fragments/ with the slug in _order.txt; README.md regenerated with --write and verified with --check.

Bug-status hygiene (ADR-0165)

• docs/state.md updated — no state delta: this is an upstream host outage, not a tracked defect in this codebase.

Netflix golden-data gate (ADR-0024)

• I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.

Deep-dive deliverables (ADR-0108)

• Research digest — no digest needed: trivial. One unreachable host, one tag verified present on the mirror.
• Decision matrix — ADR-1200 ## Alternatives considered weighs five options, including switching to GitHub outright and vendoring the 86 KB of headers.
• AGENTS.md invariant note — recorded in docs/rebase-notes.md, where this repo keeps container-level invariants: do not collapse the fallback back to one curl, and keep both the content assertion and the find-based cd.
• Reproducer / smoke-test command — below.
• CHANGELOG fragment — changelog.d/fixed/nv-codec-headers-mirror-fallback.md.
• Rebase note — fix/container-nv-codec-mirror-fallback — second source for nv-codec-headers (2026-09-06).

Reproducer

The outage itself, still live at the time of writing:

curl -sS -o /dev/null -w "%{http_code} in %{time_total}s\n" --max-time 30 \
  https://code.ffmpeg.org/FFmpeg/nv-codec-headers/archive/n13.1.15.0.tar.gz
# 000 in 30.004s

The fallback logic exactly as committed:

time { curl -fsSL --retry 1 --connect-timeout 10 --max-time 60 \
        https://code.ffmpeg.org/FFmpeg/nv-codec-headers/archive/n13.1.15.0.tar.gz -o nvh.tgz \
      || curl -fsSL --retry 3 --connect-timeout 20 --max-time 120 \
        https://github.com/FFmpeg/nv-codec-headers/archive/refs/tags/n13.1.15.0.tar.gz -o nvh.tgz; }
tar tzf nvh.tgz | head -1     # nv-codec-headers-n13.1.15.0/

Observed: 123 s total, 86247 bytes, and the tag's tree contains cuStreamCreateWithPriority.

End to end, with the primary still down:

docker build --file dev/Containerfile --target libvmaf-build -t nvmirror-test .

Observed: nv-codec-headers: code.ffmpeg.org unreachable, falling back to the GitHub mirror, then make: Leaving directory '/tmp/nv-codec-headers-n13.1.15.0', #41 DONE, and the next meson step reporting Has header "ffnvcodec/dynlink_cuda.h" : YES. The build then proceeded into the CUDA targets that had been unreachable all day.

Known follow-ups

• The other fetches in dev/Containerfile remain single-sourced — oneAPI, ROCm, ONNX Runtime, SVT-AV1, vvenc, AMF, FFmpeg. This PR does not claim to have audited them; it fixes the one that actually failed. A build cache or internal proxy would address the class, and is the right shape at a larger scale.