Avoid reopening jars per resource request and deleteOnExit per upload

[pjfanning]

Two independent resource-handling fixes in the file and resource directives, one commit each (plus a follow-up commit that makes the first one configurable), so they can be split if you prefer separate PRs.

Motivation

Jar resources are reopened per request. ResourceFile.apply opened a java.util.zip.ZipFile for every request to a resource inside a jar, only to read the entry's size and time. That re-parses the whole central directory of the jar on each request, and getFromResource/getFromResourceDirectory served out of a jar is the usual production layout for static resources. The result of getEntry was also dereferenced without a null check, so a missing entry would throw an NPE rather than reject.

Uploads register a deleteOnExit per file. fileUploadAll called File.deleteOnExit() on each temporary upload file. The JVM keeps every path passed to deleteOnExit in a global set for the lifetime of the process, and the entry is not removed when the file is deleted after the stream is consumed, so a long-running server accepting uploads grows its heap by one entry per upload.

Modification

• Read jar entry metadata from the JarURLConnection and leave its cache enabled, so the JDK reuses the same open jar the class loader already holds; guard against a null or vanished entry; share the plain URLConnection handling with the fallback branch via a small helper.
• Add a pekko.http.routing.use-jar-file-cache setting (on by default) for that behaviour. With it off, the connection reading the metadata owns its jar file and closes it again, and the entity stream is opened through a connection with caches disabled too. ResourceFile.apply(url) keeps its previous meaning and uses the cache; the new ResourceFile.apply(url, useJarFileCache) overload takes the flag.
• Place upload temp files in a directory of their own and register a single shutdown hook that removes it recursively, instead of one deleteOnExit per file.

Result

No jar is opened or parsed per request for jar-hosted resources, and a missing entry rejects instead of throwing. Deployments that need to replace jar files while the server runs (an open jar file cannot be replaced on Windows) can set use-jar-file-cache = off — which the previous implementation could not offer at all, since it opened its own ZipFile for the metadata but still streamed content through URL.openStream, which uses the JDK caches.

The on-exit cleanup that fileUploadAll documents is unchanged but now costs one shutdown hook per JVM rather than one permanent global entry per upload; the dedicated directory also gets the owner-only permissions Files.createTempDirectory applies. Note that addShutdownHook throws IllegalStateException once shutdown is in progress, so an upload arriving during shutdown fails — deleteOnExit threw in the same situation, so this is parity rather than a regression.

Scala and Java DSL settings are in parity, @since 2.0.0 is on the new public methods, and MiMa filters are added for the two new RoutingSettings members (needed on Scala 3).

Tests

• sbt "http-tests/testOnly org.apache.pekko.http.scaladsl.server.directives.FileAndResourceDirectivesSpec" - pass; new tests assert that the jar entry metadata matches the bytes actually served (a wrong length fails at toStrict), that a second request to the same route still works, and that a jar resource is still served correctly with use-jar-file-cache = off
• sbt "http-tests/testOnly org.apache.pekko.http.scaladsl.server.directives.FileUploadDirectivesSpec" - pass; new test asserts the temp files share one directory
• sbt http-tests/test - pass (1485 tests; TimeoutDirectivesSpec flaked once in a full run and passes on its own)
• sbt +http/compile - pass on 2.13.18 and 3.3.8
• sbt +http/mimaReportBinaryIssues - pass
• sbt http/scalafmt http-tests/Test/scalafmt - clean

References

None - avoids reopening jars per resource request and an unbounded deleteOnExit registration per upload

[pjfanning]

Rebased onto main and pushed 300caca addressing the review findings:

• Shutdown ordering: UploadTempFiles is now a per-actor-system extension whose directory is removed by a CoordinatedShutdown task in the actor-system-terminate phase — after in-flight requests drain, matching the ordering deleteOnExit used to guarantee. The raw Runtime.addShutdownHook ran concurrently with the drain and could delete files uploads were still using. Side benefit: Pekko HTTP registers no raw JVM hook of its own, so the §5 claim in the Add a draft threat model and wire it for discoverability #1242 threat model stays true.
• Self-healing temp dir: create() recreates the directory if a temp-file reaper removed it while empty (it previously failed all uploads until restart). New test covers it, plus one asserting the directory is deleted when a separate actor system terminates.
• Jar connection ownership: the cache-off close moved into a guarded finally (it leaked a JarFile on any non-FileNotFoundException failure); ownership is decided from the connection's effective getUseCaches, and setUseCaches is only called when disabling — so an application-wide setDefaultUseCaches(false) is no longer silently overridden (and the jar it forces open is now closed).
• ResourceFile.apply(url): the public one-arg overload is restored to its historical no-handle-kept semantics (useJarFileCache = false) and documented; the caching behavior is reachable only through the two-arg overload driven by the setting.
• Generic connection path: getContentLengthLong instead of the truncating getContentLength, negative (unknown) lengths reject instead of serving a silent empty 200, and FileNotFoundException maps to None with a guarded stream close instead of a 500.
• Structure: dispatch is on the connection type rather than the protocol string, and the cache rule lives in one openConnection helper shared with openStream.
• reference.conf: the "same cache that the class loader uses" claim was wrong (the JDK's JarFileFactory cache is disjoint from URLClassPath's handles), and cache-off cannot make a classpath jar replaceable — reworded to scope the promise to jars no class loader holds open, and to document the metadata+content two-parse cost of cache-off mode.

73 tests pass across FileUploadDirectivesSpec and FileAndResourceDirectivesSpec; http/mimaReportBinaryIssues and +http/compile (2.13.18, 3.3.8) pass.