문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.
고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
→ docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.
옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.
위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.
검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
86 lines
7.4 KiB
Markdown
86 lines
7.4 KiB
Markdown
# HTTP Client Platform — Repository Adaptation Contract
|
|
|
|
**Design source:** `docs/design/2026-08-08-httpclient-platform-design.md`
|
|
**Plan source:** `docs/history/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` | removed (decision 9, 2026-09-25: blocking only) |
|
|
| `httpclient-webclient` | `…httpclient.webclient` | removed (decision 9, 2026-09-25: blocking only) |
|
|
| `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.
|