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

build/build-resources/pom.xml

@@ -101,4 +101,34 @@
       </plugin>
     </plugins>
   </build>
+  <profiles>
+    <profile>
+      <id>eclipse-release</id>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-enforcer-plugin</artifactId>
+            <version>3.4.1</version>
+            <executions>
+              <execution>
+                <id>enforce-java</id>
+                <goals>
+                  <goal>enforce</goal>
+                </goals>
+                <configuration>
+                  <rules>
+                    <requireJavaVersion>
+                      <version>[22,)</version>
+                      <message>[ERROR] OLD JDK [${java.version}] in use. Jetty Release ${project.version} MUST use JDK 22 or newer</message>
+                    </requireJavaVersion>
+                  </rules>
+                </configuration>
+              </execution>
+            </executions>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
 </project>

build/scripts/release-jetty.sh

@@ -131,7 +131,7 @@ reportMavenTestFailures() {
 
 echo ""
 if proceedyn "Are you sure you want to release using above? (y/N)" n; then
-    mvn clean install -pl build -Dmaven.build.cache.enabled=false
+    mvn clean install -pl build -Peclipse-release -Dmaven.build.cache.enabled=false
     echo ""
     if proceedyn "Update VERSION.txt for $VER_RELEASE? (Y/n)" y; then
         mvn -N -Pupdate-version generate-resources -Dmaven.build.cache.enabled=false

documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-rewrite.adoc

@@ -0,0 +1,84 @@
+//
+// ========================================================================
+// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[og-module-rewrite]]
+===== Module `rewrite`
+
+The `rewrite` module inserts the `RewriteHandler` at the beginning of the `Handler` chain, providing URI-rewriting features similar to the link:https://httpd.apache.org/docs/current/mod/mod_rewrite.html[Apache's mod_rewrite] or the link:https://nginx.org/en/docs/http/ngx_http_rewrite_module.html[Nginx rewrite module].
+
+The module properties are:
+
+----
+include::{jetty-home}/modules/rewrite.mod[tags=documentation]
+----
+
+A common use of the `rewrite` module is to redirect/rewrite old URI paths that have been renamed, for example from `+/old/*+` to `+/new/*+`; in this way, the old paths will not result in a `404` response, but rather be redirected/rewritten to the new paths.
+
+`RewriteHandler` matches incoming requests against a set of rules that you can specify in the `$JETTY_BASE/etc/jetty-rewrite-rules.xml` file.
+
+Rules can be matched against request data such as the request URI or the request headers; if there is a match, the rule is applied.
+
+The rule file `$JETTY_BASE/etc/jetty-rewrite-rules.xml` is initially empty, but contains commented examples of rules that you can add.
+
+The list of available rules can be found link:{javadoc-url}/org/eclipse/jetty/rewrite/handler/package-summary.html[here].
+
+An example of `jetty-rewrite-rules.xml` is the following:
+
+[source,xml]
+.jetty-rewrite-rules.xml
+----
+<?xml version="1.0"?>
+<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://eclipse.dev/jetty/configure_10_0.dtd">
+<Configure id="Rewrite" class="org.eclipse.jetty.rewrite.handler.RuleContainer">
+  <Call name="addRule">
+    <!-- Redirect with a 301 from /old/* to /new/* -->
+    <Arg>
+      <New class="org.eclipse.jetty.rewrite.handler.RedirectRegexRule">
+        <Set name="statusCode">301</Set>
+        <Set name="pattern">/old/(.*)</Set>
+        <Set name="location">/new/$1</Set>
+      </New>
+    </Arg>
+  </Call>
+</Configure>
+----
+
+Rules can be scoped to a specific virtual host.
+In the example below, the rule will only be evaluated if the virtual host matches `example.com`:
+
+[source,xml]
+.jetty-rewrite-rules.xml
+----
+<?xml version="1.0"?>
+<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://eclipse.dev/jetty/configure_10_0.dtd">
+<Configure id="Rewrite" class="org.eclipse.jetty.rewrite.handler.RuleContainer">
+  <Call name="addRule">
+    <Arg>
+      <New class="org.eclipse.jetty.rewrite.handler.VirtualHostRuleContainer">
+        <Call name="addVirtualHost">
+          <!-- Only match the example.com domain -->
+          <Arg>example.com</Arg>
+        </Call>
+        <Call name="addRule">
+          <Arg>
+            <New class="org.eclipse.jetty.rewrite.handler.RedirectPatternRule">
+              <Set name="pattern">/advice</Set>
+              <Set name="location">/support</Set>
+            </New>
+          </Arg>
+        </Call>
+      </New>
+    </Arg>
+  </Call>
+</Configure>
+----

documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-standard.adoc

@@ -30,6 +30,7 @@ include::module-jmx.adoc[]
 include::module-jmx-remote.adoc[]
 include::module-requestlog.adoc[]
 include::module-resources.adoc[]
+include::module-rewrite.adoc[]
 include::module-server.adoc[]
 include::module-ssl.adoc[]
 include::module-ssl-reload.adoc[]

documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-request-customizers.adoc

@@ -0,0 +1,112 @@
+//
+// ========================================================================
+// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[pg-server-http-request-customizers]]
+==== Request Customizers
+
+A request customizer is an instance of `HttpConfiguration.Customizer`, that can customize the HTTP request and/or the HTTP response headers _before_ the `Handler` chain is invoked.
+
+Request customizers are added to a particular `HttpConfiguration` instance, and therefore are specific to a `Connector` instance: you can have two different ``Connector``s configured with different request customizers.
+
+For example, it is common to configure a secure `Connector` with the `SecureRequestCustomizer` that customizes the HTTP request by adding attributes that expose TLS data associated with the secure communication.
+
+A request customizer may:
+
+* Inspect the received HTTP request method, URI, version and headers.
+* Wrap the `Request` object to allow any method to be overridden and customized. Typically this is done to synthesize additional HTTP request headers, or to change the return value of overridden methods.
+* Add or modify the HTTP response headers.
+
+The out-of-the-box request customizers include:
+
+* `ForwardedRequestCustomizer` -- to interpret the `Forwarded` (or the the obsolete ``+X-Forwarded-*+``) HTTP header added by a reverse proxy; see xref:pg-server-http-request-customizer-forwarded[this section].
+* `HostHeaderCustomizer` -- to customize, or synthesize it when original absent, the HTTP `Host` header; see xref:pg-server-http-request-customizer-host[this section].
+* `ProxyCustomizer` -- to expose as `Request` attributes the `ip:port` information carried by the PROXY protocol; see xref:pg-server-http-request-customizer-proxy[this section].
+* `RewriteCustomizer` -- to rewrite the request URI; see xref:pg-server-http-request-customizer-rewrite[this section].
+* `SecureRequestCustomizer` -- to expose TLS data via `Request` attributes; see xref:pg-server-http-request-customizer-secure[this section].
+
+You can also write your own request customizers and add them to the `HttpConfiguration` instance along existing request customizers.
+Multiple request customizers will be invoked in the order they have been added.
+
+Below you can find an example of how to add a request customizer:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java[tags=requestCustomizer]
+----
+
+[[pg-server-http-request-customizer-forwarded]]
+===== `ForwardedRequestCustomizer`
+
+`ForwardedRequestCustomizer` should be added when Jetty receives requests from a reverse proxy on behalf of a remote client, and web applications need to access the remote client information.
+
+The reverse proxy adds the `Forwarded` (or the obsolete ``+X-Forwarded-*+``) HTTP header to the request, and may offload TLS so that the request arrives in clear-text to Jetty.
+
+Applications deployed in Jetty may need to access information related to the remote client, for example the remote IP address and port, or whether the request was sent through a secure communication channel.
+However, the request is forwarded by the reverse proxy, so the direct information about the remote IP address is that of the proxy, not of the remote client.
+Furthermore, the proxy may offload TLS and forward the request in clear-text, so that the URI scheme would be `http` as forwarded by the reverse proxy, not `https` as sent by the remote client.
+
+`ForwardedRequestCustomizer` reads the `Forwarded` header where the reverse proxy saved the remote client information, and wraps the original `Request` so that applications will transparently see the remote client information when calling methods such as `Request.isSecure()`, or `Request.getConnectionMetaData().getRemoteSocketAddress()`, etc.
+
+For more information about how to configure `ForwardedRequestCustomizer`, see also link:{javadoc-url}/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[the javadocs].
+
+[[pg-server-http-request-customizer-host]]
+===== `HostHeaderCustomizer`
+
+`HostHeaderCustomizer` should be added when Jetty receives requests that may lack the `Host` HTTP header, such as HTTP/1.0, HTTP/2 or HTTP/3 requests, and web applications have logic that depends on the value of the `Host` HTTP header.
+
+For HTTP/2 and HTTP/3, the `Host` HTTP header is missing because the authority information is carried by the `:authority` pseudo-header, as per the respective specifications.
+
+`HostHeaderCustomizer` will look at the `:authority` pseudo-header, then wrap the original `Request` adding a `Host` HTTP header synthesized from the `:authority` pseudo-header.
+In this way, web applications that rely on the presence of the `Host` HTTP header will work seamlessly in any HTTP protocol version.
+
+`HostHeaderCustomizer` works also for the WebSocket protocol.
+
+WebSocket over HTTP/2 or over HTTP/3 initiate the WebSocket communication with an HTTP request that only has the `:authority` pseudo-header.
+`HostHeaderCustomizer` synthesizes the `Host` HTTP header for such requests, so that WebSocket web applications that inspect the initial HTTP request before the WebSocket communication will work seamlessly in any HTTP protocol version.
+
+For more information about how to configure `HostHeaderCustomizer`, see also link:{javadoc-url}/org/eclipse/jetty/server/HostHeaderCustomizer.html[the javadocs].
+
+[[pg-server-http-request-customizer-proxy]]
+===== `ProxyCustomizer`
+
+`ProxyCustomizer` should be added when Jetty receives requests from a reverse proxy on behalf of a remote client, prefixed by the PROXY protocol (see also this section about the xref:pg-server-http-connector-protocol-proxy-http11[PROXY protocol]).
+
+`ProxyCustomizer` adds the reverse proxy IP address and port as `Request` attributes.
+Web applications may use these attributes in conjunction with the data exposed by `ForwardedRequestCustomizer` (see xref:pg-server-http-request-customizer-forwarded[this section]).
+
+For more information about how to configure `ProxyCustomizer`, see also link:{javadoc-url}/org/eclipse/jetty/server/ProxyCustomizer.html[the javadocs].
+
+[[pg-server-http-request-customizer-rewrite]]
+===== `RewriteCustomizer`
+
+`RewriteCustomizer` is similar to `RewriteHandler` (see xref:pg-server-http-handler-use-rewrite[this section]), but a `RewriteCustomizer` cannot send a response or otherwise complete the request/response processing.
+
+A `RewriteCustomizer` is mostly useful if you want to rewrite the request URI _before_ the `Handler` chain is invoked.
+However, a very similar effect can be achieved by having the `RewriteHandler` as the first `Handler` (the child `Handler` of the `Server` instance).
+
+Since `RewriteCustomizer` cannot send a response or complete the request/response processing, ``Rule``s that do so such as redirect rules have no effect and are ignored; only ``Rule``s that modify or wrap the `Request` will have effect and be applied.
+
+Due to this limitation, it is often a better choice to use `RewriteHandler` instead of `RewriteCustomizer`.
+
+For more information about how to configure `RewriteCustomizer`, see also link:{javadoc-url}/org/eclipse/jetty/rewrite/RewriteCustomizer.html[the javadocs].
+
+[[pg-server-http-request-customizer-secure]]
+===== `SecureRequestCustomizer`
+
+`SecureRequestCustomizer` should be added when Jetty receives requests over a secure `Connector`.
+
+`SecureRequestCustomizer` adds TLS information as request attributes, in particular an instance of `EndPoint.SslSessionData` that contains information about the negotiated TLS cipher suite and possibly client certificates, and an instance of `org.eclipse.jetty.util.ssl.X509` that contains information about the server certificate.
+
+`SecureRequestCustomizer` also adds, if configured so, the `Strict-Transport-Security` HTTP response header (for more information about this header, see link:https://datatracker.ietf.org/doc/html/rfc6797[its specification]).
+
+For more information about how to configure `SecureRequestCustomizer`, see also link:{javadoc-url}/org/eclipse/jetty/server/SecureRequestCustomizer.html[the javadocs].

documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/http/server-http-request-logging.adoc

@@ -0,0 +1,48 @@
+//
+// ========================================================================
+// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+// which is available at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[pg-server-http-request-logging]]
+==== Request Logging
+
+HTTP requests and responses can be logged to provide data that can be later analyzed with other tools.
+These tools can provide information such as the most frequently accessed request URIs, the response status codes, the request/response content lengths, geographical information about the clients, etc.
+
+The default request/response log line format is the link:https://en.wikipedia.org/wiki/Common_Log_Format[NCSA Format] extended with referrer data and user-agent data.
+
+[NOTE]
+====
+Typically, the extended NCSA format is the is enough and it's the standard used and understood by most log parsing tools and monitoring tools.
+
+To customize the request/response log line format see the link:{javadoc-url}/org/eclipse/jetty/server/CustomRequestLog.html[`CustomRequestLog` javadocs].
+====
+
+Request logging can be enabled at the `Server` level.
+
+The request logging output can be directed to an SLF4J logger named `"org.eclipse.jetty.server.RequestLog"` at `INFO` level, and therefore to any logging library implementation of your choice (see also xref:pg-troubleshooting-logging[this section] about logging).
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java[tags=serverRequestLogSLF4J]
+----
+
+Alternatively, the request logging output can be directed to a daily rolling file of your choice, and the file name must contain `yyyy_MM_dd` so that rolled over files retain their date:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/http/HTTPServerDocs.java[tags=serverRequestLogFile]
+----
+
+For maximum flexibility, you can log to multiple ``RequestLog``s using class `RequestLog.Collection`, for example by logging with different formats or to different outputs.
+
+You can use `CustomRequestLog` with a custom `RequestLog.Writer` to direct the request logging output to your custom targets (for example, an RDBMS).
+You can implement your own `RequestLog` if you want to have functionalities that are not implemented by `CustomRequestLog`.