Skip to content

Key the download cache by release, not by library version - #8

Merged
andrewchen5678 merged 2 commits into
mainfrom
fix/cache-keyed-by-release
Sep 6, 2026
Merged

andrewchen5678 merged 2 commits into
mainfrom
fix/cache-keyed-by-release

Conversation

@andrewchen5678

Copy link
Copy Markdown
Contributor

build.rs resolves releases/latest, but cached what it found under the upstream library
version alone. latest moves and the version does not, so the first release a machine ever
downloaded answered for every later build of that version, forever — and because the archives
of one version differ, the symptom was a feature quietly missing rather than a failure.

It cost a day in the consuming project: a FreeRDP archive cached before rdpei was built in
kept the touch channel out of every local build for a month, while CI, which has no such cache,
was correct throughout. All four prebuilt repositories had the same keying, so all four get the
same fix.

What changes

  • The cache is one directory per release tag — $CARGO_HOME/<repo>/<tag>/<target>/.
  • Which release latest is gets asked before the cache is read. /releases/latest names the
    tag in its Location header, so it is one HEAD with no body — no api.github.com, no 60/hour
    unauthenticated ceiling, and no JSON to parse in a build script whose selling point is that it
    compiles no dependencies.
  • The archive and its SHA256SUMS now both come from that tag, which also closes the
    pre-existing race of resolving latest twice.
  • Cannot ask (CARGO_NET_OFFLINE, or a network that does not answer) → the newest cached
    release for the version, provenance labelled not revalidated, and a warning when it was not
    a deliberate offline build. Tag stamps are fixed-width UTC, so lexicographic max is newest.
  • A latest whose version is not the one the checkout builds against is an error naming both,
    instead of a 404 on a URL nobody typed.

FDK_AAC_PREBUILT_DIR-style overrides and prebuilt/<target>/ still short-circuit ahead of all
of this, so the local build loop makes no network request at all.

Tested

Each scenario run against the real releases, on aarch64-apple-darwin:

scenario result
cold cache fetches from the resolved tag, checks SHA256SUMS + MANIFEST
warm cache, same tag hit, no fetch
cache holding only an older release ignored; current release downloaded ← the regression
offline, two releases cached newest, marked not revalidated
version the releases have moved past error naming the tag and the version

cargo clippy --all-targets -- -D warnings and cargo test pass.

🤖 Generated with Claude Code

andrewchen5678 and others added 2 commits September 6, 2026 09:05
clippy's manual_is_multiple_of, which -D warnings makes fatal, so the repo's
own post-change check did not pass on a current toolchain.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
build.rs resolves `releases/latest`, but cached what it found under the
upstream library version alone. `latest` moves and the version does not, so
the first release a machine ever downloaded answered for every later build of
that version, forever — and because the archives of one version differ (an
option changed, a patch applied, a flag corrected), the symptom was a feature
quietly missing rather than a failure.

The cache is now one directory per release tag, and which release `latest` is
gets asked before it is read: the `/releases/latest` redirect names the tag in
its Location header, so it is one HEAD with no body and no `api.github.com`
rate limit to parse JSON through. Both the archive and its SHA256SUMS are then
fetched from that tag rather than resolving `latest` twice.

Where the question cannot be asked — CARGO_NET_OFFLINE, or a network that does
not answer — the newest cached release for the version is used and the
provenance line says it was not revalidated; the stamp in a tag is a
fixed-width UTC timestamp, so lexicographic max is the newest. A `latest` whose
version is not the one the checkout builds against is now an error naming both,
instead of a 404 on a URL nobody typed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@andrewchen5678
andrewchen5678 merged commit 8dd83e8 into main Sep 6, 2026
10 of 14 checks passed
@andrewchen5678
andrewchen5678 deleted the fix/cache-keyed-by-release branch September 6, 2026 16:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant