From 04d4d9473e2a10af4483feff74b75b7b5b2a6e75 Mon Sep 17 00:00:00 2001 From: halo Date: Wed, 10 Jun 2026 08:40:26 +0900 Subject: [PATCH] docs: document that SimpleClientHttpRequestFactory is not supported in WebMVC gateway GH-3451: HttpURLConnection (used by SimpleClientHttpRequestFactory) throws exceptions on 4xx/5xx responses instead of returning the response, causing the gateway to forward a 500 instead of the actual downstream status. Added an "HTTP Client" section to how-it-works.adoc documenting: - Supported clients (Apache HC5, Jetty, JDK HttpClient) in priority order - explicit spring.http.clients.imperative.factory property - WARNING that SimpleClientHttpRequestFactory is unsupported and why Closes gh-3451 Co-Authored-By: Claude Sonnet 4.6 --- .../how-it-works.adoc | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/how-it-works.adoc b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/how-it-works.adoc index 2364aafcf..218432f9d 100644 --- a/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/how-it-works.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-gateway-server-webmvc/how-it-works.adoc @@ -12,5 +12,25 @@ In addition to custom `HandlerFunctions` for HTTP forwarding, Spring Cloud Gatew There are additional `*FilterFunctions` classes for optional filters that are documented along with each filter. +[[gateway-http-client]] +== HTTP Client + +Spring Cloud Gateway Server MVC uses Spring Boot's `RestClient` to forward proxied requests to downstream services. +The HTTP client library is selected automatically from what is on the classpath, in order of priority: + +1. https://hc.apache.org/httpcomponents-client-5.x/[Apache HttpComponents 5] (`org.apache.hc.client5:httpclient5`) +2. https://eclipse.dev/jetty/[Jetty HttpClient] (`org.eclipse.jetty:jetty-client`) +3. JDK `HttpClient` (available since Java 11 — used when neither of the above is present) + +You can also set `spring.http.clients.imperative.factory` explicitly to `apache`, `jetty`, or `jdk`. + +[WARNING] +==== +`SimpleClientHttpRequestFactory` (backed by `java.net.HttpURLConnection`) is *not* supported by Spring Cloud Gateway Server MVC. +`HttpURLConnection` throws an exception (such as `java.io.FileNotFoundException`) on 4xx/5xx responses rather than returning the response body, which prevents the gateway from correctly forwarding error responses to the client. + +Do not declare a `ClientHttpRequestFactory` bean (or set `spring.http.clients.imperative.factory=simple`) that results in `SimpleClientHttpRequestFactory` being used. +If you need to customize the HTTP client, configure one of the supported implementations listed above instead. +==== WARNING: Any path defined on a route URI will be ignored.