What changed
The shared URLSession Tuist uses to download and upload cache artifacts (cli/Sources/TuistHTTP/URLSession+Tuist.swift) had three HTTP settings hardcoded with no override:
timeoutIntervalForResource = 90stimeoutIntervalForRequest = 120shttpMaximumConnectionsPerHost = 20
This PR makes all three tunable via environment variables, following the existing TUIST_CACHE_CONCURRENCY_LIMIT pattern, with the current values kept as defaults:
| Env var |
Setting |
Default |
TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE |
timeoutIntervalForResource |
90 |
TUIST_HTTP_TIMEOUT_INTERVAL_FOR_REQUEST |
timeoutIntervalForRequest |
120 |
TUIST_HTTP_MAXIMUM_CONNECTIONS_PER_HOST |
httpMaximumConnectionsPerHost |
20 |
Reads go through the existing Environment.current.variables abstraction with a parse-failure fallback to the default, so behavior is unchanged when the vars are unset or hold a non-numeric value.
Why
A self-hosted operator reported intermittent cache-download timeouts. On a shared/congested network path (corporate proxy → their infra → S3), cache downloads are fine off-peak but degrade under daytime congestion. When that happens, individual downloads starve at the proxy and hit the client’s timeoutIntervalForResource of 90s, after which Tuist falls back to building that module from source — far more expensive than waiting a bit longer for the cached binary.
The key signal that this is connection starvation rather than artifact size: during peak congestion, modules from under 1 MB up to ~30 MB all hit the same 90s wall, while some larger modules still completed; off-peak the same path downloads everything cleanly. With the timeout hardcoded, there was no way to turn a recoverable-but-slow download back into a cache hit.
Raising TUIST_HTTP_TIMEOUT_INTERVAL_FOR_RESOURCE lets a slow-but-recoverable download finish as a cache hit instead of falling back to a build from source.
Scope / alternatives considered
This is the near-term knob. The longer-term direction discussed with the reporter — an adaptive mode that adjusts download concurrency based on observed timeouts/latency, building on the static cap from #9235 — is intentionally out of scope here; that’s a larger change. Serving the module cache from nearby Kura nodes instead of S3 (self-hosting cache nodes) remains the recommended long-term setup, but even with cache nodes this client-side timeout knob is useful for any residual slow path.
Developer/user impact
Self-hosted operators (and anyone on a constrained/proxied link) can now tune the HTTP timeouts and per-host connection limit to their network. No change for anyone who leaves the vars unset.
Validation
- Added unit tests in
cli/Tests/TuistHTTPTests/URLSessionTuistTests.swift covering defaults, env overrides, and fallback on invalid values.
swift test --filter URLSessionTuistTests → 10/10 pass.- Documented the knobs under Configuration in the module-cache guide.
🤖 Generated with Claude Code
T