Maven wrapper caching does not seem to cache enough

[headius]

Description:

setup-java was recently modified (2 weeks ago) to also cache Maven distributions used by the mvnw wrapper script. See #1027.

JRuby's build uses setup-java@v5 but we are still seeing failed downloads of the distribution. We would expect this to have been cached long ago, either by us or by other projects, so this is unexpected.

See a failure as recently as yesterday, associated with a PR to attempt to reduce these failures: https://github.com/jruby/jruby/actions/runs/28970521797/job/85964762963

Task version:

setup-java@v5 as of the time of the above build.

Platform:

• Ubuntu
• macOS
• Windows

I know we see it on Ubuntu, but I believe it has affected builds on other platforms as well. It does not appear to be specific to any platform.

Runner type:

• Hosted
• Self-hosted

Repro steps:
A description with steps to reproduce the issue. If your have a public example or repo to share, please provide the link.

The build below shows a failed mvnw wrapper download that killed a JRuby CI job.

https://github.com/jruby/jruby/actions/runs/28970521797/job/85964762963

Expected behavior:

We use cache: maven and setup-java@v5 so we expected that the wrapper would not be downloaded from Maven Central and would not trigger this error.

Actual behavior:

As others have reported, rate-limiting or similar restrictions at the Ruby Central level appear to be causing mvnw dist downloads to fail occasionally. We want to use setup-java caching to prevent re-downloading of this distribution, since it almost never changes. That does not appear to be happening.

[headius]

See JRuby issue jruby/jruby#9493 which led us to start exploring how to make mvnw more reliable.

[brunoborges]

@headius I opened #1097 with a fix. Root cause: the Maven wrapper distribution (~/.m2/wrapper/dists) was cached in the same entry as ~/.m2/repository, keyed on **/pom.xml (+ wrapper props + extensions). Since poms change constantly and there are intentionally no restoreKeys (#269), almost every change was a full cache miss, so mvnw re-downloaded Maven and hit the intermittent rate-limit failures. In your failing run I saw maven cache is not found followed by wget: Failed to fetch .../apache-maven-3.9.14-bin.zip.

The PR gives the wrapper distribution its own cache entry keyed only on **/.mvn/wrapper/maven-wrapper.properties, so it survives pom.xml changes.

Would you be able to test it? You can pin setup-java to the PR commit:

- uses: actions/setup-java@6cd4d8602abcb93d479ac1a322ebf80166d853e6
  with:
    distribution: temurin
    java-version: '21'
    cache: maven

A few notes:

• The first run after switching won't benefit yet (it needs to populate the new setup-java-<os>-<arch>-maven-wrapper-<hash> cache entry). Let it run once, then check that subsequent runs, especially ones that modify a pom.xml, log Cache restored from key: ... for the wrapper and no longer download Maven via mvnw.
• Old caches from the previous shared key are harmless and will age out.
• SHA pinning is safest since the branch ref may change as the PR evolves.

Appreciate any results you can share.

[chadlwilson]

To be fair, in the failing run above, the download URL of the wrapper itself was changed as an experiment, so if the hash is on the content of files (which it seems it is, correcting my own earlier understanding here), it was never going to be caching the Maven distribution - so perhaps not a great example.

Nevertheless, separating the distribution would probably be helpful, given mvnw seems to be rather flaky when in script mode (wget only) in ways normal maven dependency resolution is not, and gives you no feedback by default to even know why the download failed.

The bigger question of re-downloading every single dependency for any single text change in any POM is probably still a bit of an issue for a project like JRuby, but I suppose the workaround to that is to consolidate centralised dependency definitions somewhere, and then set cache-dependency-path to that single POM, rather than "all POMs" ?

We'd probably need to look at
https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#ensuring-the-maven-cache-is-complete-plugin-dependencies to look for other improvements in JRuby, avoid cache population races for parallel jobs and other cache churn.