Plan the migration to HttpClient 5

[slachiewicz]

HttpClient 4.5.x is in maintenance and the rest of the ecosystem is moving to 5.x. This issue is for agreeing the shape of that move before any code is written; a previous attempt showed that starting from renames does not work.

Target: 3.7.0. HttpClient 5 targets Java 8, as does the 3.x line, so there is no runtime obstacle. What it does change is wagon-http-shared, which exposes HttpClient 4 in 17 public or protected members — AbstractHttpClientWagon.getHttpClient(), execute(), WagonRedirectStrategy, HttpMethodConfiguration.asRequestHeaders(), BasicAuthScope.getScope() among them. Those signatures cannot survive the package rename, so 3.7.0 would carry a binary-incompatible change in that module. That is a deliberate call: wagon-http-shared is a shared implementation detail between the HTTP and WebDAV providers, no consumer of it exists across the Apache Maven repositories, and the build has no japicmp gate asserting otherwise. Recording it here so it is a decision rather than a surprise.

Footprint. 94 org.apache.http imports across 12 production files — 10 in wagon-http-shared, 2 in wagon-webdav-jackrabbit — plus 6 test files across three modules. Nothing else in the project touches HttpClient.

The work is redesign, not renaming. The existing feature/migrate-to-apache-http-client-5-x branch does not compile; it references HttpClient 5 classes that do not exist. The genuine pieces:

• HttpClient 5 merged the retry handler and the service-unavailable strategy into one HttpRequestRetryStrategy.
• DefaultRedirectStrategy lost getRedirect(), so WagonRedirectStrategy's body replay of WagonHttpEntity has to be rebuilt.
• AbstractHttpEntity has no no-arg constructor and requires close(), so WagonHttpEntity needs rewriting.
• Stale-connection checking moved from RequestConfig to the connection manager.
• OriginScopedHeadersInterceptor (Configured HTTP headers are sent to other hosts when a repository redirects #956) relies on HttpClient 4's RedirectExec copying headers after the strategy runs. HttpClient 5's redirect execution differs, so that design needs revalidating rather than porting.

Behavioural traps seen while reviewing the same migration in maven-resolver, all in 5.4:

• BasicSchemeFactory and DigestSchemeFactory ignore the charset argument; it is always UTF-8.
• HttpClientContext keeps the user token and route in typed private fields, so interception through the attribute map silently stops working.
• A no-arg DefaultHostnameVerifier has a null PublicSuffixMatcher; use HttpsSupport.getDefaultHostnameVerifier().
• Setting a route planner explicitly short-circuits useSystemProperties proxy handling.
• DefaultHttpRequestRetryStrategy sleeps a flat interval where HttpClient 4 retried immediately.

Effect on the shaded artifact. wagon-http relocates org.apache.http to org.apache.maven.wagon.providers.http.httpclient. That pattern becomes org.apache.hc, and commons-codec and commons-io may drop out of the artifact set depending on what HttpClient 5 pulls in.

Effect on Maven. Maven 3.9.x, 3.10.x and 4.0.x each pin wagonVersion and ship wagon-http, wagon-http-shared and wagon-provider-api beside maven-resolver-transport-apache, today all on one HttpClient 4 stack. Resolver has no HttpClient 5 transport — master carries apache (4.x), plus jdk and jetty, which use no HttpClient. Because 3.7.0 is a version those lines can realistically adopt, the first bump would put both stacks in the distribution. They coexist, since the coordinates and packages differ, but that is two HTTP stacks to configure and two CVE streams to track. Worth agreeing the resolver side on dev@ before Maven takes the bump, so HttpClient 4 can leave in one step.

Upstream reach. wagon-webdav-jackrabbit no longer depends on jackrabbit-webdav (#898), so nothing external pins this project to 4.x any more.

Suggested order: agree 3.7.0 as the target and the wagon-http-shared compatibility call, then rebuild from the 3.x line keeping only the trivially correct renames, then the four redesigns above, then revalidate #956, then update the shade relocations, and settle the resolver transport question on dev@.

This issue was created with AI assistance.