설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
5.9 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 | Bounded concurrency and an effective deadline are mandatory |
WebClient |
Stable | Reactive, streaming, SSE | No blocking work on the event loop |
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
| Transport | Blocking | Reactive | HTTP/1.1 | HTTP/2 | HTTP/3 | Grade | Verified by |
|---|---|---|---|---|---|---|---|
| Apache HttpClient 5 (classic) | yes | no | yes | no | no | Stable (blocking default) | httpClientStableContractTest, NegotiatedProtocolContractTest |
| JDK HttpClient | yes | sendAsync |
yes | yes (TLS/ALPN) | no | Stable (lightweight, blocking HTTP/2) | NegotiatedProtocolContractTest |
| Reactor Netty | limited | yes | yes | yes | experimental | Stable (reactive default) | NegotiatedProtocolContractTest |
| Jetty | facade | yes | yes | yes | yes | Experimental | Http3OptInTest only |
| Simple request factory | yes | no | 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. Blocking HTTP/2 is served by the JDK transport; reactive HTTP/2 by Reactor
Netty. Both are measured from the client after a real TLS handshake, not read from configuration.
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 and Reactor Netty 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 |
| Reactor Netty + WebClient | every PR | required | httpClientStableContractTest -Phttpclient.contract.transports=reactor |
| SSRF / cardinality suite | every PR | required | httpClientSecurityTest |
| Toxiproxy fault suite | nightly, release | required | httpClientFailureInjectionTest |
| Event-loop blocking (BlockHound) | every PR | required | httpClientBlockHoundTest |
| 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 |
| Netty buffer-leak detection | Netty reports a leak when an unreferenced buffer is collected, which the suite does not force | NettyLeakDetectionExtension asserts the PARANOID detector is live and reports nothing; explicit release assertions in the streaming suites are the primary guarantee |
| 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 |