설계: 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>
86 lines
7.4 KiB
Markdown
86 lines
7.4 KiB
Markdown
# 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 `HttpFailureMetadata` redaction 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.
|