Add setExecutor to JdkClientHttpRequestFactory to allow safe customization of blocking adapter threads

[NYgomets]

Overview JdkClientHttpRequestFactory currently defaults to using SimpleAsyncTaskExecutor when the provided java.net.http.HttpClient does not expose an executor. Since SimpleAsyncTaskExecutor creates a new platform thread per task, this can lead to thread exhaustion under high concurrency, especially for streaming requests or responses.

Unlike ReactorClientHttpRequestFactory (which introduced setExecutor in 6.2.13), JdkClientHttpRequestFactory provides no way to override the executor after instantiation without rebuilding the underlying HttpClient.

Problem Description When users create a standard shared HttpClient:

HttpClient sharedClient = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(10))
    .build(); // No explicit executor set

The constructor of JdkClientHttpRequestFactory executes:

this.executor = httpClient.executor().orElseGet(SimpleAsyncTaskExecutor::new);

Since HttpClient.executor() often returns Optional.empty() when using the default internal pool, Spring falls back to SimpleAsyncTaskExecutor.

This causes three significant issues:

1. Thread Explosion Risk: SimpleAsyncTaskExecutor creates an unbounded number of threads. During blocking I/O (e.g., large file uploads/downloads, streaming responses), this can lead to excessive thread creation and resource exhaustion.

2. No Customization Point: Users cannot assign a bounded thread pool, a VirtualThreadPerTaskExecutor, or a shared application-level executor without rebuilding the entire HttpClient.

3. Inconsistency Across Client Adapters: ReactorClientHttpRequestFactory provides an explicit setExecutor hook, while JdkClientHttpRequestFactory does not.

Proposed Solution Introduce a method such as:

public void setExecutor(Executor executor) {
    Assert.notNull(executor, "Executor must not be null");
    this.executor = executor;
}

This executor would be used for the blocking I/O adapter layer and would not interfere with the internal executor of the underlying JDK HttpClient.

Desired Usage

@Bean
public ClientHttpRequestFactory jdkClientHttpRequestFactory(HttpClient sharedClient) {
    JdkClientHttpRequestFactory factory = new JdkClientHttpRequestFactory(sharedClient);

    // Provide a safe executor (e.g., Virtual Threads or Bounded Pool)
    factory.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
    // or: factory.setExecutor(new ThreadPoolTaskExecutor());

    return factory;
}

Backwards Compatibility This change preserves current behavior:

• If no executor is set, SimpleAsyncTaskExecutor continues to be the default fallback.

• Existing applications experience no change in behavior.

Additional Suggestion A Javadoc note clarifying that the default fallback is SimpleAsyncTaskExecutor (unbounded thread creation) would help guide users toward safer production configurations.

[bclozel]

Thanks for reaching out.

The goal of request factories isn't to copy all available options available from the client itself. Here, the executor is only being used for an internal implementation detail.

Now HttpClient Builder already provides such an option and this is the preferred way, because:

• setting this executor there means the client itself will use it instead of a default executor with a thread pool
• spring will reuse the same executor if configured, leading to better efficiency
• if the JDK client evolves in the future, all API changes will be internal to the request factory: forward compatibility
• the tradeoffs and behavior are already well explained in the client itself and Spring should not make things more complicated for internal reasons
• this pushes developers to focus on the real point of attention here, the HttpClient API

I think we should not expose this additional method as it will lead to confusion and make performance worse compared to using the executor configuration on the builder itself.

[NYgomets]

Thanks @bclozel for the detailed explanation. I understand your point about configuring the executor on HttpClient.Builder being the preferred approach, and I agree that it's architecturally cleaner.

However, I'd like to clarify a few points to better understand the tradeoffs:

1. Performance implications of separate executors

You mentioned that using setExecutor() would make "performance worse." I want to make sure I understand this correctly.

Scenario A: Configuring on HttpClient.Builder (your recommended approach)

Executor sharedExecutor = Executors.newFixedThreadPool(100);

HttpClient client = HttpClient.newBuilder()
    .executor(sharedExecutor)
    .build();

JdkClientHttpRequestFactory factory = new JdkClientHttpRequestFactory(client);
// Spring reuses the same executor

→ Single thread pool shared between HttpClient's internal operations and Spring's blocking I/O operations

Scenario B: If setExecutor() were available

Executor httpExecutor = Executors.newFixedThreadPool(100);
Executor springExecutor = Executors.newFixedThreadPool(100);

HttpClient client = HttpClient.newBuilder()
    .executor(httpExecutor)
    .build();

factory.setExecutor(springExecutor);

→ Two separate thread pools (200 threads total)
Is the "performance worse" concern about:

• Doubled thread pool size → higher memory footprint
• Context switching overhead between different pools
• CPU cache inefficiency when switching between pools

