From 9478cd2dfb79499e4d9b9b83e68d542953cf2b43 Mon Sep 17 00:00:00 2001 From: Brian Clozel Date: Thu, 22 Oct 2020 20:04:35 +0200 Subject: [PATCH] Document how to configure h2c protocol Prior to this commit, the how-to documentation would say that Spring Boot does not support the h2c protocol. While it's not supported out-of-the-box with a configuration property, this protocol can still be configured using server customizers. This commit documents, with code snippets, the server customizers one should use to configure the h2c protocol in an application - for each supported server. Closes gh-21997 --- .../src/main/asciidoc/howto.adoc | 91 +++++++++++++++---- 1 file changed, 75 insertions(+), 16 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc index baa08a8d79..d3866f1b0c 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -582,25 +582,12 @@ This support depends on the chosen web server and the application environment, s [NOTE] ==== -Spring Boot does not support `h2c`, the cleartext version of the HTTP/2 protocol. -So you must <>. +Spring Boot does not advise using `h2c`, the cleartext version of the HTTP/2 protocol. +As a result, the next sections require to <>. +If you still choose to use `h2c`, you can check <>. ==== - -[[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-jetty]] -==== HTTP/2 with Jetty -As of Jetty 9.4.8, HTTP/2 is also supported with the https://www.conscrypt.org/[Conscrypt library]. -To enable that support, your application needs to have two additional dependencies: `org.eclipse.jetty:jetty-alpn-conscrypt-server` and `org.eclipse.jetty.http2:http2-server`. - - - [[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. @@ -621,6 +608,13 @@ This error is not fatal, and the application still starts with HTTP/1.1 SSL supp +[[howto-configure-http2-jetty]] +==== HTTP/2 with Jetty +As of Jetty 9.4.8, HTTP/2 is also supported with the https://www.conscrypt.org/[Conscrypt library]. +To enable that support, your application needs to have two additional dependencies: `org.eclipse.jetty:jetty-alpn-conscrypt-server` and `org.eclipse.jetty.http2:http2-server`. + + + [[howto-configure-http2-netty]] ==== HTTP/2 with Reactor Netty The `spring-boot-webflux-starter` is using by default Reactor Netty as a server. @@ -633,6 +627,71 @@ 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]] +==== h2c with supported servers +To enable `h2c`, 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,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,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,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,indent=0,subs="verbatim,quotes,attributes"] +---- + @Bean + public UndertowBuilderCustomizer builderCustomizer() { + return (builder) -> { + builder.setServerOption(ENABLE_HTTP2, true); + }; + } +---- + + + + [[howto-configure-webserver]] === Configure the Web Server Generally, you should first consider using one of the many available configuration keys and customize your web server by adding new entries in your `application.properties` (or `application.yml`, or environment, etc. see "`<>`").