Merge branch 'jetty-12.0.x' into jetty-12.0.x-cross-context-dispatch

Jenkinsfile

@@ -20,7 +20,7 @@ pipeline {
               mavenBuild( "jdk21", "clean install -Dspotbugs.skip=true -Djacoco.skip=true", "maven3")
               recordIssues id: "jdk21", name: "Static Analysis jdk21", aggregatingResults: true, enabledForFailure: true,
                             tools: [mavenConsole(), java(), checkStyle(), javaDoc()],
-                            skipPublishingChecks: true, blameDisabled: true
+                            skipPublishingChecks: true, skipBlames: true
             }
           }
         }
@@ -33,7 +33,7 @@ pipeline {
               mavenBuild( "jdk17", "clean install -Perrorprone", "maven3") // javadoc:javadoc
               recordIssues id: "analysis-jdk17", name: "Static Analysis jdk17", aggregatingResults: true, enabledForFailure: true,
                             tools: [mavenConsole(), java(), checkStyle(), errorProne(), spotBugs(), javaDoc()],
-                            skipPublishingChecks: true, blameDisabled: true
+                            skipPublishingChecks: true, skipBlames: true
               recordCoverage id: "coverage-jdk17", name: "Coverage jdk17", tools: [[parser: 'JACOCO']], sourceCodeRetention: 'MODIFIED',
                              sourceDirectories: [[path: 'src/main/java'], [path: 'target/generated-sources/ee8']]
             }

VERSION.txt

@@ -21,6 +21,7 @@ jetty-12.0.6 - 29 January 2024
  + 11253 Jetty 12 ComplianceViolation.Listener not notified for URI, Cookie,
    and Multipart violations.
  + 11259 HTTP/2 connection not closed after idle timeout when TCP congested
+   (CVE-2024-22201)
  + 11260 QuickStartConfiguration cannot be mixed with contexts that do not have
    a `WEB-INF/quickstart-web.xml`
  + 11263 Using `jetty.version` override from jetty-start does not use version
@@ -198,6 +199,7 @@ jetty-12.0.1 - 29 August 2023
 jetty-9.4.54.v20240208 - 08 February 2024
  + 1256 DoSFilter leaks USER_AUTH entries
  + 11259 HTTP/2 connection not closed after idle timeout when TCP congested
+   (CVE-2024-22201)
  + 11389 Strip default ports on ws/wss scheme uris too
 
 jetty-11.0.20 - 29 January 2024

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/client-io-arch.adoc

@@ -14,22 +14,44 @@
 [[pg-client-io-arch]]
 === I/O Architecture
 
-The Jetty client libraries provide the basic components and APIs to implement a network client.
+The Jetty client libraries provide the basic components and APIs to implement a client application.
 
 They build on the common xref:pg-arch-io[Jetty I/O Architecture] and provide client specific concepts (such as establishing a connection to a server).
 
 There are conceptually two layers that compose the Jetty client libraries:
 
-. xref:pg-client-io-arch-network[The network layer], that handles the low level I/O and deals with buffers, threads, etc.
-. xref:pg-client-io-arch-protocol[The protocol layer], that handles the parsing of bytes read from the network and the generation of bytes to write to the network.
+. xref:pg-client-io-arch-transport[The transport layer], that handles the low-level communication with the server, and deals with buffers, threads, etc.
+. xref:pg-client-io-arch-protocol[The protocol layer], that handles the high-level protocol by parsing the bytes read from the transport layer and by generating the bytes to write to the transport layer.
 
-[[pg-client-io-arch-network]]
-==== Network Layer
+[[pg-client-io-arch-transport]]
+==== Transport Layer
+
+The transport layer is the low-level layer that communicates with the server.
+
+Protocols such as HTTP/1.1 and HTTP/2 are typically transported over TCP, while the newer HTTP/3 is transported over QUIC, which is itself transported over UDP.
+
+However, there are other means of communication supported by the Jetty client libraries, in particular over xref:pg-client-io-arch-unix-domain[Unix-Domain sockets] (for inter-process communication), and over xref:pg-client-io-arch-memory[memory] (for intra-process communication).
+
+The same high-level protocol can be carried by different low-level transports.
+For example, the high-level HTTP/1.1 protocol can be transported over either TCP (the default), or QUIC, or Unix-Domain sockets, or memory, because all these low-level transport provide reliable and ordered communication between client and server.
+
+Similarly, the high-level HTTP/3 protocol can be transported over either QUIC (the default) or memory.
+It would be possible to transport HTTP/3 also over Unix-Domain sockets, but the current version of Java only supports Unix-Domain sockets for ``SocketChannel``s and not for ``DatagramChannel``s.
 
 The Jetty client libraries use the common I/O design described in xref:pg-arch-io[this section].
-The main client-side component is the link:{javadoc-url}/org/eclipse/jetty/io/ClientConnector.html[`ClientConnector`].
 
