# HTTP Client 플랫폼 — 지원 매트릭스 등급은 설계서 §6과 §29를 따른다. 행이 **Stable**이려면 transport를 넘는 계약 suite가 그것을 증명해야 한다. suite가 증명하지 못하는 것은 **Experimental**이고 그렇다고 밝힌다. 등급 이름(Stable, Default, Restricted, Internal, Experimental)은 원문 그대로 쓴다. ## Spring API | API | 등급 | 역할 | 제약 | |---|---|---|---| | `RestClient` | Stable | blocking 실행(유일한 실행 모델) | 동시성 상한과 실제 기한이 필수다 | | HTTP Service Client(`@HttpExchange`) | Default | 선언형 타입 있는 client | 연산 metadata가 필수다 | | Generic Exchange (H2) | Restricted | 동적 method, 경로, 본문 | Base URL과 정책은 바꿀 수 없다 | | Dynamic Target (H3) | Restricted | 사용자가 준 URL | 따로 된 SSRF 정책. credential을 물려받지 않는다 | | Native 엔진 | Internal | 엔진별 설정 | 애플리케이션이 쓰는 API가 절대 아니다 | ## Transport 플랫폼은 blocking만 한다(결정 9, 2026-09-25). 모든 호출은 호출자의 스레드(이 템플릿에서는 virtual thread)에서 `RestClient`를 거쳐 돈다. reactive 실행 경로도, `WebClient`도, Reactor Netty transport도 없다. | Transport | HTTP/1.1 | HTTP/2 | HTTP/3 | 등급 | 확인하는 것 | |---|---:|---:|---:|---|---| | Apache HttpClient 5 (classic) | 된다 | **안 된다** | 안 된다 | Stable(기본) | `httpClientStableContractTest`, `NegotiatedProtocolContractTest` | | JDK HttpClient | 된다 | 된다(TLS/ALPN) | 안 된다 | Stable(가벼움, HTTP/2) | `NegotiatedProtocolContractTest` | | Jetty | 된다 | 된다 | 된다 | **Experimental** | `Http3OptInTest`뿐 | | Simple request factory | 제한적 | 안 된다 | 안 된다 | 로컬 테스트 전용 | 운영에서는 `ClientProfileValidator`가 거부한다 | ### 여기서 Apache가 HTTP/1.1인 이유 설계서 §6.2는 Apache HttpClient 5를 HTTP/2 가능으로 등급 매긴다. 라이브러리는 그렇다. 다만 **async** client에서다. Spring의 `HttpComponentsClientHttpRequestFactory`는 **classic** client를 쓰고, 그것은 HTTP/1.1만 한다. `NegotiatedProtocolContractTest`는 이것을 가정하지 않고 잰다. classic client는 prior-knowledge h2c 서버에 대해 바로 실패한다. 그래서 `ApacheBlockingTransportProvider.capabilities()`는 HTTP/1.1을 선언한다. Apache와 `HTTP_2`를 짝지은 profile은 이 표가 다르게 주장하는 동안 조용히 HTTP/1.1로 도는 대신 시작 때 거부된다. **HTTP/2는 JDK transport가 맡는다.** 설정에서 읽지 않고, 실제 TLS handshake 뒤 client 쪽에서 잰다. HTTP/2만으로 제한할 수 있는 transport는 없으므로 `HTTP_2`만 선언한 profile은 거부한다(`HTTP2_REQUIRED_TRANSPORT_UNSUPPORTED`). JDK transport는 `routeScopedPool=false`, `boundedPendingAcquireQueue=false`, `dynamicTargetStable=false`를 선언한다. 그중 하나라도 필요한 profile은 약한 보장으로 돌지 않고 시작 때 거부된다. 그래서 Apache와 JDK 사이의 선택은 진짜 맞바꿈이다. Apache는 route 범위 pool과 Dynamic Target 고정을 주고, JDK는 HTTP/2를 준다. ## Capability 관문 | Capability | 관문 | |---|---| | Dynamic Target (H3) | Apache만. JDK와 Jetty는 거부한다 | | HTTP/3 | `experimentalAcknowledgement`가 `I_ACCEPT_HTTP3_EXPERIMENTAL_SEMANTICS`와 같아야 한다 | | origin을 넘는 redirect | profile마다 골라 켠다. hop에서 credential을 지운다 | | 재시도 | 증거 기반. HTTP method만으로 켜지지 않는다 | ## CI 매트릭스 | Profile | 빈도 | 릴리스 게이트 | Task | |---|---|---|---| | Spring Framework 7.0(저장소 기준) | 이 leaf를 건드린 PR, main push, 릴리스 | 필수 | `spring70CompatibilityTest` | | Spring Framework 6.2 API 면 | 모든 PR(`check`), 릴리스 | 필수 | `spring62ApiSurfaceScan` | | Apache HC5 + RestClient | 이 leaf를 건드린 PR(두 transport는 `check`로 모든 PR에서 함께 돈다), 릴리스 | 필수 | `httpClientStableContractTest -Phttpclient.contract.transports=apache` | | JDK HttpClient + RestClient | 이 leaf를 건드린 PR(두 transport는 `check`로 모든 PR에서 함께 돈다), 릴리스 | 필수 | `httpClientStableContractTest -Phttpclient.contract.transports=jdk` | | SSRF / 가짓수 suite | 모든 PR(`check`), 릴리스 | 필수 | `httpClientSecurityTest` | | Toxiproxy 장애 suite | main push, nightly(`integrationCheck`), 릴리스 | 필수 | `httpClientFailureInjectionTest` | | 성능 인증 | main push, nightly(`performanceCheck`), 릴리스 | 필수 | `httpClientPerformanceTest`(모든 상한을 단언. 끄는 스위치가 없다) | | Jetty HTTP/3 | main push, nightly | Experimental, 막지 않음 | `test -Phttp3.tests.enabled=true` | ### Spring 6.2 lane의 알려진 한계 이 저장소의 Spring Boot 4.0 기준은 Spring Framework 7을 고정한다. 그래서 여기서는 실제 6.2 런타임을 풀 수 없다. `spring62ApiSurfaceScan`은 대신 **API 면**을 확인한다. 공통 package가 Spring 7 전용 타입을 참조하지 않아야 하고, 어떤 클래스도 `org.springframework.web.service.registry`를 쓰지 않아야 한다. 실제 6.2 배포판에 대해 suite를 돌리려면 그 계열의 host 프로젝트가 필요하다. 이 한계는 통과하는 검사 뒤에 숨기지 않고 밝혀 둔다. ## Suite가 증명하지 않는 것 매트릭스를 바람이 아니라 측정으로 읽게 하려고 적는다. | 빈곳 | 이유 | 대신 증명하는 것 | |---|---|---| | HTTP/2 frame 주입(`REFUSED_STREAM`, 임의 `GOAWAY`) | fixture 서버에 frame 수준 제어가 없고, 전용 h2 서버는 여기서 얻는 보장보다 큰 의존성이다 | `Http2EvidenceMapperTest`가 frame → 증거 대응을, `NegotiatedProtocolContractTest`가 h2가 정말 협상되는지를 증명한다 | | Spring 6.2 런타임 | 이 저장소의 Boot 4.0 기준이 Spring 7을 고정한다 | `spring62ApiSurfaceScan`이 공통 package를 6.2 API 면 안에 가둔다 | | 성능 지연 기준선 | 빌드 agent에서 잰 숫자는 인증이 아니다 | `httpClientPerformanceTest`가 매번 구조적 상한과 스트리밍 heap 상한을 단언한다. 지연 숫자는 단언하지 않는다 |