문제: docs/httpclient 아래 살아 있는 문서 9개가 영어였다(language 예외). repository-adaptation.md는 registry의 leaf 수를 「exactly 19 leaf identities」로, Spring Boot 버전을 4.0.8로 옮겨 적었다(number 예외 두 줄). 같은 문서가 testkit을 `testkit` source set이라고 했지만 1절 표와 실제 코드는 `testFixtures`다. 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·예외·metric·위반 코드·표 구조는 원문으로 둔다. scripts/verify-httpclient-docs.py가 코드에서 뽑는 이름이 모두 문서에 남는다. leaf 수는 registry(src/config/architecture/modules.json)를, 버전은 src/gradle/libs.versions.toml의 `springBoot`를 가리킨다. 등급 이름(Stable, Default, Restricted, Internal, Experimental)은 꼬리표라 원문으로 둔다. env-fields.yaml은 머리 주석만 옮겼다. HttpClientPlatformEnvManifestTest는 주석을 읽지 않는다(`- field:`·`env:` 줄만). configuration-reference.md의 「Three of these」 뒤 목록이 다섯이라 「아래 코드들」로 고쳤다. 버린 대안: 리뷰 번호(RR-03-14 등)를 걷어 내기. 이 작업은 번역이고 내용 감사는 다음 리뷰 몫이라 날짜와 함께 그대로 둔다. 위험·한계: 내용 감사는 하지 않았다. 검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). python3 scripts/verify-httpclient-docs.py PASS(코드에서 뽑은 이름 156개 모두 문서에 있음).
6.2 KiB
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 상한을 단언한다. 지연 숫자는 단언하지 않는다 |