Compliance modes documentation

documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc

@@ -27,6 +27,7 @@ include::start/chapter.adoc[]
 include::modules/chapter.adoc[]
 include::deploy/chapter.adoc[]
 include::protocols/chapter.adoc[]
+include::compliance/server-compliance.adoc[]
 include::keystore/chapter.adoc[]
 include::sessions/chapter.adoc[]
 include::quickstart/chapter.adoc[]

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

@@ -18,15 +18,50 @@ The `server` module provides generic server support, and configures generic HTTP
 
 The `server` module depends on the xref:og-module-threadpool[`threadpool` module], the xref:og-module-bytebufferpool[`bytebufferpool` module] and the xref:og-module-logging[`logging`  module].
 
-The module file is `$JETTY_HOME/modules/server.mod`:
+[NOTE]
+====
+The `server` module configures the shared parameters for generic HTTP handline, but does not enable any specific network protocol.  You have to explicitly enable the protocols you want to support by enabling, for example, the xref:og-module-http[`http` module] for clear-text HTTP/1.1 support, or the xref:og-module-http2[`http2` module] for secure HTTP/2 support, etc.
+
+See also the xref:og-protocols[protocols section] for more information about the supported protocols.
+====
+
+[[og-module-server-http-config]]
+====== HTTP Configuration Properties
+
+The module properties to configure generic HTTP properties are listed below. Mostly they frequently apply to both HTTP/1 and HTTP/2, but some parameters are version specific:
 
 ----
-include::{JETTY_HOME}/modules/server.mod[]
+include::{JETTY_HOME}/modules/server.mod[tags=documentation-http-config]
 ----
 
 Among the configurable properties, the most relevant are:
 
-// TODO: consider extracting the httpConfig and scheduler properties into separate files.
+`jetty.httpConfig.headerCacheSize`::
+The header cache is used when parsing HTTP/1 to more efficiently handle fields that are repeated in every request on a connection.  If the server does not receive persistent connection or infrequent repeated fields, then there may be a performance gain in reducing the cache size. If large fields are frequently repeated, then a large cache may be beneficial.
+
+`jetty.httpConfig.delayDispatchUntilContent`::
+It is not uncommon for the network packets containing a request header to arrive before packets that contain the data of any request body. In such cases it may be beneficial for overall performance to delay dispatching the request to be handled until the first data packet arrives, as this may avoid blocking the handling thread.  However, if minimum latency for receiving the request without content is important, then this parameter can be set to false.
+
+`jetty.httpConfig.sendServerVersion`::
+Whether you want to send the `Server` header in every HTTP response:
++
+[source,screen,subs=normal]
+----
+HTTP/1.1 200 OK
+Content-Length: 0
+Server: Jetty({version})
+----
+
+[[og-module-server-config]]
+====== Server Configuration Properties
+
+The module properties to configure the Jetty server are:
+
+----
+include::{JETTY_HOME}/modules/server.mod[tags=documentation-server-config]
+----
+
+Among the configurable properties, the most relevant are:
 
 `jetty.server.dumpAfterStart`::
 Whether to perform a `Server.dump()` operation after the `Server` has started.
@@ -40,3 +75,59 @@ See also the xref:og-troubleshooting-dump[Jetty Server Dump] section for more in
 
 `jetty.server.stopAtShutdown`::
 Whether to call `Server.stop()` through a JVM shutdown hook when the JVM exits.
