Files
clean-architecture-backend-…/docs/httpclient/repository-adaptation.md
T
DongHyeonka 630f9b860a docs(records): 설계서와 기록 문서를 docs/design·docs/history로 옮긴다
문제: 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.
2026-11-07 12:15:45 +09:00

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 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.