문제: 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.
7.4 KiB
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
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.