Cache resolved JDK releases to remove the vendor API from warm jobs - #1208

Description:

Only Temurin is preinstalled in the runner tool cache. For every other distribution (Zulu, Corretto, Liberica, SapMachine, Microsoft, Semeru, ...) findInToolcache() misses on essentially every job, so setup-java must call the distribution's metadata API to learn which release satisfies java-version before it can even compute the JDK cache key. That makes the vendor a hard per-job dependency even when the JDK bytes are already in the Actions cache, and turns a vendor 403, 429, or outage into a job failure.

This stores the resolved release itself in a small companion cache entry, keyed only on inputs known before any network call: runner OS, architecture, distribution, package type, requested version, and stability. A job that finds a current entry installs the JDK without contacting the metadata API at all.

Why the key and path are shaped this way

@actions/cache derives a cache version by hashing the requested paths (getCacheVersion in cacheUtils), and getCacheEntry(keys, paths) matches on it, so save and restore paths must be identical. That rules out any scheme keyed on the resolved version, since the path would have to contain a version we do not know yet. Instead the entry uses a path that excludes the freshness window while the key includes it:

path:        $RUNNER_TEMP/setup-java-jdk-resolution/<identityDigest>
primary key: setup-java-jdkres-v1-<os>-<arch>-<identityDigest>-<windowStart>
restoreKeys: setup-java-jdkres-v1-<os>-<arch>-<identityDigest>-

An entry from an earlier window is deliberately not used directly. setup-java still queries the metadata API, so a floating request such as java-version: 21 keeps picking up new releases; the older entry is used only when that query fails, which is what keeps a job working through an outage or rate limit. Because the entry also carries the download URL and checksum, that fallback works even when the JDK itself is not cached and still has to be downloaded. The fallback is reported with a warning.

The window is seven days. GitHub removes cache entries that have not been accessed for seven days, so anything longer would leave the previous entry evicted by the time the window rolls over, removing the fallback exactly when it is most likely to be needed. Anything shorter penalizes low-frequency repositories, which are the ones least likely to have a warm tool cache: a daily window would give no benefit at all to a workflow that runs weekly. Seven days also comfortably covers JDK release cadence, which is monthly at its fastest and usually quarterly.

Things worth a careful look

• Releases whose URL is not content-addressed are never stored. Oracle JDK and Oracle GraalVM build a /latest/ URL when java-version names only a major version, and the bytes behind it change whenever a new build is published, so its URL and its .sha256 sibling are only consistent with each other at the moment they are resolved. Caching that pair could produce a checksum mismatch that looks like tampering. Those releases are marked floating and skipped. A more specific version resolves an archived URL and is stored normally.
• The restored payload drives the download, so it is validated as untrusted input: HTTPS URLs only, supported checksum algorithms only, unknown fields dropped. This does not widen the trust model, since the existing JDK cache already restores an executable JDK from the same cache scope under a derivable key.
• The post-job save rewrites the payload the key was computed for rather than uploading whatever is on disk. A restore performed by a later step in the same job targets the same path, so without this a stale payload could be promoted into the current window's key.
• Gating: the cache is bypassed entirely for check-latest: true, java-version: latest, and force-download: true, and it is coupled to cache-jdk so nothing is written unless the user opted into caching.

Every cache interaction degrades to today's behavior on failure.

Related issue:

N/A

Check list:

• Ran npm run check locally (format, lint, build, test) and all checks pass.
• Mark if documentation changes are required.
• Mark if tests were added or updated to cover the changes.