fix(http-client): guard HTTP/2 defaults against unsupported libcurl builds

[joshtrichards]

• Resolves: HTTP client issue with libcurl without HTTP/2 support #58528

Summary

Only enable HTTP/2 defaults when local libcurl supports HTTP/2. Also refactors buildRequestOptions() into smaller helpers.

Motivation

Improve readability of the request option setup and fix #58528, where HTTP/2 defaults can break setups with libcurl builds that do not support HTTP/2.

What changed

• extract request option setup into smaller private helpers
• simplify proxy, header, redirect, and legacy option handling
• only set RequestOptions::VERSION and curl HTTP/2 options when libcurl supports HTTP/2
• update ClientTest to cover both HTTP/2-supported and unsupported cases deterministically

Related

• perf(client): enable HTTP/2 and brotli support in internal HTTP client #55433

Notes

• First commit is purely refactor
• Second commit is the fix for HTTP client issue with libcurl without HTTP/2 support #58528
• Balance of commits are test additions/revisions followed by tidying/fixup

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)

AI (if applicable)

• The content of this PR was partly or fully generated using AI

[joshtrichards]

/backport to stable33

[ernolf]

Thanks for the effort. I have to decline this PR, though I'm happy to discuss if others see this differently.

The removal of the HTTP/2 guard in #55433 was a deliberate decision:
HTTP/2 support has been present in every PHP-supported libcurl version for years:

CURL_HTTP_VERSION_2_0 and CURL_VERSION_HTTP2 (the feature flag) were both introduced in libcurl 7.33.0 (October 2013) — see commits curl/curl@698e3bd and curl/curl@b77997e, both from September 2013. CURL_HTTP_VERSION_2TLS followed later in 7.47.0 (January 2016).

A system where supportsHttp2() returns true — meaning CURL_VERSION_HTTP2 is set in the features bitmask — but CURL_HTTP_VERSION_2TLS is not defined, would require a libcurl build from the 7.33.0–7.46.x range. The newest of those (7.46.0) was released on December 2, 2015 — making it at minimum a 10-year-old build. The defined('CURL_HTTP_VERSION_2TLS') check on a PHP constant that comes from the libcurl headers at PHP compile time is designed here as a runtime guard, but it targets a scenario that is purely theoretical in any real-world deployment today. This complicates the logic without any practical benefit.

Any libcurl build old enough to lack CURL_HTTP_VERSION_2TLS predates the very first Nextcloud release (September 2016). Running Nextcloud against such a build means running against a library with years of unpatched CVEs — including TLS and HTTP/2 vulnerabilities. Silently falling back to HTTP/1.1 in that scenario does not make the setup safer; it obscures a serious underlying problem that the server operator needs to fix. A hard failure with a clear error is, in my view, the correct behavior.

What this PR does is reverse that decision by silently degrading to HTTP/1.1 for a vanishingly small group of users with outdated builds. Instead of those few users being prompted to fix their environment, the server permanently carries the complexity — and the degradation becomes invisible.

The correct response to #58528 is, from my perspective, documentation or a clear error message pointing users to upgrade their libcurl build — not a runtime guard that rewards neglected setups.

The refactoring bundled into this PR makes it harder to review the actual fix in isolation, and it's not something I'd want merged separately either — but I acknowledge that's a matter of taste.

---

ernolf