Add 'Global HTTP Client Configuration' reference docs section

Update documentation with information on how to configure the HTTP
client globally.

Closes gh-42888

Author: philwebb

spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/io/rest-client.adoc

@@ -112,6 +112,8 @@ To make an application-wide, additive customization to all `RestClient.Builder`
 Finally, you can fall back to the original API and use `RestClient.create()`.
 In that case, no auto-configuration or `RestClientCustomizer` is applied.
 
+TIP: You can also change the xref:io/rest-client.adoc#io.rest-client.clienthttprequestfactory.configuration[global HTTP client configuration].
+
 
 
 [[io.rest-client.restclient.ssl]]
@@ -175,6 +177,8 @@ include-code::MyRestTemplateBuilderConfiguration[]
 The most extreme (and rarely used) option is to create your own `RestTemplateBuilder` bean without using a configurer.
 In addition to replacing the auto-configured builder, this also prevents any `RestTemplateCustomizer` beans from being used.
 
+TIP: You can also change the xref:io/rest-client.adoc#io.rest-client.clienthttprequestfactory.configuration[global HTTP client configuration].
+
 
 
 [[io.rest-client.resttemplate.ssl]]
@@ -195,7 +199,44 @@ In order of preference, the following clients are supported:
 . Apache HttpClient
 . Jetty HttpClient
 . Reactor Netty HttpClient
-. OkHttp (deprecated)
-. Simple JDK client (`HttpURLConnection`)
+. JDK client (`java.net.http.HttpClient`)
+. Simple JDK client (`java.net.HttpURLConnection`)
+
+If multiple clients are available on the classpath, and not global configuration is provided, the most preferred client will be used.
+
+
+
+[[io.rest-client.clienthttprequestfactory.configuration]]
+=== Global HTTP Client Configuration
+
+If the the auto-detected HTTP client does not meet your needs, you can use the configprop:spring.http.client.factory[] property to pick a specific factory.
+For example, if you have Apache HttpClient on your classpath, but you prefer Jetty's `HttpClient` you can add use the following:
+
+[configprops,yaml]
+----
+spring:
+  http:
+    client:
+      factory: jetty
+----
+
+You can also set properties to change defaults that will be applied to all clients.
+For example, you may want to change timeouts and if redirects are followed:
+
+[configprops,yaml]
+----
+spring:
+  http:
+    client:
+      connect-timeout: 2s
+      read-timeout: 1s
+      redirects: dont-follow
+----
+
+For more complex customizations, you can declare your own `ClientHttpRequestFactoryBuilder` bean which will cause auto-configuration to back off.
+This can be useful when you need to customize some of the internals of the underlying HTTP library.
+
+For example, the following will use a JDK client configured with a specific `java.net.ProxySelector`:
+
+include-code::MyClientHttpConfiguration[]
 
-If multiple clients are available on the classpath, the most preferred client will be used.

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/clienthttprequestfactory/configuration/MyClientHttpConfiguration.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2012-2024 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.io.restclient.clienthttprequestfactory.configuration;
+
+import java.net.ProxySelector;
+
+import org.springframework.boot.http.client.ClientHttpRequestFactoryBuilder;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration(proxyBeanMethods = false)
+public class MyClientHttpConfiguration {
+
+	@Bean
+	ClientHttpRequestFactoryBuilder<?> clientHttpRequestFactoryBuilder(ProxySelector proxySelector) {
+		return ClientHttpRequestFactoryBuilder.jdk()
+			.withHttpClientCustomizer((builder) -> builder.proxy(proxySelector));
+	}
+
+}

spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/clienthttprequestfactory/configuration/MyClientHttpConfiguration.kt

@@ -0,0 +1,18 @@
+package org.springframework.boot.docs.io.restclient.clienthttprequestfactory.configuration
+
+import org.springframework.boot.http.client.ClientHttpRequestFactoryBuilder
+import org.springframework.context.annotation.Bean
+import org.springframework.context.annotation.Configuration
+import java.net.ProxySelector
+import java.net.http.HttpClient
+
+@Configuration(proxyBeanMethods = false)
+class MyClientHttpConfiguration {
+
+	@Bean
+	fun clientHttpRequestFactoryBuilder(proxySelector: ProxySelector): ClientHttpRequestFactoryBuilder<*>? {
+		return ClientHttpRequestFactoryBuilder.jdk()
+				.withHttpClientCustomizer { builder -> builder.proxy(proxySelector) }
+	}
+
+}