feat(proxies): cache GitHub release artifacts and Packagist

[luthermonson]

Two new CacheProxy implementations, plus a fix that makes ServeArtifact honour TTL.

Why these two

An inventory of the org’s workflows found the largest uncached ecosystems were not the ones with proxies:

ecosystem	files	had a cache?
cargo build	39	proxy existed, switched off — now enabled on the fleet
composer install	22	no
releases/download	19	no
dtolnay/rust-toolchain	11	via cargo proxy
go mod download	4	yes — the only one

Measured cost on a real build (php-sdk, x86_64 gnu, 2026-09-20): 40 source artifacts, 87s of a 591s build.

ghrel

GitHub releases are a distribution channel with no registry and no GOPROXY-style redirect — a release download is a plain github.com URL baked into whatever tool fetches it. Intercepting transparently would mean terminating TLS for job containers (a CA in every image, and a real change to what untrusted job code is exposed to).

So it advertises GHREL_PROXY and lets tools opt in. Unset, everything goes upstream exactly as today — which also keeps builds correct on GitHub-hosted runners and laptops.

Metadata is cached with a TTL and its asset URLs rewritten to the proxy’s /download/ route — otherwise a caller takes kilobytes of JSON from the LAN and every megabyte from the CDN.

composer

Deliberately rewritten on pkgcache rather than lifting the implementation from the stale feat/cargo-composer-cache branch. That version predates pkgcache entirely and would have reinvented the bounded LRU store, traversal-safe key mapping and fail-open fetch — and disk-full is a failure mode these nodes have hit twice.

It also fixes what that version documented about itself:

"distribution zips come from mirrors and GitHub, which this proxy does not front"

Metadata is the cheap part. Packagist dist URLs name an exact commit, so they are genuinely immutable — now fronted and cached permanently. The archive route re-checks the host allowlist, so a job cannot hand it an arbitrary URL and use ephemerd as an open proxy.

ServeArtifact now honours TTL

This is the part most worth reviewing.

ServeArtifact served any cached entry unconditionally — it never consulted req.TTL. That is correct for every existing caller: npm, PyPI and pub all refuse to re-publish a file, so their proxies pass Immutable and the question never arises.

GitHub does not. An asset can be deleted and re-uploaded under the same URL. Without this, ghrel’s non-immutable default was a no-op and the safe default was silently "cache forever" — the exact hazard it exists to avoid.

A stale, non-immutable entry is now revalidated with a conditional GET, reusing decide() — the same primitive Document already uses. Gated so Immutable callers are untouched; npm/pip/pub/cargo suites are unchanged.

Testing

go build, go vet, and go test ./pkg/proxies/... ./pkg/config/... ./cmd/... all pass.

Coverage: URL rewriting for both proxies (single-object and array release shapes), the composer open-proxy guard, cache-key safety, and both TTL branches.

Revert-verified — each of these was confirmed to fail when the behaviour is neutered:

• revalidation off → conditional requests = 0, want 2
• either rewrite made a no-op → its suite fails
• composer allowlist check removed → a metadata-service URL returns 200 instead of 403

Notes for reviewers

• Windows pools get none of this by design. Gateway proxies bind the bridge gateway, which Hyper-V job containers cannot route to; injecting the env var there hangs the build (mayfly already suppresses the others for this reason).
• Four silent-failure bugs were caught during review and fixed before this landed: cache keys containing ? (rejected by SafeSegments, so paginated listings went upstream forever), nested API paths colliding file-vs-directory, a composer dist key embedding a host with a port, and advertiseBase() breaking on a port-0 listener. All failed silently — Document() logs a warning and serves the bytes — so the cache would have appeared to work while caching nothing.

[ephpm]

ePHPm Preview — removed

Preview deployment has been torn down.