+
+[[og-module-server-compliance]]
+====== Server Compliance Properties
+
+The Jetty server strives to keep up with the latest link:https://en.wikipedia.org/wiki/Request_for_Comments[IETF RFC]s for compliance with internet specifications, which are periodically updated. When possible, Jetty will support backwards compatibility by providing compliance modes that can be configured to allow violations of the current specifications that may have been allowed in obsoleted specifications.
+The module properties to configure the Jetty server compliance are:
+
+----
+include::{JETTY_HOME}/modules/server.mod[tags=documentation-server-compliance]
+----
+
+Among the configurable properties, the most relevant are:
+
+`jetty.httpConfig.compliance`::
+Configures the compliance to HTTP specifications.
+The value could be:
+
+* One of the predefined link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] constants, such as `RFC7230` or `RFC2616`.
+For example: `jetty.httpConfig.compliance=RFC2616`.
+* A comma-separated list of violations to allow or forbid, as specified by the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html#from(java.lang.String)[`HttpCompliance.from(String)`] method.
+For example, `jetty.httpConfig.compliance=RFC7230,MULTIPLE_CONTENT_LENGTHS` means that the HTTP compliance is that defined by `RFC7230`, but also allows the `HttpCompliance.Violation.MULTIPLE_CONTENT_LENGTHS`, so that requests that have multiple `Content-Length` headers are accepted (they would be rejected when using just `HttpCompliance.RFC7230`).
++
+For more information about `HttpCompliance` see also xref:pg-server-compliance-http[this section].
+
+`jetty.httpConfig.uriCompliance`::
+Configures the compliance to URI specifications.
+The value could be:
+
+* One of the predefined link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html[`UriCompliance`] constants, such as `DEFAULT` or `RFC3986`.
+For example: `jetty.httpConfig.compliance=RFC3986`.
+* A comma-separated list of violations to allow or forbid, as specified by the link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html#from(java.lang.String)[`UriCompliance.from(String)`] method.
+For example, `jetty.httpConfig.uriCompliance=RFC3986,-AMBIGUOUS_PATH_SEPARATOR` means that the URI compliance is that defined by `RFC3986`, but also does not allow the `UriCompliance.Violation.AMBIGUOUS_PATH_SEPARATOR`, so that requests that have URIs such as `/foo/bar%2Fbaz` (where `%2F` is the URL-encoded `/` character) are rejected (they would be accepted when using just `UriCompliance.RFC3986`).
++
+For more information about `UriCompliance` see also xref:pg-server-compliance-uri[this section].
+
+`jetty.httpConfig.requestCookieCompliance`::
+`jetty.httpConfig.responseCookieCompliance`::
+Configures the compliance to HTTP cookie specifications.
+The value could be:
+
+* One of the predefined link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html[`CookieCompliance`] constants, such as `RFC6265`.
+For example: `jetty.httpConfig.compliance=RFC6265`.
+* A comma-separated list of violations to allow or forbid, as specified by the link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html#from(java.lang.String)[`CookieCompliance.from(String)`] method.
+For example, `jetty.httpConfig.requestCookieCompliance=RFC6265,-RESERVED_NAMES_NOT_DOLLAR_PREFIXED` means that the cookie compliance is that defined by `RFC6265`, but also does not allow the `CookieCompliance.Violation.RESERVED_NAMES_NOT_DOLLAR_PREFIXED`, so that requests that have cookie headers such as `Cookie: $foo=bar` are rejected (they would be accepted when using just `CookieCompliance.RFC6265`).
++
+For more information about `CookieCompliance` see also xref:pg-server-compliance-cookie[this section].
+
+
+[[og-module-scheduler-config]]
+====== Server Scheduler Configuration Properties
+
+The module properties to configure the Jetty server scheduler are:
+
+----
+include::{JETTY_HOME}/modules/server.mod[tags=documentation-scheduler-config]
+----

documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-cookie.adoc

@@ -0,0 +1,35 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2021 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-compliance-cookie]]
+==== Cookie Compliance Modes
+
+The standards for Cookies have varied greatly over time from a non-specified but de-facto standard (implemented by the first browsers), through link:https://tools.ietf.org/html/rfc2965[RFC 2965] and currently to link:https://tools.ietf.org/html/rfc6265[RFC 6265].
+
+The link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.Violation.html[CookieCompliance.Violation] enumeration defines the RFC requirements that may be optionally enforced by Jetty when parsing the `Cookie` HTTP header in requests and when generating the `Set-Cookie` HTTP header in responses.
+
+These violations are then grouped into modes by the link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html[`CookieCompliance`] class, which also defines several named modes that support common deployed sets of violations, with the default being link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html#RFC6265[`CookieCompliance.RFC6265`].
+
+For example:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=cookieCompliance]
+----
+
+If you want to customize the violations that you want to allow, you can create your own mode using the link:{JDURL}/org/eclipse/jetty/http/CookieCompliance.html#from(java.lang.String)[`CookieCompliance.from(String)`] method:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=cookieComplianceCustom]
+----

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

