Spring/spring-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Auto-configure H2C when HTTP/2 is enabled and SSL is disabled

Browse Source
This commit is contained in:
Andy Wilkinson
2021-04-12 07:44:11 +01:00
parent 288e86d871
commit 713c0fce7c
10 changed files with 148 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc
View File

@@ -594,26 +594,23 @@ We recommend using `application.properties` to configure HTTPS, as the HTTP conn
[[howto-configure-http2]]
=== Configure HTTP/2
You can enable HTTP/2 support in your Spring Boot application with the configprop:server.http2.enabled[] configuration property.
This support depends on the chosen web server and the application environment, since that protocol is not supported out-of-the-box by all JDK8 releases.
Both `h2` (HTTP/2 over TLS) and `h2c` (HTTP/2 over TCP) are supported.
To use `h2`, SSL must also be enabled.
When SSL is not enabled, `h2c` will be used.
The details of the `h2` support depend on the chosen web server and the application environment, since that protocol is not supported out-of-the-box by all JDK 8 releases.
[NOTE]
====
Spring Boot does not advise using `h2c`, the cleartext version of the HTTP/2 protocol.
As a result, the following sections require you to <<howto-configure-ssl, configure SSL first>>.
If you still choose to use `h2c`, you can check <<howto-configure-http2-h2c, the dedicated section>>.
====
[[howto-configure-http2-tomcat]]
==== HTTP/2 with Tomcat
Spring Boot ships by default with Tomcat 9.0.x which supports HTTP/2 out of the box when using JDK 9 or later.
Alternatively, HTTP/2 can be used on JDK 8 if the `libtcnative` library and its dependencies are installed on the host operating system.
Spring Boot ships by default with Tomcat 9.0.x which supports `h2c` out of the box and `h2` out of the box when using JDK 9 or later.
Alternatively, `h2` can be used on JDK 8 if the `libtcnative` library and its dependencies are installed on the host operating system.
The library directory must be made available, if not already, to the JVM library path.
You can do so with a JVM argument such as `-Djava.library.path=/usr/local/opt/tomcat-native/lib`.
More on this in the https://tomcat.apache.org/tomcat-9.0-doc/apr.html[official Tomcat documentation].
Starting Tomcat 9.0.x on JDK 8 without that native support logs the following error:
Starting Tomcat 9.0.x on JDK 8 with HTTP/2 and SSL enabled but without that native support logs the following error:
[indent=0,subs="attributes"]
----
@@ -626,7 +623,8 @@ This error is not fatal, and the application still starts with HTTP/1.1 SSL supp
[[howto-configure-http2-jetty]]
==== HTTP/2 with Jetty
For HTTP/2 support, Jetty requires the additional `org.eclipse.jetty.http2:http2-server` dependency.
Now depending on your deployment, you also need to choose other dependencies:
To use `h2c` no other dependencies are required.
To use `h2`, you also need to choose one of the following dependencies, depending on your deployment:
* `org.eclipse.jetty:jetty-alpn-java-server` for applications running on JDK9+
* `org.eclipse.jetty:jetty-alpn-openjdk8-server` for applications running on JDK8u252+
@@ -637,8 +635,9 @@ Now depending on your deployment, you also need to choose other dependencies:
[[howto-configure-http2-netty]]
==== HTTP/2 with Reactor Netty
The `spring-boot-webflux-starter` is using by default Reactor Netty as a server.
Reactor Netty can be configured for HTTP/2 using the JDK support with JDK 9 or later.
For JDK 8 environments, or for optimal runtime performance, this server also supports HTTP/2 with native libraries.
Reactor Netty supports `h2c` using JDK 8 or later with no additional dependencies.
Reactor Netty supports `h2` using the JDK support with JDK 9 or later.
For JDK 8 environments, or for optimal runtime performance, this server also supports `h2` with native libraries.
To enable that, your application needs to have an additional dependency.
Spring Boot manages the version for the `io.netty:netty-tcnative-boringssl-static` "uber jar", containing native libraries for all platforms.
@@ -648,65 +647,7 @@ Developers can choose to import only the required dependencies using a classifie
[[howto-configure-http2-undertow]]
==== HTTP/2 with Undertow
As of Undertow 1.4.0+, HTTP/2 is supported without any additional requirement on JDK8.
[[howto-configure-http2-h2c]]
==== HTTP/2 Cleartext with supported servers
To enable HTTP/2 with cleartext support, you need to leave the configprop:server.http2.enabled[] property set to `false`,
and instead apply a customizer specific to your choice of server:
For Tomcat, we need to add an upgrade protocol:
[source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"]
----
@Bean
public TomcatConnectorCustomizer connectorCustomizer() {
return (connector) -> connector.addUpgradeProtocol(new Http2Protocol());
}
----
For Jetty, we need to add a connection factory to the existing connector:
[source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"]
----
@Bean
public JettyServerCustomizer serverCustomizer() {
return (server) -> {
HttpConfiguration configuration = new HttpConfiguration();
configuration.setSendServerVersion(false);
Arrays.stream(server.getConnectors())
.filter(connector -> connector instanceof ServerConnector)
.map(ServerConnector.class::cast)
.forEach(connector -> {
connector.addConnectionFactory(new HTTP2CServerConnectionFactory(configuration));
});
};
}
----
For Netty, we need to add `h2c` as a supported protocol:
[source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"]
----
@Bean
public NettyServerCustomizer serverCustomizer() {
return (server) -> server.protocol(HttpProtocol.H2C);
}
----
For Undertow, we need to enable the HTTP2 option:
[source,java,pending-extract=true,indent=0,subs="verbatim,quotes,attributes"]
----
@Bean
public UndertowBuilderCustomizer builderCustomizer() {
return (builder) -> {
builder.setServerOption(ENABLE_HTTP2, true);
};
}
----
As of Undertow 1.4.0+, both `h2` and `h2c` are supported on JDK 8 without any additional dependencies.