Update TestRestTemplate's default cookie handling to match RestTemplate's

See gh-49261 Signed-off-by: Apoorv Darshan <ad13dtu@gmail.com>
2026-09-17 20:19:06 +00:00 · 2026-03-12 12:13:27 +00:00
parent 5ca8e0956a
commit 085d522570
12 changed files with 222 additions and 21 deletions
@@ -25,6 +25,8 @@ import org.springframework.boot.ssl.SslBundle;
 /**
 * Settings that can be applied when creating an imperative or reactive HTTP client.
 *
+ * @param cookies the cookie handling strategy to use or null to use the underlying
+ * library's default
 * @param redirects the follow redirect strategy to use or null to redirect whenever the
 * underlying library allows it
 * @param connectTimeout the connect timeout
@@ -33,10 +35,36 @@ import org.springframework.boot.ssl.SslBundle;
 * @author Phillip Webb
 * @since 3.5.0
 */
-public record HttpClientSettings(@Nullable HttpRedirects redirects, @Nullable Duration connectTimeout,
-		@Nullable Duration readTimeout, @Nullable SslBundle sslBundle) {
+public record HttpClientSettings(@Nullable HttpCookies cookies, @Nullable HttpRedirects redirects,
+		@Nullable Duration connectTimeout, @Nullable Duration readTimeout, @Nullable SslBundle sslBundle) {

-	private static final HttpClientSettings defaults = new HttpClientSettings(null, null, null, null);
+	/**
+	 * Create a new {@link HttpClientSettings} instance.
+	 * @param redirects the follow redirect strategy to use
+	 * @param connectTimeout the connect timeout
+	 * @param readTimeout the read timeout
+	 * @param sslBundle the SSL bundle providing SSL configuration
+	 * @deprecated since 4.1.0 for removal in 4.3.0 in favor of
+	 * {@link HttpClientSettings#HttpClientSettings(HttpCookies, HttpRedirects, Duration, Duration, SslBundle)}
+	 */
+	@Deprecated(since = "4.1.0", forRemoval = true)
+	public HttpClientSettings(@Nullable HttpRedirects redirects, @Nullable Duration connectTimeout,
+			@Nullable Duration readTimeout, @Nullable SslBundle sslBundle) {
+		this(null, redirects, connectTimeout, readTimeout, sslBundle);
+	}
+
+	private static final HttpClientSettings defaults = new HttpClientSettings(null, null, null, null, null);
+
+	/**
+	 * Return a new {@link HttpClientSettings} instance with an updated cookie handling
+	 * setting.
+	 * @param cookies the new cookie handling setting
+	 * @return a new {@link HttpClientSettings} instance
+	 * @since 4.1.0
+	 */
+	public HttpClientSettings withCookies(@Nullable HttpCookies cookies) {
+		return new HttpClientSettings(cookies, this.redirects, this.connectTimeout, this.readTimeout, this.sslBundle);
+	}

 	/**
 	 * Return a new {@link HttpClientSettings} instance with an updated connect timeout
@@ -46,7 +74,7 @@ public record HttpClientSettings(@Nullable HttpRedirects redirects, @Nullable Du
 	 * @since 4.0.0
 	 */
 	public HttpClientSettings withConnectTimeout(@Nullable Duration connectTimeout) {
-		return new HttpClientSettings(this.redirects, connectTimeout, this.readTimeout, this.sslBundle);
+		return new HttpClientSettings(this.cookies, this.redirects, connectTimeout, this.readTimeout, this.sslBundle);
 	}

 	/**
@@ -57,7 +85,7 @@ public record HttpClientSettings(@Nullable HttpRedirects redirects, @Nullable Du
 	 * @since 4.0.0
 	 */
 	public HttpClientSettings withReadTimeout(@Nullable Duration readTimeout) {
-		return new HttpClientSettings(this.redirects, this.connectTimeout, readTimeout, this.sslBundle);
+		return new HttpClientSettings(this.cookies, this.redirects, this.connectTimeout, readTimeout, this.sslBundle);
 	}

 	/**
@@ -69,7 +97,7 @@ public record HttpClientSettings(@Nullable HttpRedirects redirects, @Nullable Du
 	 * @since 4.0.0
 	 */
 	public HttpClientSettings withTimeouts(@Nullable Duration connectTimeout, @Nullable Duration readTimeout) {
-		return new HttpClientSettings(this.redirects, connectTimeout, readTimeout, this.sslBundle);
+		return new HttpClientSettings(this.cookies, this.redirects, connectTimeout, readTimeout, this.sslBundle);
 	}

 	/**
@@ -80,7 +108,7 @@ public record HttpClientSettings(@Nullable HttpRedirects redirects, @Nullable Du
 	 * @since 4.0.0
 	 */
 	public HttpClientSettings withSslBundle(@Nullable SslBundle sslBundle) {
-		return new HttpClientSettings(this.redirects, this.connectTimeout, this.readTimeout, sslBundle);
+		return new HttpClientSettings(this.cookies, this.redirects, this.connectTimeout, this.readTimeout, sslBundle);
 	}

 	/**
@@ -90,7 +118,7 @@ public record HttpClientSettings(@Nullable HttpRedirects redirects, @Nullable Du
 	 * @since 4.0.0
 	 */
 	public HttpClientSettings withRedirects(@Nullable HttpRedirects redirects) {
-		return new HttpClientSettings(redirects, this.connectTimeout, this.readTimeout, this.sslBundle);
+		return new HttpClientSettings(this.cookies, redirects, this.connectTimeout, this.readTimeout, this.sslBundle);
 	}

 	/**
@@ -104,11 +132,12 @@ public record HttpClientSettings(@Nullable HttpRedirects redirects, @Nullable Du
 		if (other == null) {
 			return this;
 		}
+		HttpCookies cookies = (cookies() != null) ? cookies() : other.cookies();
 		HttpRedirects redirects = (redirects() != null) ? redirects() : other.redirects();
 		Duration connectTimeout = (connectTimeout() != null) ? connectTimeout() : other.connectTimeout();
 		Duration readTimeout = (readTimeout() != null) ? readTimeout() : other.readTimeout();
 		SslBundle sslBundle = (sslBundle() != null) ? sslBundle() : other.sslBundle();
-		return new HttpClientSettings(redirects, connectTimeout, readTimeout, sslBundle);
+		return new HttpClientSettings(cookies, redirects, connectTimeout, readTimeout, sslBundle);
 	}

 	/**
@@ -0,0 +1,44 @@
+/*
+ * Copyright 2012-present 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.http.client;
+
+import org.apache.hc.client5.http.cookie.StandardCookieSpec;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Adapts {@link HttpCookies} to an
+ * <a href="https://hc.apache.org/httpcomponents-client-ga/">Apache HttpComponents</a>
+ * cookie spec identifier.
+ *
+ * @author Apoorv Darshan
+ */
+final class HttpComponentsCookieSpec {
+
+	private HttpComponentsCookieSpec() {
+	}
+
+	static @Nullable String get(@Nullable HttpCookies cookies) {
+		if (cookies == null) {
+			return null;
+		}
+		return switch (cookies) {
+			case ENABLE_WHEN_POSSIBLE, ENABLE -> StandardCookieSpec.STRICT;
+			case DISABLE -> StandardCookieSpec.IGNORE;
+		};
+	}
+
+}
@@ -180,7 +180,7 @@ public final class HttpComponentsHttpClientBuilder {
 			.useSystemProperties()
 			.setRedirectStrategy(HttpComponentsRedirectStrategy.get(settings.redirects()))
 			.setConnectionManager(createConnectionManager(settings))
-			.setDefaultRequestConfig(createDefaultRequestConfig());
+			.setDefaultRequestConfig(createDefaultRequestConfig(settings));
 		this.customizer.accept(builder);
 		return builder.build();
 	}
@@ -218,8 +218,12 @@ public final class HttpComponentsHttpClientBuilder {
 		return builder.build();
 	}

-	private RequestConfig createDefaultRequestConfig() {
+	private RequestConfig createDefaultRequestConfig(HttpClientSettings settings) {
 		RequestConfig.Builder builder = RequestConfig.custom();
+		String cookieSpec = HttpComponentsCookieSpec.get(settings.cookies());
+		if (cookieSpec != null) {
+			builder.setCookieSpec(cookieSpec);
+		}
 		this.defaultRequestConfigCustomizer.accept(builder);
 		return builder.build();
 	}
@@ -0,0 +1,42 @@
+/*
+ * Copyright 2012-present 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.http.client;
+
+/**
+ * Cookie handling strategies supported by HTTP clients.
+ *
+ * @author Apoorv Darshan
+ * @since 4.1.0
+ */
+public enum HttpCookies {
+
+	/**
+	 * Enable cookies (if the underlying library has support).
+	 */
+	ENABLE_WHEN_POSSIBLE,
+
+	/**
+	 * Enable cookies (fail if the underlying library has no support).
+	 */
+	ENABLE,
+
+	/**
+	 * Disable cookies (fail if the underlying library has no support).
+	 */
+	DISABLE
+
+}
@@ -16,6 +16,8 @@

 package org.springframework.boot.http.client;

+import java.net.CookieHandler;
+import java.net.CookieManager;
 import java.net.http.HttpClient;
 import java.net.http.HttpClient.Redirect;
 import java.util.concurrent.Executor;
@@ -83,6 +85,7 @@ public final class JdkHttpClientBuilder {
 		Assert.isTrue(settings.readTimeout() == null, "'settings' must not have a 'readTimeout'");
 		HttpClient.Builder builder = HttpClient.newBuilder();
 		PropertyMapper map = PropertyMapper.get();
+		map.from(settings::cookies).as(this::asCookieHandler).to(builder::cookieHandler);
 		map.from(settings::redirects).always().as(this::asHttpClientRedirect).to(builder::followRedirects);
 		map.from(settings::connectTimeout).to(builder::connectTimeout);
 		map.from(settings::sslBundle).as(SslBundle::createSslContext).to(builder::sslContext);
@@ -99,6 +102,13 @@ public final class JdkHttpClientBuilder {
 		return parameters;
 	}

+	private @Nullable CookieHandler asCookieHandler(HttpCookies cookies) {
+		return switch (cookies) {
+			case ENABLE_WHEN_POSSIBLE, ENABLE -> new CookieManager();
+			case DISABLE -> null;
+		};
+	}
+
 	private Redirect asHttpClientRedirect(@Nullable HttpRedirects redirects) {
 		if (redirects == null) {
 			return Redirect.NORMAL;
@@ -28,6 +28,7 @@ import org.eclipse.jetty.client.HttpClientTransport;
 import org.eclipse.jetty.client.Request;
 import org.eclipse.jetty.client.transport.HttpClientTransportDynamic;
 import org.eclipse.jetty.client.transport.HttpClientTransportOverHTTP;
+import org.eclipse.jetty.http.HttpCookieStore;
 import org.eclipse.jetty.io.ClientConnector;
 import org.eclipse.jetty.util.ssl.SslContextFactory;
 import org.jspecify.annotations.Nullable;
@@ -140,6 +141,7 @@ public final class JettyHttpClientBuilder {
 		HttpClient httpClient = createHttpClient(settings.readTimeout(), transport);
 		PropertyMapper map = PropertyMapper.get();
 		map.from(settings::connectTimeout).as(Duration::toMillis).to(httpClient::setConnectTimeout);
+		map.from(settings::cookies).as(this::asCookieStore).to(httpClient::setHttpCookieStore);
 		map.from(settings::redirects).always().as(this::followRedirects).to(httpClient::setFollowRedirects);
 		this.customizer.accept(httpClient);
 		return httpClient;
@@ -182,6 +184,13 @@ public final class JettyHttpClientBuilder {
 		return factory;
 	}

+	private @Nullable HttpCookieStore asCookieStore(HttpCookies cookies) {
+		return switch (cookies) {
+			case ENABLE_WHEN_POSSIBLE, ENABLE -> null;
+			case DISABLE -> new HttpCookieStore.Empty();
+		};
+	}
+
 	private boolean followRedirects(@Nullable HttpRedirects redirects) {
 		if (redirects == null) {
 			return true;
@@ -47,7 +47,8 @@ class HttpClientSettingsTests {

 	@Test
 	void createWithNulls() {
-		HttpClientSettings settings = new HttpClientSettings(null, null, null, null);
+		HttpClientSettings settings = new HttpClientSettings(null, null, null, null, null);
+		assertThat(settings.cookies()).isNull();
 		assertThat(settings.redirects()).isNull();
 		assertThat(settings.connectTimeout()).isNull();
 		assertThat(settings.readTimeout()).isNull();
@@ -82,6 +83,16 @@ class HttpClientSettingsTests {
 		assertThat(settings.sslBundle()).isSameAs(sslBundle);
 	}

+	@Test
+	void withCookiesReturnsInstanceWithUpdatedCookies() {
+		HttpClientSettings settings = HttpClientSettings.defaults().withCookies(HttpCookies.DISABLE);
+		assertThat(settings.cookies()).isEqualTo(HttpCookies.DISABLE);
+		assertThat(settings.redirects()).isNull();
+		assertThat(settings.connectTimeout()).isNull();
+		assertThat(settings.readTimeout()).isNull();
+		assertThat(settings.sslBundle()).isNull();
+	}
+
 	@Test
 	void withRedirectsReturnsInstanceWithUpdatedRedirect() {
 		HttpClientSettings settings = HttpClientSettings.defaults().withRedirects(HttpRedirects.DONT_FOLLOW);
@@ -94,8 +105,10 @@ class HttpClientSettingsTests {
 	@Test
 	void orElseReturnsNewInstanceWithUpdatedValues() {
 		SslBundle sslBundle = mock(SslBundle.class);
-		HttpClientSettings settings = new HttpClientSettings(null, ONE_SECOND, null, null)
-			.orElse(new HttpClientSettings(HttpRedirects.FOLLOW_WHEN_POSSIBLE, TWO_SECONDS, TWO_SECONDS, sslBundle));
+		HttpClientSettings settings = new HttpClientSettings(null, null, ONE_SECOND, null, null)
+			.orElse(new HttpClientSettings(HttpCookies.ENABLE, HttpRedirects.FOLLOW_WHEN_POSSIBLE, TWO_SECONDS,
+					TWO_SECONDS, sslBundle));
+		assertThat(settings.cookies()).isEqualTo(HttpCookies.ENABLE);
 		assertThat(settings.redirects()).isEqualTo(HttpRedirects.FOLLOW_WHEN_POSSIBLE);
 		assertThat(settings.connectTimeout()).isEqualTo(ONE_SECOND);
 		assertThat(settings.readTimeout()).isEqualTo(TWO_SECONDS);
@@ -52,14 +52,14 @@ class HttpClientAutoConfigurationTests {
 			.withPropertyValues("spring.http.clients.redirects=dont-follow", "spring.http.clients.connect-timeout=1s",
 					"spring.http.clients.read-timeout=2s")
 			.run((context) -> assertThat(context.getBean(HttpClientSettings.class)).isEqualTo(new HttpClientSettings(
-					HttpRedirects.DONT_FOLLOW, Duration.ofSeconds(1), Duration.ofSeconds(2), null)));
+					null, HttpRedirects.DONT_FOLLOW, Duration.ofSeconds(1), Duration.ofSeconds(2), null)));
 	}

 	@Test
 	void doesNotReplaceUserProvidedHttpClientSettings() {
 		this.contextRunner.withUserConfiguration(TestHttpClientConfiguration.class)
 			.run((context) -> assertThat(context.getBean(HttpClientSettings.class))
-				.isEqualTo(new HttpClientSettings(null, Duration.ofSeconds(1), Duration.ofSeconds(2), null)));
+				.isEqualTo(new HttpClientSettings(null, null, Duration.ofSeconds(1), Duration.ofSeconds(2), null)));
 	}

 	@Configuration(proxyBeanMethods = false)
@@ -93,7 +93,7 @@ class HttpClientSettingsPropertyMapperTests {

 	@Test
 	void mapUsesBaseSettingsForMissingProperties() {
-		HttpClientSettings baseSettings = new HttpClientSettings(HttpRedirects.FOLLOW_WHEN_POSSIBLE,
+		HttpClientSettings baseSettings = new HttpClientSettings(null, HttpRedirects.FOLLOW_WHEN_POSSIBLE,
 				Duration.ofSeconds(15), Duration.ofSeconds(25), null);
 		HttpClientSettingsPropertyMapper mapper = new HttpClientSettingsPropertyMapper(null, baseSettings);
 		TestHttpClientSettingsProperties properties = new TestHttpClientSettingsProperties();
@@ -35,6 +35,7 @@ import org.jspecify.annotations.Nullable;
 import org.springframework.beans.BeanUtils;
 import org.springframework.boot.http.client.ClientHttpRequestFactoryBuilder;
 import org.springframework.boot.http.client.HttpClientSettings;
+import org.springframework.boot.http.client.HttpCookies;
 import org.springframework.boot.http.client.HttpRedirects;
 import org.springframework.boot.ssl.SslBundle;
 import org.springframework.http.client.ClientHttpRequest;
@@ -481,6 +482,20 @@ public class RestTemplateBuilder {
 				this.customizers, this.requestCustomizers);
 	}

+	/**
+	 * Sets the cookie handling strategy on the underlying
+	 * {@link ClientHttpRequestFactory}.
+	 * @param cookies the cookie handling strategy
+	 * @return a new builder instance.
+	 * @since 4.1.0
+	 */
+	public RestTemplateBuilder cookies(HttpCookies cookies) {
+		return new RestTemplateBuilder(this.clientSettings.withCookies(cookies), this.detectRequestFactory,
+				this.rootUri, this.messageConverters, this.interceptors, this.requestFactoryBuilder,
+				this.uriTemplateHandler, this.errorHandler, this.basicAuthentication, this.defaultHeaders,
+				this.customizers, this.requestCustomizers);
+	}
+
 	/**
 	 * Sets the redirect strategy on the underlying {@link ClientHttpRequestFactory}.
 	 * @param redirects the redirect strategy
@@ -41,6 +41,7 @@ import org.springframework.boot.http.client.ClientHttpRequestFactoryBuilder;
 import org.springframework.boot.http.client.HttpClientSettings;
 import org.springframework.boot.http.client.HttpComponentsClientHttpRequestFactoryBuilder;
 import org.springframework.boot.http.client.HttpComponentsHttpClientBuilder.TlsSocketStrategyFactory;
+import org.springframework.boot.http.client.HttpCookies;
 import org.springframework.boot.http.client.HttpRedirects;
 import org.springframework.boot.restclient.RestTemplateBuilder;
 import org.springframework.boot.resttestclient.autoconfigure.AutoConfigureTestRestTemplate;
@@ -69,8 +70,7 @@ import org.springframework.web.util.UriTemplateHandler;
 * status code}.
 * <p>
 * A {@code TestRestTemplate} can optionally carry Basic authentication headers. If Apache
- * Http Client 4.3.2 or better is available (recommended) it will be used as the client,
- * and by default configured to ignore cookies.
+ * Http Client 4.3.2 or better is available (recommended) it will be used as the client.
 * <p>
 * Note: To prevent injection problems this class intentionally does not extend
 * {@link RestTemplate}. If you need access to the underlying {@link RestTemplate} use
@@ -160,10 +160,13 @@ public class TestRestTemplate {
 		return builder;
 	}

+	@SuppressWarnings("deprecation")
 	private static HttpComponentsClientHttpRequestFactoryBuilder applyHttpClientOptions(
 			HttpComponentsClientHttpRequestFactoryBuilder builder, HttpClientOption[] httpClientOptions) {
-		builder = builder.withDefaultRequestConfigCustomizer(
-				new CookieSpecCustomizer(HttpClientOption.ENABLE_COOKIES.isPresent(httpClientOptions)));
+		if (HttpClientOption.ENABLE_COOKIES.isPresent(httpClientOptions)) {
+			builder = builder.withDefaultRequestConfigCustomizer(
+					new CookieSpecCustomizer(true));
+		}
 		if (HttpClientOption.SSL.isPresent(httpClientOptions)) {
 			builder = builder.withTlsSocketStrategyFactory(new SelfSignedTlsSocketStrategyFactory());
 		}
@@ -974,6 +977,19 @@ public class TestRestTemplate {
 		return withClientSettings((settings) -> settings.withRedirects(redirects));
 	}

+	/**
+	 * Creates a new {@code TestRestTemplate} with the same configuration as this one,
+	 * except that it will apply the given {@link HttpCookies}. The request factory used is
+	 * a new instance of the underlying {@link RestTemplate}'s request factory type (when
+	 * possible).
+	 * @param cookies the new cookie settings
+	 * @return the new template
+	 * @since 4.1.0
+	 */
+	public TestRestTemplate withCookies(HttpCookies cookies) {
+		return withClientSettings((settings) -> settings.withCookies(cookies));
+	}
+
 	/**
 	 * Creates a new {@code TestRestTemplate} with the same configuration as this one,
 	 * except that it will apply the given {@link HttpClientSettings}. The request factory
@@ -1036,7 +1052,10 @@ public class TestRestTemplate {

 		/**
 		 * Enable cookies.
+		 * @deprecated since 4.1.0 for removal in 4.3.0 in favor of
+		 * {@link TestRestTemplate#withCookies(HttpCookies)}
 		 */
+		@Deprecated(since = "4.1.0", forRemoval = true)
 		ENABLE_COOKIES,

 		/**
@@ -35,6 +35,7 @@ import org.junit.jupiter.api.Test;

 import org.springframework.boot.http.client.ClientHttpRequestFactoryBuilder;
 import org.springframework.boot.http.client.HttpClientSettings;
+import org.springframework.boot.http.client.HttpCookies;
 import org.springframework.boot.http.client.HttpRedirects;
 import org.springframework.boot.restclient.RestTemplateBuilder;
 import org.springframework.boot.resttestclient.TestRestTemplate.HttpClientOption;
@@ -140,11 +141,26 @@ class TestRestTemplateTests {
 	}

 	@Test
+	@SuppressWarnings("removal")
 	void options() {
 		RequestConfig config = getRequestConfig(new TestRestTemplate(HttpClientOption.ENABLE_COOKIES));
 		assertThat(config.getCookieSpec()).isEqualTo("strict");
 	}

+	@Test
+	void defaultCookieSpecMatchesRestTemplate() {
+		RequestConfig config = getRequestConfig(new TestRestTemplate());
+		assertThat(config.getCookieSpec()).isNull();
+	}
+
+	@Test
+	void withCookies() {
+		TestRestTemplate template = new TestRestTemplate();
+		assertThat(getRequestConfig(template).getCookieSpec()).isNull();
+		assertThat(getRequestConfig(template.withCookies(HttpCookies.ENABLE)).getCookieSpec()).isEqualTo("strict");
+		assertThat(getRequestConfig(template.withCookies(HttpCookies.DISABLE)).getCookieSpec()).isEqualTo("ignoreCookies");
+	}
+
 	@Test
 	void jdkBuilderCanBeSpecifiedWithSpecificRedirects() {
 		RestTemplateBuilder builder = new RestTemplateBuilder()