Merge remote-tracking branch 'origin/jetty-12.0.x' into jetty-12.0.x-VirtualThreadPoolSemaphore

Author: joakime

documentation/jetty/modules/ROOT/pages/index.adoc

@@ -13,12 +13,34 @@
 
 = Eclipse Jetty {page-version}
 
-This section of the site contains the documentation for {page-component-title} {page-version}.
+This is the main documentation page for the Eclipse Jetty Project.
+
+Jetty provides a highly scalable and memory-efficient web server and Servlet container, supporting web protocols such as HTTP/1.1, HTTP/2, HTTP/3 and WebSocket.
+Furthermore, Jetty offers integrations with many other technologies, such as OSGi, JMX, JNDI, JAAS, CDI, etc. and with the relevant Jakarta EE technologies.
+
+Jetty is open source and are freely available for commercial use and distribution under either the link:https://www.eclipse.org/legal/epl-2.0/[Eclipse Public License v2] or the link:https://www.apache.org/licenses/LICENSE-2.0[Apache License v2].
+
+Jetty can either be used as a standalone server to deploy web applications, or as a library that can be used in your code as a dependency.
+
+.Jetty Versions and Compatibilities
+[cols="1a,1a,1a,1a", options="header"]
+|===
+| Jetty Version | Required Java Version | Jakarta EE Version | Status
+| Jetty 12.1.x | Java 17 | Jakarta EE11, EE10, EE9, EE8 | Development
+
+| Jetty 12.0.x | Java 17 | Jakarta EE10, EE9, EE8 | Stable
+
+| Jetty 11.0.x | Java 11 | Jakarta EE9 | EOL (see link:https://github.com/jetty/jetty.project/issues/10485[#10485])
+
+| Jetty 10.0.x | Java 11 | Jakarta EE8 | EOL (see link:https://github.com/jetty/jetty.project/issues/10485[#10485])
+
+| Jetty 9.4.x | Java 8 | Jakarta EE7 | EOL (see link:https://github.com/jetty/jetty.project/issues/7958[#7958])
+|===
 
 == xref:operations-guide:index.adoc[]
 
-The Eclipse Jetty Operations Guide targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications.
+The Operations Guide targets sysops, devops, and developers who want to install Jetty as a standalone server to deploy web applications.
 
 == xref:programming-guide:index.adoc[]
 
-The Eclipse Jetty Programming Guide targets developers who want to use the Eclipse Jetty libraries in their applications, and advanced sysops/devops that want to customize the deployment of web applications.
+The Programming Guide targets developers who want to use the Jetty libraries in their applications, and advanced sysops/devops that want to customize the deployment of web applications.

documentation/jetty/modules/code/examples/src/main/java/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java

@@ -17,6 +17,7 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.net.SocketAddress;
 import java.net.URI;
 import java.nio.ByteBuffer;
 import java.nio.file.Path;
@@ -34,6 +35,7 @@
 import org.eclipse.jetty.client.BufferingResponseListener;
 import org.eclipse.jetty.client.BytesRequestContent;
 import org.eclipse.jetty.client.CompletableResponseListener;
+import org.eclipse.jetty.client.Connection;
 import org.eclipse.jetty.client.ConnectionPool;
 import org.eclipse.jetty.client.ContentResponse;
 import org.eclipse.jetty.client.Destination;
@@ -72,6 +74,7 @@
 import org.eclipse.jetty.io.ClientConnectionFactory;
 import org.eclipse.jetty.io.ClientConnector;
 import org.eclipse.jetty.io.Content;
+import org.eclipse.jetty.io.EndPoint;
 import org.eclipse.jetty.io.Transport;
 import org.eclipse.jetty.io.ssl.SslHandshakeListener;
 import org.eclipse.jetty.quic.client.ClientQuicConfiguration;
@@ -1180,4 +1183,29 @@ public void mixedTransports() throws Exception
             .send();
         // end::mixedTransports[]
     }
+
+    public void connectionInformation() throws Exception
+    {
+        // tag::connectionInformation[]
+        HttpClient httpClient = new HttpClient();
+        httpClient.start();
+
+        ContentResponse response = httpClient.newRequest("http://domain.com/path")
+            // The connection information is only available starting from the request begin event.
+            .onRequestBegin(request ->
+            {
+                Connection connection = request.getConnection();
+
+                // Obtain the address of the server.
+                SocketAddress remoteAddress = connection.getRemoteSocketAddress();
+                System.getLogger("connection").log(INFO, "Server address: %s", remoteAddress);
+
+                // Obtain the SslSessionData.
+                EndPoint.SslSessionData sslSessionData = connection.getSslSessionData();
+                if (sslSessionData != null)
+                    System.getLogger("connection").log(INFO, "SslSessionData: %s", sslSessionData);
+            })
+            .send();
+        // end::connectionInformation[]
+    }
 }

documentation/jetty/modules/programming-guide/pages/client/http.adoc

@@ -235,7 +235,12 @@ A second request with the same origin sent _after_ the first request/response cy
 A second request with the same origin sent _concurrently_ with the first request will likely cause the opening of a second connection, depending on the connection pool implementation.
 The configuration parameter `HttpClient.maxConnectionsPerDestination` (see also the <<configuration,configuration section>>) controls the max number of connections that can be opened for a destination.
 
-NOTE: If opening connections to a given origin takes a long time, then requests for that origin will queue up in the corresponding destination until the connections are established.
+[NOTE]
+====
+If opening connections to a given origin takes a long time, then requests for that origin will queue up in the corresponding destination until the connections are established.
+
+To save the time spent opening connections, you can xref:connection-pool-precreate-connections[pre-create connections].
+====
 
 Each connection can handle a limited number of concurrent requests.
 For HTTP/1.1, this number is always `1`: there can only be one outstanding request for each connection.
@@ -528,6 +533,28 @@ This is a fancy example of how to mix HTTP versions and low-level transports:
 include::code:example$src/main/java/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tag=mixedTransports]
 ----
 
