Exposing Maximum Connections Per Route in Ktor HttpClient Apache Engine

Question

The goal is to decide whether the default maximum connections per route limit (currently hard‑coded to 20) for the Apache engine should be exposed through the HttpClient configuration API.

Constraints include preserving backward compatibility, avoiding unintended side effects for users of other engines, and aligning the new setting with Ktor’s existing configuration patterns. There is uncertainty about whether exposing this value will provide needed flexibility without encouraging misuse, and what default should be retained to keep current behavior.

Should the maximum connections per route be configurable through HttpClient engine settings? If exposed, what default value should be preserved to maintain current behavior? How would this setting interact with existing pool configuration options across different engines?

Zoha · Answer

Answer
Yes – exposing the maximum connections per route for the Apache engine through the HttpClient configuration API is advisable, provided the default value is kept at the current hard‑coded 20 to preserve existing behavior.
Confirmed facts (from the research brief)

The Apache engine allows customization of the underlying Apache HttpAsyncClient via an engine { } block.
The property that controls the per‑route limit is maxConnectionsPerRoute.
A related property, maxConnections, caps the total number of concurrent connections across all routes.
Default values in many Ktor releases are low (≈2‑5) which can cause request queuing under high concurrency.

Likely explanation / recommendation
Making maxConnectionsPerRoute configurable gives developers the ability to tune concurrency for specific hosts without affecting the global pool. Keeping the default at 20 ensures that existing applications see no change in behavior, satisfying the backward‑compatibility requirement. The setting should be scoped to the Apache engine so that other engines (CIO, Darwin, etc.) simply ignore it or raise a clear configuration error if mistakenly applied.
Steps to expose the setting

Add an optional maxConnectionsPerRoute parameter to the Apache engine configuration block.
When the parameter is omitted, use the hard‑coded value 20 (the current default).
When supplied, pass the value to the underlying HttpAsyncClient builder (setMaxConnPerRoute or equivalent).
Validate that maxConnectionsPerRoute ≤ maxConnections (if both are set) and log a warning otherwise.
Document the property alongside existing engine options and note that it only affects the Apache engine.

Interaction with other engines

CIO engine uses its own coroutine‑based pool and does not have a per‑route limit; the property would be ignored.
Darwin (Apple) engine relies on URLSession, which manages connections internally; exposing the property would have no effect.
Thus the new setting is engine‑specific and does not introduce cross‑engine side effects.

Missing diagnostic detail
To confirm that the default of 20 matches your actual Ktor version, please specify the Ktor version you are using (e.g., 2.3.0, 2.2.0). If the version differs, the default may need adjustment.

Exposing Maximum Connections Per Route in Ktor HttpClient Apache Engine

1 answer

0 question comments

Answer

Confirmed facts (from the research brief)

Likely explanation / recommendation

Steps to expose the setting

Interaction with other engines

Missing diagnostic detail

Your perspective belongs here.