Skip to content

Commit

Permalink
Fixes #5308 - Extract httpConfig and scheduler configuration out of j…
Browse files Browse the repository at this point in the history 
…etty.xml.

Move the scheduler and http configuration into separate modules.
Updated and expanded the documentation.

Signed-off-by: Simone Bordet <[email protected]>
  • Loading branch information
@sbordet
sbordet committed Nov 29, 2024
1 parent d1fc707 commit c06a24b
Show file tree
Hide file tree
Showing 10 changed files with 324 additions and 264 deletions.
11 changes: 10 additions & 1 deletion ...les/code/examples/src/main/java/org/eclipse/jetty/docs/programming/server/ServerDocs.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@

import org.eclipse.jetty.http.CookieCompliance;
import org.eclipse.jetty.http.HttpCompliance;
import org.eclipse.jetty.http.MultiPartCompliance;
import org.eclipse.jetty.http.UriCompliance;
import org.eclipse.jetty.io.AbstractConnection;
import org.eclipse.jetty.io.Connection;
Expand Down Expand Up @@ -326,7 +327,15 @@ public void cookieComplianceCustom()
httpConfiguration.setRequestCookieCompliance(customUriCompliance);

httpConfiguration.setResponseCookieCompliance(CookieCompliance.RFC6265);

// end::cookieComplianceCustom[]
}

public void multiPartCompliance()
{
// tag::multiPartCompliance[]
HttpConfiguration httpConfiguration = new HttpConfiguration();
MultiPartCompliance custom = MultiPartCompliance.from("RFC7578,-CONTENT_TRANSFER_ENCODING");
httpConfiguration.setMultiPartCompliance(custom);
// end::multiPartCompliance[]
}
}
181 changes: 95 additions & 86 deletions documentation/jetty/modules/operations-guide/pages/modules/standard.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,9 @@ For more information, refer to xref:programming-guide:server/http.adoc#connector

The module file is `$JETTY_HOME/modules/connectionlimit.mod`:

----
include::{jetty-home}/modules/connectionlimit.mod[tags=documentation]
----

[[console-capture]]
== Module `console-capture`
Expand Down Expand Up @@ -312,6 +314,82 @@ The module properties are:
include::{jetty-home}/modules/http3.mod[tags=documentation]
----

[[http-config]]
== Module `http-config`

The `http-config` module provides HTTP configuration parameters that describe the HTTP semantic, and therefore do not depend on a specific HTTP protocol version.

The module properties are:

----
include::{jetty-home}/modules/http-config.mod[tags=documentation]
----

Among the configurable properties, the most relevant are:

`jetty.httpConfig.requestHeaderSize`::
The maximum size of the request headers, beyond which the request is rejected with the HTTP status code `431 Request Header Fields Too Large`.

`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.outputAggregationSize`::
The size of the buffer that aggregates response writes that are not explicitly flushed.
This is used only at the Servlet layer, to buffer writes performed with `ServletOutputStream`.

`jetty.httpConfig.sendServerVersion`::
Whether you want to send the `Server` header in every HTTP response:
+
[source,subs=attributes+]
----
HTTP/1.1 200 OK
Content-Length: 0
Server: Jetty({jetty-version})
----

=== Server Compliance Properties

The Jetty server strives to keep up with the latest 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/http-config.mod[tags=documentation-compliance]
----

Among the configurable properties, the most relevant are:

`jetty.httpConfig.compliance`::
Configures the compliance to HTTP specifications, see also xref:programming-guide:server/compliance.adoc#http[this section].
+
The value could be: one of the predefined link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] constants, such as `RFC9110`, `RFC7230` or `RFC2616`; or a comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html#from(java.lang.String)[`HttpCompliance.from(String)`] method.
+
For example, `jetty.httpConfig.compliance=RFC9110,MULTIPLE_CONTENT_LENGTHS` means that the HTTP compliance is that defined by `RFC9110`, 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.RFC9110`).

`jetty.httpConfig.uriCompliance`::
Configures the compliance to URI specifications, see also xref:programming-guide:server/compliance.adoc#uri[this section].
+
The value could be: one of the predefined link:{javadoc-url}/org/eclipse/jetty/http/UriCompliance.html[`UriCompliance`] constants, such as `DEFAULT` or `RFC3986`; or a comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/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`).