+[[connection-information]]
+=== Request Connection Information
+
+In order to send a request, it is necessary to obtain a connection, as explained in the xref:request-processing[request processing section].
+
+The HTTP/1.1 protocol may send only one request at a time on a single connection, while multiplexed protocols such as HTTP/2 may send many requests at a time on a single connection.
+
+You can access the connection information, for example the local and remote `SocketAddress`, or the `SslSessionData` if the connection is secured, in the following way:
+
+[,java,indent=0]
+----
+include::code:example$src/main/java/org/eclipse/jetty/docs/programming/client/http/HTTPClientDocs.java[tag=connectionInformation]
+----
+
+[NOTE]
+====
+The connection information is only available when the request is associated with a connection.
+
+This means that the connection is not available in the _request queued_ event, but only starting from the _request begin_ event.
+For more information about request events, see xref:non-blocking[this section].
+====
+
 [[configuration]]
 == HttpClient Configuration
 

documentation/jetty/modules/programming-guide/pages/index.adoc

@@ -23,3 +23,24 @@ You may use the xref:client/index.adoc[Jetty client-side library] in your applic
 Likewise, you may use the xref:server/index.adoc[Jetty server-side library] to quickly create an HTTP or REST service without having to create a web application archive file (a `+*.war+` file) and without having to deploy it to a Jetty standalone server that you would have to download and install.
 
 This guide will walk you through the design of the Jetty libraries and how to use its classes to write your applications.
+
+== Code Deprecation Policy
+
+As the Jetty code evolves, classes and/or methods are deprecated using the `@Deprecated` annotation and will be removed in a future Jetty release.
+
+The Jetty release numbering follows this scheme: `<major>.<minor>.<micro>`. For example, 12.0.5 has `major=12`, `minor=0` and `micro=5`.
+
+As much as possible, deprecated code is not removed in micro releases.
+Deprecated code may be removed in major releases.
+Deprecated code may be removed in minor releases, but only if it has been deprecated for at least 6 micro releases.
+
+For example, let's assume that Jetty 12.1.0 (a new minor release) is released after the release of Jetty 12.0.11.
+
+Then, code that was deprecated in Jetty 12.0.5 or earlier may be removed from Jetty 12.1.0 (because it has been deprecated for more than 6 micro releases).
+
+On the other hand, code that was deprecated in Jetty 12.0.8 may be removed in Jetty 12.1.3 (because it has been deprecated for 3 micro releases in Jetty 12.0.x, and for 3 micro releases in Jetty 12.1.x -- 12.1.0, 12.1.1 and 12.1.2).
+
+[NOTE]
+====
+There could be rare cases where code (possibly not even deprecated) must be removed earlier than specified above to address security vulnerabilities.
+====

jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/Connection.java

@@ -16,6 +16,7 @@
 import java.io.Closeable;
 import java.net.SocketAddress;
 
