# 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) | PR touching this leaf, main push, release | required | `spring70CompatibilityTest` | | Spring Framework 6.2 API surface | every PR (`check`), release | required | `spring62ApiSurfaceScan` | | Apache HC5 + RestClient | PR touching this leaf (both transports together on every PR through `check`), release | required | `httpClientStableContractTest -Phttpclient.contract.transports=apache` | | JDK HttpClient + RestClient | PR touching this leaf (both transports together on every PR through `check`), release | required | `httpClientStableContractTest -Phttpclient.contract.transports=jdk` | | SSRF / cardinality suite | every PR (`check`), release | required | `httpClientSecurityTest` | | Toxiproxy fault suite | main push, nightly (`integrationCheck`), release | required | `httpClientFailureInjectionTest` | | Performance certification | main push, nightly (`performanceCheck`), release | required | `httpClientPerformanceTest` (every bound asserted; no switch turns them off) | | Jetty HTTP/3 | main push, 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. `spring62ApiSurfaceScan` 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 | `spring62ApiSurfaceScan` 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 its structural bounds and the streaming heap bound in every run; it asserts no latency figure |