설계: 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>
7.4 KiB
HTTP Client Platform — Repository Adaptation Contract
Design source: docs/superpowers/specs/2026-08-08-httpclient-platform-design.md
Plan source: docs/superpowers/plans/2026-08-08-httpclient-platform-implementation-plan.md
The design package states its own adaptation rule:
실제 Backend Skeleton 저장소가 제공되지 않았으므로 package 경로와 Gradle 구조는 설계서의 명시적 구현 가정이다. 구현 전 저장소의 기존 convention과 root package에 맞춰 경로만 조정하고 공개 계약과 정책 의미론은 유지한다.
This file is the single record of how the design's assumed layout was mapped onto this repository. Only paths, build DSL, and composition-root ownership changed. Public contracts, policy order, and error semantics are implemented exactly as specified.
1. Why the module layout differs
The design assumes a greenfield library with 19 Gradle projects under modules/httpclient/.
This repository is a Clean Architecture template whose fail-closed registry
(src/config/architecture/modules.json, enforced by src/settings.gradle and
verifyCleanArchitectureDependencies) declares exactly 19 leaf identities. Creating 19 more
Gradle projects would violate HARD-STOP #5 in AGENTS.md.
Therefore the design's 19 library modules become package boundaries inside the registered leaf
:adapter:outbound:httpclient, with two exceptions driven by this repository's own rules:
| Design module | Repository home | Reason |
|---|---|---|
httpclient-spring-boot-starter |
:adapter:outbound:httpclient (dev.caskeleton.adapter.outbound.httpclient.autoconfigure) |
Capability-specific Spring composition is owned with the reusable HTTP client platform; app-bootstrap only selects/includes the capability and runtime activation remains app.httpclient.enabled. |
httpclient-testkit |
:adapter:outbound:httpclient src/testFixtures/java/**/testkit |
The design forbids production modules depending on the testkit. Gradle testFixtures publishes the reusable test support only to test consumers; ordinary tests, integration/performance lanes, and JMH opt into that surface explicitly without exposing it to production. PlatformClasses excludes test-fixture output so the boundary rules keep meaning production classes. |
The package boundary is enforced by ArchUnit rules (PublicApiArchitectureTest,
HttpClientModuleBoundaryTest) that reproduce the design's module dependency table.
2. Package mapping
Root package: io.backend.skeleton.httpclient → dev.caskeleton.adapter.outbound.httpclient.
| Design module | Design package | Repository package |
|---|---|---|
httpclient-core-api |
…httpclient.api (+ .body, .error, .operation, .result) |
dev.caskeleton.adapter.outbound.httpclient.api (+ same subpackages) |
httpclient-profile |
…httpclient.profile |
…outbound.httpclient.profile |
httpclient-transport-spi |
…httpclient.transport |
…outbound.httpclient.transport |
httpclient-transport-apache |
…httpclient.apache |
…outbound.httpclient.apache |
httpclient-transport-jdk |
…httpclient.jdk |
…outbound.httpclient.jdk |
httpclient-restclient |
…httpclient.restclient |
…outbound.httpclient.restclient |
httpclient-resilience |
…httpclient.resilience |
…outbound.httpclient.resilience |
httpclient-auth |
…httpclient.auth |
…outbound.httpclient.auth |
httpclient-security |
…httpclient.security |
…outbound.httpclient.security |
httpclient-observability |
…httpclient.observation |
…outbound.httpclient.observation |
httpclient-transport-reactor-netty |
…httpclient.reactor |
…outbound.httpclient.reactor |
httpclient-webclient |
…httpclient.webclient |
…outbound.httpclient.webclient |
httpclient-service-client |
…httpclient.service |
…outbound.httpclient.service |
httpclient-dynamic-target |
…httpclient.dynamic |
…outbound.httpclient.dynamic |
httpclient-jetty-http3-experimental |
…httpclient.http3 |
…outbound.httpclient.http3 |
httpclient-spring-boot-starter |
…httpclient.autoconfigure |
dev.caskeleton.adapter.outbound.httpclient.autoconfigure |
httpclient-testkit |
…httpclient.testkit |
…outbound.httpclient.testkit (testkit source set) |
3. Other deliberate substitutions
| Design assumption | Repository reality | Adaptation |
|---|---|---|
Gradle Kotlin DSL, build-logic convention plugin |
Groovy DSL, root build.gradle conventions, LockMode.STRICT dependency locking |
Dependencies declared in src/adapter/outbound/httpclient/build.gradle; gradle.lockfile regenerated. |
| Spring Framework 6.2 baseline with 7.0 compatibility | Spring Boot 4.0.8 / Spring Framework 7.0 is the repository baseline | Common code targets the Spring 6.2 API surface (no 6.2-only or 7.0-only classes in common packages). The Spring 7 HTTP Service Group integration and the RestTemplate migration package were removed. |
settings.gradle.kts module registration |
Fail-closed registry | No registry change; leaf identity, gradle path, allowed dependencies unchanged. |
| Design §6.2 grades Apache HttpClient 5 as HTTP/2-capable | Spring's blocking factory drives Apache's classic client, which is HTTP/1.1 only; HTTP/2 lives in Apache's async client | ApacheBlockingTransportProvider declares HTTP/1.1 and rejects an HTTP/2 profile at startup. Blocking HTTP/2 is served by the JDK transport, measured by NegotiatedProtocolContractTest. |
| Design §28.1 names WireMock for stateful fixtures | WireMock's Jetty modules bind a different Jetty 12 ABI than the Boot-managed one this module already needs for HTTP/3, and fail at server start | StatefulUpstream provides path-keyed stateful responses on the existing fixture server; the WireMock dependency was removed rather than worked around with a shaded jar |
Per-task git commit |
AGENTS.md: commit policy is human-only |
Implementation is delivered unstaged; commits are the human's action. This is the only plan step intentionally not executed, and it is recorded here. |
docs/httpclient/**, .github/workflows/httpclient-*.yml, scripts/verify-httpclient-docs.py |
Repository already owns docs/ and .github/workflows/ |
Created at the same repository-relative paths. |
4. What is unchanged from the design
- H1 / H2 / H3 / H4 exposure rules and the forbidden native-engine signatures.
ExecutionEvidence,BodyReplayability,OperationIdempotency,AttemptStage,FailureCategory.HttpOperation,HttpCallResult,BodySource,ResponseType,BlockingStreamingResponse.- The complete stable exception hierarchy and
HttpFailureMetadataredaction rules. - Named Client Profile schema, startup validation codes, and operation override direction.
- Effective deadline formula, attempt budget, and streaming setup/idle split.
- Retry eligibility inputs, the ordered decision table, retry budget, and backoff rules.
- Circuit → Rate Limiter → Bulkhead attempt order and logical admission placement.
- OAuth2 cache key, single-flight refresh, and the 401 replay-at-most-once rule.
- TLS allow/forbid lists and permanent-failure classification.
- Dynamic Target canonicalization → all-answer DNS validation → pinning → redirect revalidation.
- Low-cardinality tag allowlist, forbidden labels, trace and logging rules.
- Runtime generation swap and drain semantics.