Fixes #8979 - Jetty 12 - HttpClientTransport network "modes".

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` and not for `DatagramChannel`.
 
 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.TransportProtocol`.
+
+`TransportProtocol` represents how high-level protocols can be transported; there is `TransportProtocol.TCP_IP` that represents communication over TCP, but also `TransportProtocol.TCPUnix` for Unix-Domain sockets, `QuicTransportProtocol` for QUIC and `MemoryTransportProtocol` for memory.
+
+Applications can specify the `TransportProtocol` to use for each request as described in xref:pg-client-http-api-protocol[this section].
+
+When the `TransportProtocol` 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,7 +84,7 @@ 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:
 
@@ -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, for `SocketChannel`.
 
-`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 `TransportProtocol` to use for each request as described in xref:pg-client-http-api-protocol[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.MemoryTransportProtocol`, which does not delegate to `ClientConnector`, but instead delegates to the server-side `MemoryConnector` and its related classes.
+
+Applications can specify the `TransportProtocol` to use for each request as described in xref:pg-client-http-api-protocol[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 `TransportProtocol` 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-protocol]]
+===== Request `TransportProtocol`
+
+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=mixedTransportProtocols]
+----

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).