`jetty.httpConfig.requestCookieCompliance`::
`jetty.httpConfig.responseCookieCompliance`::
Configure the compliance to HTTP cookie specifications, respectively for requests and responses, see also xref:programming-guide:server/compliance.adoc#cookie[this section].
+
The value could be: one of the predefined link:{javadoc-url}/org/eclipse/jetty/http/CookieCompliance.html[`CookieCompliance`] constants, such as `RFC6265`; or a comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/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`).

`jetty.httpConfig.multiPartCompliance`::
Configures the compliance to MultiPart specifications, see also xref:programming-guide:server/compliance.adoc#multiPart[this section].
+
The value could be: one of the predefined link:{javadoc-url}/org/eclipse/jetty/http/MultiPartCompliance.html[`MultiPartCompliance`] constants, such as `RFC7578_STRICT` or `RFC7578`; or a comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/org/eclipse/jetty/http/MultiPartCompliance.html#from(java.lang.String)[`MultiPartCompliance.from(String)`] method.
+
For example, `jetty.httpConfig.multiPartCompliance=RFC7578,-CONTENT_TRANSFER_ENCODING` means that the MultiPart compliance is that defined by `RFC7578`, but also does not allow the `MultiPartCompliance.Violation.CONTENT_TRANSFER_ENCODING`, so that parts that specify the `Content-Transfer-Encoding` header are rejected (they would be accepted when using just `MultiPartCompliance.RFC7578`).

[[http-forwarded]]
== Module `http-forwarded`

Expand Down Expand Up @@ -477,54 +555,40 @@ In the example below, the rule will only be evaluated if the virtual host matche
</Configure>
----

[[server]]
== Module `server`

The `server` module provides generic server support, and configures generic HTTP properties that apply to all HTTP protocols, the scheduler properties and the server specific properties.

The `server` module depends on the <<threadpool,`threadpool` module>>, the <<bytebufferpool,`bytebufferpool` module>> and the xref:server/index.adoc#logging[`logging` module].

[NOTE]
====
The `server` module configures the shared parameters for generic HTTP handling, but does not enable any specific network protocol. You have to explicitly enable the protocols you want to support by enabling, for example, the <<http,`http` module>> for clear-text HTTP/1.1 support, or the <<http2,`http2` module>> for secure HTTP/2 support, etc.
[[scheduler]]
== Module `scheduler`

See also the xref:protocols/index.adoc[protocols section] for more information about the supported protocols.
====
The `scheduler` module allows you to configure the server-wide scheduler.

[[server-http-config]]
=== HTTP Configuration Properties
The scheduler is used to schedule tasks that must run at a later time, for example the tasks that perform actions when timeouts expire, in particular idle timeouts.

The module properties to configure generic HTTP properties are listed below. Mostly they frequently apply to HTTP/1, HTTP/2 and HTTP/3, but some parameters are version specific:
The module properties to configure the scheduler are:

----
include::{jetty-home}/modules/server.mod[tags=documentation-http-config]
include::{jetty-home}/modules/scheduler.mod[tags=documentation]
----

Among the configurable properties, the most relevant are:
[[server]]
== Module `server`

`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.
The `server` module provides generic server support, and configures generic HTTP properties that apply to all HTTP protocols, the scheduler properties and the server specific properties.

`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.
[NOTE]
====
The `server` module configures the shared parameters for generic HTTP handling, but does not enable any specific network protocol.
`jetty.httpConfig.sendServerVersion`::
Whether you want to send the `Server` header in every HTTP response:
+
[source,subs=attributes+]
----
HTTP/1.1 200 OK
Content-Length: 0
Server: Jetty({jetty-version})
----
You have to explicitly enable the protocols you want to support by enabling, for example, the <<http,`http` module>> for clear-text HTTP/1.1 support, or the <<http2,`http2` module>> for secure HTTP/2 support, etc.
See also the xref:protocols/index.adoc[protocols section] for more information about the supported protocols.
====

[[server-config]]
=== Server Configuration Properties

The module properties to configure the Jetty server are:

----
include::{jetty-home}/modules/server.mod[tags=documentation-server-config]
include::{jetty-home}/modules/server.mod[tags=documentation]
----

Among the configurable properties, the most relevant are:
Expand All @@ -542,61 +606,6 @@ See also the xref:troubleshooting/index.adoc#dump[Jetty Server Dump] section for
`jetty.server.stopAtShutdown`::
Whether to call `Server.stop()` through a JVM shutdown hook when the JVM exits.

[[server-compliance]]
=== Server Compliance Properties

The Jetty server strives to keep up with the latest 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:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html[`HttpCompliance`] constants, such as `RFC9110`, RFC7230` or `RFC2616`.
For example: `jetty.httpConfig.compliance=RFC2616`.
* A comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/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:programming-guide:server/compliance.adoc#http[this section].

`jetty.httpConfig.uriCompliance`::
Configures the compliance to URI specifications.
The value could be:

* One of the predefined link:{javadoc-url}/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:{javadoc-url}/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:programming-guide:server/compliance.adoc#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:{javadoc-url}/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:{javadoc-url}/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:programming-guide:server/compliance.adoc#cookie[this section].

[[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]
----

[[size-limit]]
== Module `size-limit`

Expand Down
17 changes: 17 additions & 0 deletions documentation/jetty/modules/programming-guide/pages/server/compliance.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ There are compliance modes provided for:
* <<http,HTTP Compliance>>
* <<uri,URI Compliance>>
* <<cookie,Cookie Compliance>>
* <<multiPart,MultiPart 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 <<uri,ambiguous URIs>>).

Expand Down Expand Up @@ -131,3 +132,19 @@ If you want to customize the violations that you want to allow, you can create y
----
include::code:example$src/main/java/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=cookieComplianceCustom]
----

[[multiPart]]
== MultiPart Compliance Modes

The standards for multipart uploads (also known as `multipart/form-data`) varied over time, but were eventually standardized by link:https://tools.ietf.org/html/rfc7578[RFC 7578].

The link:{javadoc-url}/org/eclipse/jetty/http/MultiPartCompliance.Violation.html[MultiPartCompliance.Violation] enumeration defines the RFC requirements that may be optionally enforced by Jetty when parsing `multipart/form-data` content in requests.

These violations are then grouped into modes by the link:{javadoc-url}/org/eclipse/jetty/http/MultiPartCompliance.html[`MultiPartCompliance`] class, which also defines several named modes that support common deployed sets of violations, with the default being link:{javadoc-url}/org/eclipse/jetty/http/MultiPartCompliance.html#RFC7578[`MultiPartCompliance.RFC7578`].

If you want to customize the violations that you want to allow, you can create your own mode using the link:{javadoc-url}/org/eclipse/jetty/http/MultiPartCompliance.html#from(java.lang.String)[`MultiPartCompliance.from(String)`] method:

[,java,indent=0]
----
include::code:example$src/main/java/org/eclipse/jetty/docs/programming/server/ServerDocs.java[tags=multiPartCompliance]
----
Loading

0 comments on commit c06a24b

Please sign in to comment.