Provide a How-To for customizing Reactor Netty's TcpClient

Closes gh-17856

Author: wilkinsona

spring-boot-project/spring-boot-docs/src/main/asciidoc/howto.adoc

@@ -1231,6 +1231,19 @@ The following example configures `HttpComponentsClientRequestFactory` with an `H
 include::{code-examples}/web/client/RestTemplateProxyCustomizationExample.java[tag=customizer]
 ----
 
+[[howto-webclient-reactor-netty-customization]]
+=== Configure the TcpClient used by a Reactor Netty-based WebClient
+When Reactor Netty is on the classpath a Reactor Netty-based `WebClient` is auto-configured.
+To customize the client's handling of network connections, provide a `ClientHttpConnector` bean.
+The following example configures a 60 second read timeout and adds a `ReadTimeoutHandler`:
+
+[source,java,indent=0]
+----
+include::{code-examples}/web/reactive/function/client/ReactorNettyClientCustomizationExample.java[tag=custom-http-connector]
+----
+
+TIP: Note the use of `ReactorResourceFactory` for the connection provider and event loop resources.
+This ensures efficient sharing of resources for the server receiving requests and the client making requests.
 
 
 [[howto-logging]]

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/web/reactive/function/client/ReactorNettyClientCustomizationExample.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2012-2019 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.web.reactive.function.client;
+
+import io.netty.channel.ChannelOption;
+import io.netty.handler.timeout.ReadTimeoutHandler;
+import reactor.netty.http.client.HttpClient;
+import reactor.netty.tcp.TcpClient;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.client.reactive.ClientHttpConnector;
+import org.springframework.http.client.reactive.ReactorClientHttpConnector;
+import org.springframework.http.client.reactive.ReactorResourceFactory;
+import org.springframework.web.reactive.function.client.WebClient;
+
+/**
+ * Example configuration for customizing the Reactor Netty-based {@link WebClient}.
+ *
+ * @author Andy Wilkinson
+ */
+@Configuration
+public class ReactorNettyClientCustomizationExample {
+
+	// tag::custom-http-connector[]
+	@Bean
+	ClientHttpConnector clientHttpConnector(ReactorResourceFactory resourceFactory) {
+		TcpClient tcpClient = TcpClient.create(resourceFactory.getConnectionProvider())
+				.runOn(resourceFactory.getLoopResources()).option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 60000)
+				.doOnConnected((connection) -> connection.addHandlerLast(new ReadTimeoutHandler(60)));
+		return new ReactorClientHttpConnector(HttpClient.from(tcpClient));
+	}
+	// end::custom-http-connector[]
+
+}