If this is correct, I completely agree with your decision to reject setExecutor().

2. The real concern: SimpleAsyncTaskExecutor fallback

My main concern is that the current implementation has a dangerous default that isn't clearly documented:

public JdkClientHttpRequestFactory(HttpClient httpClient) {
    this.executor = httpClient.executor()
        .orElseGet(SimpleAsyncTaskExecutor::new);  // ⚠️ Unbounded thread creation
}

Problem: When users create a default HttpClient (which is quite common):

HttpClient client = HttpClient.newHttpClient();  // No explicit executor
JdkClientHttpRequestFactory factory = new JdkClientHttpRequestFactory(client);

They unknowingly get SimpleAsyncTaskExecutor, which creates unbounded platform threads. Under high load (e.g., large file uploads, streaming responses), this can lead to resource exhaustion.

The issue is that:

• httpClient.executor() returns Optional.empty() even though HttpClient internally uses a bounded thread pool
• Spring creates a separate SimpleAsyncTaskExecutor with no bounds
• Users don't realize they need to configure the executor explicitly

3. Proposed solution: Documentation improvements

Since adding setExecutor() would compromise performance and architectural clarity, would you consider accepting a documentation PR that:

A. Adds clear warnings to the JavaDoc

/**
 * Create a new instance based on the given {@link HttpClient}.
 * 
 * <p><b>⚠️ Important:</b> If the provided HttpClient does not have an explicit 
 * executor configured via {@link HttpClient.Builder#executor}, this factory will 
 * fall back to {@link SimpleAsyncTaskExecutor}, which creates <b>unbounded 
 * platform threads</b>. This can lead to thread exhaustion under high concurrency 
 * or long-running blocking I/O operations.
 *
 * <p><b>Recommended production configuration:</b>
 * <pre>{@code
 * // Preferred: Single shared thread pool for optimal performance
 * Executor executor = Executors.newVirtualThreadPerTaskExecutor(); // Java 21+
 * // or: Executors.newFixedThreadPool(100) for Java 17
 * 
 * HttpClient client = HttpClient.newBuilder()
 *     .executor(executor)
 *     .build();
 * 
 * ClientHttpRequestFactory factory = new JdkClientHttpRequestFactory(client);
 * }</pre>
 *
 * <p>Alternatively, use the {@link #JdkClientHttpRequestFactory(HttpClient, Executor)} 
 * constructor to provide a separate executor, though this may be less efficient due to 
 * maintaining two thread pools instead of one.
 *
 * @param httpClient the client to base on
 * @see SimpleAsyncTaskExecutor
 * @see #JdkClientHttpRequestFactory(HttpClient, Executor)
 */
public JdkClientHttpRequestFactory(HttpClient httpClient) {
    // ...
}

B. Updates reference documentation

Add a section explaining:

• Why configuring on HttpClient.Builder is preferred (single pool = better performance)
• The risks of the default fallback
• Clear migration examples for common patterns

Summary
I fully agree with your architectural decision against setExecutor(). My concern is purely about helping users avoid the SimpleAsyncTaskExecutor trap.

Would a documentation-focused PR be acceptable? I'm happy to prepare one if you think this would add value.

Thanks again for your time and consideration!

[bclozel]

1. Performance implications of separate executors

Yes, that's correct.

2. The real concern: SimpleAsyncTaskExecutor fallback
   ...
   They unknowingly get SimpleAsyncTaskExecutor, which creates unbounded platform threads. Under high load (e.g., large file uploads, streaming responses), this can lead to resource exhaustion.

If I understand correctly, you have met this scenario in production and you would like to document that. Can you explain what lead to resource exhaustion? That's quite strange as I think this would need a very specific scenario and low overall resources for that to happen.

I'm not sure we can consider this as unbounded, because I would assume HttpClient bounds this in the first place through its connection pool. Can you share your findings and point to documentation stating that the connection pool is unbounded? If the client itself defaults to a thread pool of 100, doesn't this mean that you would get at most 100 active connections in parallel? Please advise.

Adds clear warnings to the JavaDoc

I don't think this description matches the reality. For example, the SimpleAsyncTaskExecutor created by Spring will have close to no impact if the main use case is many requests in parallel and the server streaming data. Again, your experience in production and your findings would be interesting.

[NYgomets]

You're absolutely right. Thank you for the detailed questions—they helped me realize my mistake.
I was conflating connection concurrency (already limited by HttpClient) with thread creation (SimpleAsyncTaskExecutor). After digging deeper:

• HttpClient's connection pool already provides necessary bounds
• Spring's executor is only for blocking I/O operations, not HTTP requests
• My concern was theoretical without production evidence

The "unbounded executor" doesn't lead to unbounded resources because HttpClient's connection management happens first.

this was a valuable learning experience