[feature] Native EXPath HTTP Client (java.net.http + Methanol); remove Apache HttpClient

[joewiz]

[This PR was co-authored with Claude Code. -Joe]

Summary

Replaces eXist's EXPath HTTP Client (http:send-request) with a native implementation built on the JDK java.net.http.HttpClient, augmented by Methanol (thanks to @dizzzz for the suggestion to investigate Methanol), and removes Apache HttpClient from the code base entirely — production and tests. Along the way it brings the client closer to the EXPath spec: full authentication (preemptive and challenge-response, Basic and Digest) and spec-compliant error codes.

After this PR, git grep org.apache.httpcomponents over the poms and import org.apache.http / import org.apache.hc over the sources both return nothing.

This is the rewrite requested in #5771, and it also fixes #4256 (non-spec-compliant errors). It supersedes #6473 (which migrated to Apache HttpClient 5 as an intermediate step) and #6474 (the draft HC5 EXPath prerelease) — both can be closed once this lands. With the native module now living in core, the eXist-db/exist-http-client prototype repo can also be archived after merge.

Why

eXist's EXPath HTTP client depended on Apache HttpClient (HC4) and the third-party http-client-java EXPath library, and the integration test suite drove the server through HC4's fluent client (plus, for WebDAV, the milton-client library, which itself pulls in Apache HttpClient). Methanol is a thin, Apache-2.0 augmentation of the JDK client: it adds transparent gzip/deflate decoding, a read (inactivity) timeout, MediaType, and MultipartBodyPublisher — the pieces the bare JDK client lacks — while pulling in no Apache HttpClient.

What changed

Native EXPath HTTP Client module (extensions/modules/http-client)