@@ -0,0 +1,42 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2021 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-compliance-http]]
+==== HTTP Compliance Modes
+
+In 1995, when Jetty was first implemented, there were no RFC specification of HTTP, only a W3C specification for link:https://www.w3.org/Protocols/HTTP/AsImplemented.html[HTTP/0.9], which has since been obsoleted or augmented by:
+
+ * link:https://datatracker.ietf.org/doc/html/rfc1945[RFC 1945] for HTTP/1.0 in 1996
+ * link:https://datatracker.ietf.org/doc/html/rfc2068[RFC 2068] for HTTP/1.1  in 1997
+ * link:https://datatracker.ietf.org/doc/html/rfc2616[RFC 2616] for HTTP/1.1 bis in 1999
+ * link:https://datatracker.ietf.org/doc/html/rfc7230[RFC 7230], link:https://datatracker.ietf.org/doc/html/rfc7231[RFC 7231], link:https://datatracker.ietf.org/doc/html/rfc7232[RFC 7232], link:https://datatracker.ietf.org/doc/html/rfc7233[RFC 7233], link:https://datatracker.ietf.org/doc/html/rfc7234[RFC 7234], link:https://datatracker.ietf.org/doc/html/rfc7235[RFC 7235] again for HTTP/1.1 in 2014
+ * link:https://datatracker.ietf.org/doc/html/rfc7540[RFC 7540] for HTTP/2.0 in 2015
+
+In addition to these evolving requirements, some earlier version of Jetty did not completely or strictly implement the RFC at the time (for example, case-insensitive HTTP methods).
+Therefore, upgrading to a newer Jetty version may cause runtime behavior differences that may break your applications.
+
+The link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.Violation.html[`HttpCompliance.Violation`] enumeration defines the RFC requirements that may be optionally enforced by Jetty, to support legacy deployments. These possible violations are grouped into modes by the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] class, which also defines several named modes that support common deployed sets of violations (with the default being link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html#RFC7230[`HttpCompliance.RFC7230`]).
+
+For example:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=httpCompliance]
+----
+
+If you want to customize the violations that you want to allow, you can create your own mode using the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html#from(java.lang.String)[`HttpCompliance.from(String)`] method:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=httpComplianceCustom]
+----

documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance-uri.adoc

