Files
clean-architecture-backend-…/docs/httpclient/support-matrix.md
T

5.4 KiB

HTTP Client Platform — Support Matrix

Grades follow design §6 and §29. A row is Stable only when the cross-transport contract suite proves it; anything the suite cannot prove is Experimental and says so.

Spring API

API Grade Role Constraint
RestClient Stable Blocking execution (the only execution model) Bounded concurrency and an effective deadline are mandatory
HTTP Service Client (@HttpExchange) Default Declarative typed client Operation metadata is mandatory
Generic Exchange (H2) Restricted Dynamic method, path, body Base URL and policy are immutable
Dynamic Target (H3) Restricted User-supplied URL Separate SSRF policy; inherits no credential
Native engine Internal Engine-specific configuration Never an application-facing API

Transports

The platform is blocking only (decision 9, 2026-09-25): every call runs on the caller's thread — a virtual thread in this template — through RestClient. There is no reactive execution path, no WebClient, and no Reactor Netty transport.

Transport HTTP/1.1 HTTP/2 HTTP/3 Grade Verified by
Apache HttpClient 5 (classic) yes no no Stable (default) httpClientStableContractTest, NegotiatedProtocolContractTest
JDK HttpClient yes yes (TLS/ALPN) no Stable (lightweight, HTTP/2) NegotiatedProtocolContractTest
Jetty yes yes yes Experimental Http3OptInTest only
Simple request factory limited no no Local test only rejected in production by ClientProfileValidator

Apache is HTTP/1.1 here, and why

Design §6.2 grades Apache HttpClient 5 as HTTP/2-capable, and the library is — in its async client. Spring's HttpComponentsClientHttpRequestFactory drives the classic client, which speaks HTTP/1.1 only. NegotiatedProtocolContractTest measures this rather than assuming it: the classic client fails outright against a prior-knowledge h2c server.

So ApacheBlockingTransportProvider.capabilities() declares HTTP/1.1, and a profile that pairs Apache with HTTP_2 is rejected at startup instead of quietly running HTTP/1.1 while this table claims otherwise. HTTP/2 is served by the JDK transport, measured from the client after a real TLS handshake, not read from configuration. No transport can be restricted to HTTP/2 alone, so a profile that declares only HTTP_2 is refused (HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED).

The JDK transport declares routeScopedPool=false, boundedPendingAcquireQueue=false, and dynamicTargetStable=false. A profile that needs any of those is rejected at startup rather than served with weaker guarantees. Choosing between Apache and JDK is therefore a real trade: Apache gives route-scoped pooling and Dynamic Target pinning, JDK gives HTTP/2.

Capability gates

Capability Gate
Dynamic Target (H3) Apache only; JDK and Jetty are rejected
HTTP/3 experimentalAcknowledgement must equal I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS
Cross-origin redirect opt-in per profile; credentials are stripped on the hop
Retry evidence-based; never enabled by HTTP method alone

CI matrix

Profile Frequency Release gate Task
Spring Framework 7.0 (repository baseline) every PR required spring70CompatibilityTest
Spring Framework 6.2 API surface every PR required spring62CompatibilityTest
Apache HC5 + RestClient every PR required httpClientStableContractTest -Phttpclient.contract.transports=apache
JDK HttpClient + RestClient every PR required httpClientStableContractTest -Phttpclient.contract.transports=jdk
SSRF / cardinality suite every PR required httpClientSecurityTest
Toxiproxy fault suite nightly, release required httpClientFailureInjectionTest
Performance certification nightly, release required httpClientPerformanceTest -Pperformance.assertions.enabled=true
Jetty HTTP/3 nightly Experimental, non-blocking test -Phttp3.tests.enabled=true

Known limitation of the Spring 6.2 lane

This repository's Spring Boot 4.0 baseline pins Spring Framework 7, so a real 6.2 runtime cannot be resolved here. spring62CompatibilityTest therefore verifies the API surface: the common packages must not reference any Spring 7-only type, and no class uses org.springframework.web.service.registry. Executing the suite against an actual 6.2 distribution requires a host project on that line. This limitation is stated rather than hidden behind a passing check.

What the suites do not prove

Stated so the matrix is read as a measurement rather than an aspiration.

Gap Why What is proven instead
HTTP/2 frame injection (REFUSED_STREAM, arbitrary GOAWAY) The fixture server exposes no frame-level control, and a purpose-built h2 server is a larger dependency than the guarantee is worth here Http2EvidenceMapperTest proves the frame → evidence mapping, and NegotiatedProtocolContractTest proves h2 is really negotiated
Spring 6.2 runtime This repository's Boot 4.0 baseline pins Spring 7 spring62CompatibilityTest confines the common packages to the 6.2 API surface
Performance latency baseline Numbers measured on a build agent are not a certification httpClientPerformanceTest asserts structural bounds unconditionally; latency and heap bounds run under -Pperformance.assertions.enabled=true