• New org.exist.xquery.modules.httpclient module implementing http:send-request (namespace http://expath.org/ns/http-client) on java.net.http.HttpClient. The http:request element, namespace, and function signatures are unchanged, so existing queries are unaffected.
• The client is a Methanol client with autoAcceptEncoding (advertises Accept-Encoding and transparently decodes gzip/deflate) and a read timeout.
• Multipart request bodies are built with Methanol's MultipartBodyPublisher (the JDK client has no multipart support); each http:body part keeps its own Content-Type.

Authentication (per EXPath spec §3.3)

• @send-authorization='true' sends Basic credentials preemptively.
• Otherwise (the spec default), credentials are withheld until the server returns a 401 challenge, and the request is re-sent once with the computed Authorization header — Basic or RFC 2617 Digest (MD5, qop=auth). This challenge-response mode was missing from the initial port; it matches the previous eXist client and the BaseX reference implementation.

Error handling (fixes #4256)

• Connection / I/O failures surface as expath-err:HC001, timeouts as expath-err:HC006, in the EXPath error namespace (http://expath.org/ns/error) — catchable from XQuery, rather than the raw org.expath.httpclient.HttpClientException the old client raised.

Old EXPath client removed

• Deletes the old org.expath.exist HTTP client (SendRequestFunction, HttpClientModule, the EXistResult/EXistTreeBuilder adapters, and the orphaned org.expath.tools model classes). The exist-expath module keeps only its Zip functions. Drops http-client-java, tools-java, apache-mime4j-core and the HC4 httpcore dependency.
• debuggee's HttpSession (the XDEBUG_SESSION form POST) is migrated to the JDK client.
• Every conf.xml re-points http://expath.org/ns/http-client to the native module.

Tests migrated off Apache HttpClient

• AbstractHttpTest now builds on java.net.http.HttpClient; the integration tests across exist-core, restxq, file and persistentlogin use it. GetParameterTest (multipart) uses Methanol's MultipartBodyPublisher.
• The WebDAV tests were the last test code pulling in Apache HttpClient — they drove the server through milton-client. They are replaced with JDK java.net.http round-trip tests (WebDavRoundTripTest), and the now-unused Milton stack is removed (the WebDAV server already runs on Apache Jackrabbit). The standalone webapp web.xml is corrected to map the WebDAV path to the Jackrabbit ExistWebdavServlet (develop still referenced the long-deleted MiltonWebDAVServlet).

Build

• exist-distribution bundles the new exist-http-client module (runtime dependency) so the repointed conf.xml resolves the module class at runtime.
• exist-parent BOM: drop the Apache HttpClient (HC4) and Milton managed dependencies and their version properties; add Methanol.

Spec references

• EXPath HTTP Client Module 1.0 — http:send-request, the http:request element, the response format, authentication (§3.3), and error codes (HC001/HC006).

Test plan

• New module: 72 http:send-request integration tests (in-process com.sun.net.httpserver target + embedded eXist) and 43 ContentTypeHelper unit tests — all green. Coverage includes HTTP methods, request/response bodies, multipart, gzip/deflate decoding, Content-Type classification (XML/HTML/text/JSON/binary), redirects, timeouts (HC006), status codes, multiple response headers, and authentication: Basic preemptive, Basic and Digest challenge-response (the test server validates the Digest response hash end-to-end), and connection errors catchable as expath-err:HC001 (EXPath HttpClient errors are not spec compliant #4256).
• Migrated integration tests run green across exist-core, restxq, file and persistentlogin.
• WebDAV: WebDavRoundTripTest green — exact round-trip of XML DOCTYPE, XML declaration, CDATA, namespaces, non-ASCII content, and a binary document, over the JDK client against the Jackrabbit servlet.
• Full reactor build (clean install) green; full unit suite green; container CI (incl. litmus WebDAV compliance) exercised.

Notes for reviewers

• The only remaining Codacy/PMD warning is NPathComplexity on the test class SendRequestFunctionTest.startHttpServer() (the in-process test server's endpoint registration). It is below where it started before this PR's auth additions; per review it can be ignored for now.
• The Milton/WebDAV removal is a consequence of removing all Apache HttpClient: milton-client is an Apache HttpClient consumer, so retiring those tests is required. Their WebDAV protocol coverage is provided by the litmus compliance suite in container CI (98/98); WebDavRoundTripTest covers the complementary eXist content-fidelity angle.
• Dropping http-client-java removes eXist's dependency on the upstream EXPath HTTP client, so merging this removes the eXist-related motivation from Cut a release from main (Apache HttpComponents 5) expath/expath-http-client-java#59 (that issue can remain open on its own merits).

Closes #5771
Closes #4256

[joewiz]

[This response was co-authored with Claude Code. -Joe]

A note on the WebDAV test change in this PR, since it may raise eyebrows in review:

The deleted CopyTest / DeleteTest / LockTest / RenameTest / ReplaceTest / SerializationTest / StoreAndRetrieveTest were built on the milton-client library, which pulls in Apache HttpClient — the very dependency this PR removes. So they could not simply be "ported to the new client": there is no drop-in JDK equivalent for milton-client's object model.

Their WebDAV protocol coverage (COPY, MOVE, LOCK/UNLOCK, PROPFIND, DELETE) is, however, already provided — and far more thoroughly — by the litmus compliance suite that runs in container CI (exist-docker/src/test/bats/04-webdav-litmus.bats), currently at 98/98: basic 16, copymove 13, props 33, locks 36. The milton JUnit tests were redundant with it.

WebDavRoundTripTest is intentionally narrower and complementary: it covers the eXist-specific concern litmus does not — that content stored over WebDAV round-trips faithfully through eXist's own storage and serialization. It asserts exact round-trip of an XML DOCTYPE, an XML declaration, a CDATA section, namespace declarations, non-ASCII content, and a binary document, via a small JDK java.net.http helper (WebDavHttpClient).

[duncdrum]

@joewiz the repeated failures in the docker job are a concern. Exist has errors in the logs upon a clean boot.

not ok 5 logs are error free
# (in test file exist-docker/src/test/bats/01-connect-spec.bats, line 26)
#   `[ "$result" -eq 0 ]' failed

[line-o]

I bet we have these constants in some package we already depend on.

[joewiz]

[This response was co-authored with Claude Code. -Joe]

Thanks for catching it — root-caused and fixed. The clean-boot error was:

Configuration problem: class not found for module 'http://expath.org/ns/http-client'
(ClassNotFoundException); class:'org.exist.xquery.modules.httpclient.HttpClientModule'

This was a real packaging bug, not a test-only issue: the old HttpClientModule shipped inside exist-expath; this PR moves the EXPath HTTP client into a new exist-http-client module and repoints conf.xml to it, but the distribution wasn't yet bundling that module — so the class wasn't on the runtime classpath and boot logged the error (in a real install, http:send-request would have failed to load too).

Fixed by adding exist-http-client as a runtime dependency of exist-distribution (00b194c), mirroring how exist-file/exist-expath are bundled; confirmed with dependency:tree that it now resolves as a runtime artifact. The container job should be back to error-free on this run.

[line-o]

LGTM!
This will make our lives much easier going forward.
It will be interesting to learn if we get failures in apps making heavy use of http-client.
The remaining codacy warning is in a test class which I would vote to ignore for the moment.

[line-o]

Does this PR fix #4256

[joewiz]

[This response was co-authored with Claude Code. -Joe]

Yes — it fixes #4256. The old client raised a raw org.expath.httpclient.HttpClientException; the native module maps connection/I/O failures to expath-err:HC001 (and timeouts to expath-err:HC006) in the EXPath error namespace. I added a regression test mirroring the issue's reproducer — a send-request to an unreachable host caught with catch expath-err:HC001 — and added Closes #4256 to the description.

On apps that make heavy use of http-client: the surface is deliberately unchanged — same http:request element, same http://expath.org/ns/http-client namespace, same function signatures — so existing queries don't need edits. The 72 module integration tests exercise the behaviors such apps lean on: methods, request/response bodies, multipart, gzip/deflate decoding, Content-Type classification, redirects, timeouts, status codes, multiple response headers, and authentication (Basic preemptive, plus Basic and Digest challenge-response, validated end-to-end). Where behavior changed, it changed toward the spec: challenge-response auth and the HC001/HC006 error codes both restore conformance the old client lacked. The honest caveat is that the JDK/Methanol client can differ from Apache in edge cases (specific header quirks, proxy/TLS behavior); if any such reports surface we can address them, but the EXPath contract itself is preserved.

Agreed on the remaining Codacy warning — it's the in-process test server's setup method; happy to leave it for now (it's actually lower than before this PR's additions).

Thanks for the review!

[dizzzz]

did not expect unit to disappear here. No tests remaining?

[joewiz]

[This response was co-authored with Claude Code. -Joe]

Right — HttpClientTest was the only test in exist-expath, and it exercised the old Apache-HttpClient-based EXPath client that this PR removes. With it gone, there are no test classes or test runner left in the module (only the log4j2.xml/conf.xml test resources), so junit is genuinely unused here. The HTTP client's tests now live in the new exist-http-client module.

Those leftover log4j2.xml/conf.xml test resources are now orphaned too — happy to strip them for a fully clean src/test, or leave them in case the module grows tests again. Whichever you'd prefer.

[dizzzz]

I'd stay out of the com.sun packages. These are not guaranteed to be present.

a better route and sustainable route is to use wire mock.

[joewiz]

[This response was co-authored with Claude Code. -Joe]

Fair flag — sharing what we found so you and the devs can steer it. com.sun.net.httpserver here is the exported public API of the JDK jdk.httpserver module (documented since JDK 9), not a sun.* internal, so it is present in every standard JDK; it let the tests stand up a tiny in-process target with no extra dependency. There's no existing precedent in eXist's own tests either way — neither com.sun.net.httpserver nor WireMock is used today. WireMock would be the more conventional choice but adds a test dependency and a rewrite of the in-process server. No strong preference from our side; happy to go with whatever you and the team settle on as the house convention for this kind of HTTP test target.

[dizzzz]

I see that on some locations "preemptive authorization" is applied.

For running the tests this makes sense as this will potentially save a handshake, But I am not sure if this is switched on for every outbound HTTPcall, as this might leak sensitive data.

[dizzzz]

About performance/heavy load as asked by @line-o ; I need to deep dive here. If we are able to use the connection pool and have good (default) Executor management, I expect it will work out well. But the proof is in the pudding.

[dizzzz]

LGTM! Will spin up IntelliJ for a more in-depth review.

[joewiz]

[This response was co-authored with Claude Code. -Joe]

On preemptive authorization: it's opt-in per request, not applied to every outbound call. Credentials are sent preemptively only when the request sets send-authorization="true" (the EXPath default is false). Without it, no Authorization header goes out until the server replies with a 401 challenge, and then it is sent only to that challenging origin. The places you saw it are the tests deliberately setting send-authorization="true". This follows the EXPath spec's auth model, so there's no blanket credential leak.

On performance / connection pooling and Executor management: good idea, and it looks readily achievable — the per-request client construction is the single seam where a shared, pooled client (with sensible Executor defaults, proxy, etc.) would slot in. Probably cleanest as a follow-on, but we're happy to fold it into this PR if you'd prefer it here. And agreed — the proof is in the pudding; glad to benchmark once there's a pooled path to measure.