@@ -0,0 +1,52 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2021 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-compliance-uri]]
+==== URI Compliance Modes
+
+Universal Resource Locators (URLs) where initially formalized in 1994 in link:https://datatracker.ietf.org/doc/html/rfc1738[RFC 1738] and then refined in 1995 with relative URLs by link:https://datatracker.ietf.org/doc/html/rfc1808[RFC 1808].
+
+In 1998, URLs were generalized to Universal Resource Identifiers (URIs) by link:https://datatracker.ietf.org/doc/html/rfc2396[RFC 2396], which also introduced features such a link:https://datatracker.ietf.org/doc/html/rfc2396#section-3.3[path parameter]s.
+
+This was then obsoleted in 2005 by link:https://datatracker.ietf.org/doc/html/rfc3986[RFC 3986] which removed the definition for path parameters.
+
+Unfortunately by this stage the existence and use of such parameters had already been codified in the Servlet specification.
+For example, the relative URI `/foo/bar;JSESSIONID=a8b38cd02b1c` would define the path parameter `JSESSIONID` for the path segment `bar`, but the most recent RFC does not specify a formal definition of what this relative URI actually means.
+
+The current situation is that there may be URIs that are entirely valid for link:https://datatracker.ietf.org/doc/html/rfc3986[RFC 3986], but are ambiguous when handled by the Servlet APIs:
+
+* A URI with `..` _and_ path parameters such as `/some/..;/path` is not link:https://datatracker.ietf.org/doc/html/rfc3986#section-5.2[_resolved_] by RFC 3986, since the resolution process only applies to the exact segment `..`, not to `..;`.
+However, once the path parameters are removed by the Servlet APIs, the resulting `/some/../path` can easily be resolved to `/path`, rather than be treated as a path that has `..;` as a segment.
+* A URI such as `/some/%2e%2e/path` is not resolved by RFC 3986, yet when URL-decoded by the Servlet APIs will result in `/some/../path` which can easily be resolved to `/path`, rather than be treated as a path that has `..` as a segment.
+* A URI with empty segments like `/some//../path` may be correctly resolved to `/some/path` (the `..` removes the previous empty segment) by the Servlet APIs.
+However, if the URI raw path is passed to some other APIs (for example, file system APIs) it can be interpreted as `/path` because the empty segment `//` is discarded and treated as `/`, and the `..` thus removes the `/some` segment.
+
+In order to avoid ambiguous URIs, Jetty imposes additional URI requirements in excess of what is required by link:https://datatracker.ietf.org/doc/html/rfc3986[RFC 3986] compliance.
+
+These additional requirements may optionally be violated and are defined by the link:{JDURL}/org/eclipse/jetty/http/UriCompliance.Violation.html[`UriCompliance.Violation`] enumeration.
+
+These violations are then grouped into modes by the link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html[`UriCompliance`] class, which also defines several named modes that support common deployed sets of violations, with the default being link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html#DEFAULT[`UriCompliance.DEFAULT`].
+
+For example:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=uriCompliance]
+----
+
+If you want to customize the violations that you want to allow, you can create your own mode using the link:{JDURL}/org/eclipse/jetty/http/UriCompliance.html#from(java.lang.String)[`UriCompliance.from(String)`] method:
+
+[source,java,indent=0]
+----
+include::../../{doc_code}/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=uriComplianceCustom]
+----

documentation/jetty-documentation/src/main/asciidoc/programming-guide/server/compliance/server-compliance.adoc

@@ -0,0 +1,33 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2021 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-compliance]]
+=== Server Compliance Modes
+
+The Jetty server strives to keep up with the latest link:https://en.wikipedia.org/wiki/Request_for_Comments[IETF RFC]s for compliance with internet specifications, which are periodically updated.
+
+When possible, Jetty will support backwards compatibility by providing compliance modes that can be configured to allow violations of the current specifications that may have been allowed in obsoleted specifications.
+
+There are compliance modes provided for:
+
+* xref:pg-server-compliance-http[HTTP Compliance]
+* xref:pg-server-compliance-uri[URI Compliance]
+* xref:pg-server-compliance-cookie[Cookie Compliance]
+
+Compliance modes can be configured to allow violations from the RFC requirements, or in some cases to allow additional behaviors that Jetty has implemented in excess of the RFC (for example, to allow xref:pg-server-compliance-uri[ambiguous URIs]).
+
+For example, the HTTP RFCs require that request HTTP methods are link:https://datatracker.ietf.org/doc/html/rfc7230#section-3.1.1[case sensitive], however Jetty can allow case-insensitive HTTP methods by including the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.Violation.html#CASE_INSENSITIVE_METHOD[`HttpCompliance.Violation.CASE_INSENSITIVE_METHOD`] in the link:{JDURL}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] set of allowed violations.
+
+include::server-compliance-http.adoc[]
+include::server-compliance-uri.adoc[]
+include::server-compliance-cookie.adoc[]

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

@@ -26,7 +26,9 @@ The Jetty server-side libraries provide:
 * HTTP support for HTTP/1.0, HTTP/1.1, HTTP/2, clear-text or encrypted, for applications that want to embed Jetty as a generic HTTP server or proxy, via the xref:pg-server-http[HTTP libraries]
 * HTTP/2 low-level support, for applications that want to explicitly handle low-level HTTP/2 _sessions_, _streams_ and _frames_, via the xref:pg-server-http2[HTTP/2 libraries]
 * WebSocket support, for applications that want to embed a WebSocket server, via the xref:pg-server-websocket[WebSocket libraries]
+* FCGI support, to delegate requests to python or similar scripting languages.
 
+include::compliance/server-compliance.adoc[]
 include::http/server-http.adoc[]
 include::http2/server-http2.adoc[]
 include::sessions/sessions.adoc[]