(maven-resolver) branch master updated: Document known transport issues (#1792)

[cs...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

cstamas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-resolver.git


The following commit(s) were added to refs/heads/master by this push:
     new ad8dee921 Document known transport issues (#1792)
ad8dee921 is described below

commit ad8dee92157a529ea35f388a559270d0787e55ce
Author: Tamas Cservenak <ta...@cservenak.net>
AuthorDate: Thu Feb 12 12:20:33 2026 +0100

    Document known transport issues (#1792)
    
    Document "known issues" for transports, for start the HTTP capable transports.
---
 src/site/markdown/transporter-known-issues.md | 52 +++++++++++++++++++++++++++
 src/site/site.xml                             |  1 +
 2 files changed, 53 insertions(+)

diff --git a/src/site/markdown/transporter-known-issues.md b/src/site/markdown/transporter-known-issues.md
new file mode 100644
index 000000000..c83d6eaa1
--- /dev/null
+++ b/src/site/markdown/transporter-known-issues.md
@@ -0,0 +1,52 @@
+# Transporter Known Issues
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+This page lists known issues related to various transporters.
+
+## The `jdk` (Java HttpClient) Transporter
+
+Given this transporter uses the Java HttpClient (available since Java 11), it is the user's best interest
+to use latest patch version of Java, as HttpClient is getting bugfixes regularly.
+
+Known issues:
+* Does not properly support `aether.transport.http.requestTimeout` configuration prior Java 26, see [JDK-8208693](https://bugs.openjdk.org/browse/JDK-8208693)
+* No TLS Proxy support, see [here](https://dev.to/kdrakon/httpclient-can-t-connect-to-a-tls-proxy-118a)
+* No SOCKS proxy support, see [JDK-8214516](https://bugs.openjdk.org/browse/JDK-8214516)
+* In case of Proxy TLS tunneling, to enable Proxy Basic authentication, one must use `jdk.http.auth.tunneling.disabledScheme` 
+  Java System Property, see [here](https://docs.oracle.com/en/java/javase/21/core/java-networking.html#GUID-801380C1-4300-4ED8-A390-3C39135267CD). Java versions since 8u111 have this property set to value "Basic" making HTTP 
+  Basic authentication disabled, see [here](https://www.oracle.com/java/technologies/javase/8u111-relnotes.html). To 
+  enable HTTP Basic authentication for Proxy TLS tunneling, one must set `jdk.http.auth.tunneling.disabledScheme` to 
+  empty string, e.g. by adding `-Djdk.http.auth.tunneling.disabledScheme=""` JVM argument.
+
+Maven 4 uses this transport by default for HTTP(S) protocol.
+
+## The `apache` (Apache HttpClient) Transporter
+
+Transporter based on Apache HttpClient.
+
+To use this transporter in Maven 4, you need to specify `-Dmaven.resolver.transport=apache` user property.
+
+## The `jetty` (Jetty HttpClient) Transporter
+
+Transporter based on Jetty HttpClient. 
+
+In Maven 4 this transport is not available by default (is not bundled). To use it, 
+you need to add `org.apache.maven.resolver.transport:transport-http-jetty` artifact with its runtime dependencies to
+`/lib` directory of Maven. Once added to core classpath, it will take over the role of default transport.
diff --git a/src/site/site.xml b/src/site/site.xml
index 677ec4ff1..bb4a37229 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -45,6 +45,7 @@ under the License.
       <item name="Resolving Dependencies" href="resolving-dependencies.html"/>
       <item name="Common Misconceptions" href="common-misconceptions.html"/>
       <item name="Artifact Deployment" href="deployment.html"/>
+      <item name="Transporter Known Issues" href="transporter-known-issues.html"/>
     </menu>
     <menu name="Reference">
       <item name="Configuration" href="configuration.html"/>