+import org.eclipse.jetty.io.EndPoint;
 import org.eclipse.jetty.util.Promise;
 
 /**
@@ -63,4 +64,13 @@ default SocketAddress getRemoteSocketAddress()
     {
         return null;
     }
+
+    /**
+     * @return the {@link EndPoint.SslSessionData} associated with
+     * the connection, or {@code null} if the connection is not secure.
+     */
+    default EndPoint.SslSessionData getSslSessionData()
+    {
+        return null;
+    }
 }

jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/HttpProxy.java

@@ -346,6 +346,12 @@ public SocketAddress getRemoteSocketAddress()
             return connection.getRemoteSocketAddress();
         }
 
+        @Override
+        public EndPoint.SslSessionData getSslSessionData()
+        {
+            return connection.getSslSessionData();
+        }
+
         @Override
         public void send(Request request, Response.CompleteListener listener)
         {

jetty-core/jetty-client/src/main/java/org/eclipse/jetty/client/transport/internal/HttpConnectionOverHTTP.java

@@ -116,6 +116,12 @@ public SocketAddress getRemoteSocketAddress()
         return delegate.getRemoteSocketAddress();
     }
 
+    @Override
+    public EndPoint.SslSessionData getSslSessionData()
+    {
+        return delegate.getSslSessionData();
+    }
+
     @Override
     public long getBytesIn()
     {
@@ -350,6 +356,12 @@ public SocketAddress getRemoteSocketAddress()
             return getEndPoint().getRemoteSocketAddress();
         }
 
+        @Override
+        public EndPoint.SslSessionData getSslSessionData()
+        {
+            return getEndPoint().getSslSessionData();
+        }
+
         @Override
         public SendFailure send(HttpExchange exchange)
         {

jetty-core/jetty-fcgi/jetty-fcgi-client/src/main/java/org/eclipse/jetty/fcgi/client/transport/internal/HttpConnectionOverFCGI.java

@@ -101,6 +101,12 @@ public SocketAddress getRemoteSocketAddress()
         return delegate.getRemoteSocketAddress();
     }
 
+    @Override
+    public EndPoint.SslSessionData getSslSessionData()
+    {
+        return delegate.getSslSessionData();
+    }
+
     protected Flusher getFlusher()
     {
         return flusher;
@@ -359,6 +365,12 @@ public SocketAddress getRemoteSocketAddress()
             return getEndPoint().getRemoteSocketAddress();
         }
 
+        @Override
+        public EndPoint.SslSessionData getSslSessionData()
+        {
+            return getEndPoint().getSslSessionData();
+        }
+
         @Override
         public SendFailure send(HttpExchange exchange)
         {

jetty-core/jetty-http2/jetty-http2-client-transport/src/main/java/org/eclipse/jetty/http2/client/transport/internal/HttpConnectionOverHTTP2.java

@@ -44,6 +44,7 @@
 import org.eclipse.jetty.http2.api.Session;
 import org.eclipse.jetty.http2.api.Stream;
 import org.eclipse.jetty.http2.frames.HeadersFrame;
+import org.eclipse.jetty.io.EndPoint;
 import org.eclipse.jetty.util.Callback;
 import org.eclipse.jetty.util.thread.Sweeper;
 import org.slf4j.Logger;
@@ -85,6 +86,12 @@ public SocketAddress getRemoteSocketAddress()
         return session.getRemoteSocketAddress();
     }
 
+    @Override
+    public EndPoint.SslSessionData getSslSessionData()
+    {
+        return connection.getEndPoint().getSslSessionData();
+    }
+
     public boolean isRecycleHttpChannels()
     {
         return recycleHttpChannels;

jetty-core/jetty-http2/jetty-http2-client/src/main/java/org/eclipse/jetty/http2/client/HTTP2ClientConnectionFactory.java

@@ -95,8 +95,7 @@ private HTTP2ClientConnection(HTTP2Client client, EndPoint endpoint, HTTP2Client
         public void onOpen()
         {
             Map<Integer, Integer> settings = listener.onPreface(getSession());
-            if (settings == null)
-                settings = new HashMap<>();
+            settings = settings == null ? new HashMap<>() : new HashMap<>(settings);
 
             // Below we want to populate any settings to send to the server
             // that have a different default than what prescribed by the RFC.

jetty-core/jetty-http2/jetty-http2-common/src/main/java/org/eclipse/jetty/http2/HTTP2Session.java

@@ -1248,6 +1248,11 @@ protected Entry(Frame frame, HTTP2Stream stream, Callback callback)
             this.stream = stream;
         }
 
+        public Frame frame()
+        {
+            return frame;
+        }
+
         public abstract int getFrameBytesGenerated();
 
         public int getDataBytesRemaining()