-The `ClientConnector` primarily wraps the link:{javadoc-url}/org/eclipse/jetty/io/SelectorManager.html[`SelectorManager`] and aggregates other four components:
+The common I/O components and concepts are used for all low-level transports.
+The only partial exception is the xref:pg-client-io-arch-memory[memory transport], which is not based on network components; as such it does not need a `SelectorManager`, but it exposes `EndPoint` so that high-level protocols have a common interface to interact with the low-level transport.
+
+The client-side abstraction for the low-level transport is `org.eclipse.jetty.io.Transport`.
+
+`Transport` represents how high-level protocols can be transported; there is `Transport.TCP_IP` that represents communication over TCP, but also `Transport.TCPUnix` for Unix-Domain sockets, `QuicTransport` for QUIC and `MemoryTransport` for memory.
+
+Applications can specify the `Transport` to use for each request as described in xref:pg-client-http-api-transport[this section].
+
+When the `Transport` implementation uses the network, it delegates to `org.eclipse.jetty.io.ClientConnector`.
+
+`ClientConnector` primarily wraps `org.eclipse.jetty.io.SelectorManager` to provide network functionalities, and aggregates other four components:
 
 * a thread pool (in form of an `java.util.concurrent.Executor`)
 * a scheduler (in form of `org.eclipse.jetty.util.thread.Scheduler`)
@@ -39,6 +61,8 @@ The `ClientConnector` primarily wraps the link:{javadoc-url}/org/eclipse/jetty/i
 The `ClientConnector` is where you want to set those components after you have configured them.
 If you don't explicitly set those components on the `ClientConnector`, then appropriate defaults will be chosen when the `ClientConnector` starts.
 
+`ClientConnector` manages all network-related components, and therefore it is used for TCP, UDP, QUIC and xref:pg-client-io-arch-unix-domain[Unix-Domain sockets].
+
 The simplest example that creates and starts a `ClientConnector` is the following:
 
 [source,java,indent=0]
@@ -60,11 +84,11 @@ A more advanced example that customizes the `ClientConnector` by overriding some
 include::../{doc_code}/org/eclipse/jetty/docs/programming/client/ClientConnectorDocs.java[tags=advanced]
 ----
 
-Since `ClientConnector` is the component that handles the low-level network, it is also the component where you want to configure the low-level network configuration.
+Since `ClientConnector` is the component that handles the low-level network transport, it is also the component where you want to configure the low-level network configuration.
 
 The most common parameters are:
 
-* `ClientConnector.selectors`: the number of ``java.nio.Selector``s components (defaults to `1`) that are present to handle the ``SocketChannel``s opened by the `ClientConnector`.
+* `ClientConnector.selectors`: the number of ``java.nio.Selector``s components (defaults to `1`) that are present to handle the ``SocketChannel``s and ``DatagramChannel``s opened by the `ClientConnector`.
 You typically want to increase the number of selectors only for those use cases where each selector should handle more than few hundreds _concurrent_ socket events.
 For example, one selector typically runs well for `250` _concurrent_ socket events; as a rule of thumb, you can multiply that number by `10` to obtain the number of opened sockets a selector can handle (`2500`), based on the assumption that not all the `2500` sockets will be active _at the same time_.
 * `ClientConnector.idleTimeout`: the duration of time after which `ClientConnector` closes a socket due to inactivity (defaults to `30` seconds).
@@ -81,32 +105,38 @@ Please refer to the `ClientConnector` link:{javadoc-url}/org/eclipse/jetty/io/Cl
 [[pg-client-io-arch-unix-domain]]
 ===== Unix-Domain Support
 
-link:https://openjdk.java.net/jeps/380[JEP 380] introduced Unix-Domain sockets support in Java 16, on all operative systems.
+link:https://openjdk.java.net/jeps/380[JEP 380] introduced Unix-Domain sockets support in Java 16, on all operative systems, but only for ``SocketChannel``s (not for ``DatagramChannel``s).
 
-`ClientConnector` can be configured to support Unix-Domain sockets in the following way:
+`ClientConnector` handles Unix-Domain sockets exactly like it handles regular TCP sockets, so there is no additional configuration necessary -- Unix-Domain sockets are supported out-of-the-box.
 
-[source,java,indent=0]
-----
-include::../{doc_code}/org/eclipse/jetty/docs/programming/client/ClientConnectorDocs.java[tags=unixDomain]
-----
+Applications can specify the `Transport` to use for each request as described in xref:pg-client-http-api-transport[this section].
 
