Files
clean-architecture-backend-…/docs/httpclient/support-matrix.md
T
DongHyeonka e6b6e18eae fix(strict-lane)!: 성능 lane이 상한을 재지 않고 통과하지 못하게 한다
문제: 성능 lane의 기계 의존 상한(httpclient 스트리밍 힙 증가, Mongo 시간
gate)이 performance.assertions.enabled 뒤에 있었고 기본값이 자리마다
달랐다(httpclient build false, Mongo build true, Mongo 테스트 코드 false).
workflow만 GRADLE_OPTS로 켰다. 그래서 desktop에서 손으로 돌린
./gradlew :performanceCheck가 httpclient 힙 상한을 재지 않고 통과했다
(2026-11-05 r10 게이트). JPA pool lane도 전에 같은 속성 뒤에서 아무 상한도
비교하지 않았다(PoolLaneClaimTest).

방법: 규칙을 build-logic strict-lane convention 한 곳에 둔다.
- PERFORMANCE lane 테스트 JVM에 performance.assertions.enabled=true를
  넣는다. 빌드(-P, GRADLE_OPTS)나 lane(systemProperty, jvmArgs, task
  설정)이 true 아닌 값을 주면 테스트 전에 실패하고, 지우거나 true로
  바꾸라고 알려 준다. true는 받아 준다(파생 서비스 workflow가 넘긴다).
- PERFORMANCE lane은 skip된 테스트가 있으면 실패한다.
- httpclient·Mongo 테스트는 조건 없이 단언하고 잰 값을 한 줄 남긴다.
  두 leaf의 속성 선언과 integration-main·release workflow의 GRADLE_OPTS
  줄을 지웠다. 사람과 workflow가 같은 명령을 쓴다. verifyStrictLaneStages가
  읽는 run: 줄은 그대로다.
버린 대안: 두 leaf 기본값만 true로(정의가 leaf마다 남아 다음 lane이 다시
복사한다), 속성 삭제만(옛 속성을 기본값 false로 읽는 파생 서비스 테스트가
조용히 건너뛴다), 측정 전용 태스크(쓸 곳이 없다: 숫자만 볼 때는 JMH, 실패한
단언과 매 실행 출력이 값을 남긴다).
같은 원인으로 함께 고친 문서: httpclient support-matrix·release-checklist의
없는 lane 이름 spring62CompatibilityTest와 빠진 main push 주기.

위험·한계: 손으로 돌린 performanceCheck가 이제 상한을 실제로 재므로 느린
기계에서는 실패할 수 있다. JVM 인자 공급자(jvmArgumentProviders)가 넣는
-D는 보지 않는다. Docker가 없을 때 skip되는 통합·시스템 lane은 지금
모두 실패한다(전부 skip이면 executed no test, 아니면 skip 안 되는 컨테이너
테스트가 실패) — 거짓 통과가 아니어서 고치지 않았다.

검증(desktop ~/b4-logs, flock 아래, 노트북과 같은 트리 — git diff sha256 일치):
- RED(고치기 전 트리 + 새 테스트): build-logic 새 테스트 4건이
  UnexpectedBuildSuccess로 실패 — aPerformanceLaneFailsOnAnExceededBound
  WhenTheBuildSetsNoAssertionsProperty, …FailsBeforeTestingWhenTheBuild
  TurnsItsAssertionsOff, …FailsWhenItsOwnDeclarationTurnsTheAssertionsOff,
  …FailsWhenOneOfItsTestsIsSkipped. jvmArgs 경로(…FailsWhenItsJvmArguments
  TurnTheAssertionsOff)도 같은 실패. 실제 lane: 속성 없이
  httpClientPerformanceTest rc=0인데 "skipped machine-dependent bound" 출력.
- GREEN: -p build-logic check javadoc rc=0. :performanceCheck rc=0(lane 5개
  테스트 26, skip 0; httpclient 힙 증가 5,243,880 B / 상한 16,777,216 B,
  Mongo p50·p95·p99 1ms, examined/returned 1.0, pool 대기 0).
  -p optional-platforms performanceCheck rc=0(grpc 1). 두 명령에
  -Pperformance.assertions.enabled=false → rc=1, 6개 lane 모두 테스트 전
  실패. =true → rc=0. verifyStrictLaneStages --dry-run 두 빌드 rc=0,
  architectureCheck rc=0, ci·mainCheck·integrationCheck·releaseCheck·
  performanceCheck --dry-run --configuration-cache rc=0,
  :mainCheck --continue --warning-mode=fail rc=0, -p optional-platforms ci
  rc=0, persistence-mongo:check rc=0, verify-httpclient-docs.py rc=0.
- 이 변경 밖 실패: :ci :verifyDependencyLocks --continue와
  httpclient:check가 CircuitBreakerStatusAccountingTest JDK 2건으로 rc=1.
  기준 커밋 3d73b6f1에서도 10/10 실패(이 트리도 10/10). ci의 다른
  task는 모두 통과했다.

Refs: docs/upgrade/2026-11-maturity-review.md B-43, docs/testing/TESTING_STRATEGY.md 6절
BREAKING CHANGE: PERFORMANCE lane은 performance.assertions.enabled가
true가 아니거나 skip된 테스트가 있으면 실패한다. 자기 성능 lane의 그 속성
선언(false)과 skip을 없앤다.
2026-11-06 20:33:47 +09:00

5.7 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) 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