-[IMPORTANT]
-====
-You can use Unix-Domain sockets support only when you run your client application with Java 16 or later.
-====
+[[pg-client-io-arch-memory]]
+===== Memory Support
+
+In addition to support communication between client and server via network or Unix-Domain, the Jetty client libraries also support communication between client and server via memory for intra-process communication.
+This means that the client and server must be in the same JVM process.
+
+This functionality is provided by `org.eclipse.jetty.server.MemoryTransport`, which does not delegate to `ClientConnector`, but instead delegates to the server-side `MemoryConnector` and its related classes.
+
+Applications can specify the `Transport` to use for each request as described in xref:pg-client-http-api-transport[this section].
 
 [[pg-client-io-arch-protocol]]
 ==== Protocol Layer
 
-The protocol layer builds on top of the network layer to generate the bytes to be written to the network and to parse the bytes read from the network.
+The protocol layer builds on top of the transport layer to generate the bytes to be written to the low-level transport and to parse the bytes read from the low-level transport.
 
-Recall from xref:pg-arch-io-connection[this section] that Jetty uses the `Connection` abstraction to produce and interpret the network bytes.
+Recall from xref:pg-arch-io-connection[this section] that Jetty uses the `Connection` abstraction to produce and interpret the low-level transport bytes.
 
 On the client side, a `ClientConnectionFactory` implementation is the component that creates `Connection` instances based on the protocol that the client wants to "speak" with the server.
 
-Applications use `ClientConnector.connect(SocketAddress, Map<String, Object>)` to establish a TCP connection to the server, and must tell `ClientConnector` how to create the `Connection` for that particular TCP connection, and how to notify back the application when the connection creation succeeds or fails.
+Applications may use `ClientConnector.connect(SocketAddress, Map<String, Object>)` to establish a TCP connection to the server, and must provide `ClientConnector` with the following information in the context map:
+
+* A `Transport` instance that specifies the low-level transport to use.
+* A `ClientConnectionFactory` that creates `Connection` instances for the high-level protocol.
+* A `Promise` that is notified when the connection creation succeeds or fails.
 
-This is done by passing a link:{javadoc-url}/org/eclipse/jetty/io/ClientConnectionFactory.html[`ClientConnectionFactory`] (that creates `Connection` instances) and a link:{javadoc-url}/org/eclipse/jetty/util/Promise.html[`Promise`] (that is notified of connection creation success or failure) in the context `Map` as follows:
+For example:
 
 [source,java,indent=0]
 ----

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-api.adoc

@@ -270,3 +270,33 @@ An application that implements a forwarder between two servers can be implemente
 ----
 include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tag=forwardContent]
 ----
+
+[[pg-client-http-api-transport]]
+===== Request `Transport`
+
+The communication between client and server happens over a xref:pg-client-io-arch-transport[low-level transport], and applications can specify the low-level transport to use for each request.
+
+This gives client applications great flexibility, because they can use the same `HttpClient` instance to communicate, for example, with an external third party web application via TCP, to a different process via Unix-Domain sockets, and efficiently to the same process via memory.
+
+Client application can also choose more esoteric configurations such as using QUIC, typically used to transport HTTP/3, to transport HTTP/1.1 or HTTP/2, because QUIC provides reliable and ordered communication like TCP does.
+
+Provided you have configured a xref:pg-server-http-connector[`UnixDomainServerConnector`] on the server, this is how you can configure a request to use Unix-Domain sockets:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tag=unixDomain]
+----
+
+In the same way, if you have configured a xref:pg-server-http-connector[`MemoryConnector`] on the server, this is how you can configure a request to use memory for communication:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tag=memory]
+----
+
+This is a fancy example of how to mix HTTP versions and low-level transports:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tag=mixedTransports]
+----

documentation/jetty-documentation/src/main/asciidoc/programming-guide/client/http/client-http-configuration.adoc

@@ -19,9 +19,9 @@ Please refer to the `HttpClient` link:{javadoc-url}/org/eclipse/jetty/client/Htt
 
 The most common parameters are:
 
-* `HttpClient.idleTimeout`: same as `ClientConnector.idleTimeout` described in xref:pg-client-io-arch-network[this section].
-* `HttpClient.connectBlocking`: same as `ClientConnector.connectBlocking` described in xref:pg-client-io-arch-network[this section].
-* `HttpClient.connectTimeout`: same as `ClientConnector.connectTimeout` described in xref:pg-client-io-arch-network[this section].
+* `HttpClient.idleTimeout`: same as `ClientConnector.idleTimeout` described in xref:pg-client-io-arch-transport[this section].
+* `HttpClient.connectBlocking`: same as `ClientConnector.connectBlocking` described in xref:pg-client-io-arch-transport[this section].
+* `HttpClient.connectTimeout`: same as `ClientConnector.connectTimeout` described in xref:pg-client-io-arch-transport[this section].
 * `HttpClient.maxConnectionsPerDestination`: the max number of TCP connections that are opened for a particular destination (defaults to 64).
 * `HttpClient.maxRequestsQueuedPerDestination`: the max number of requests queued (defaults to 1024).