Files
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00

6.0 KiB

Web 플랫폼 runbook

HTTP 경계가 이상할 때 운영자에게 필요한 것이다. 어느 모듈이 가졌는지가 아니라 무엇을 보았는지로 나눴다. 새벽 3시에 손에 있는 것이 그것이기 때문이다.

429 읽기

RateLimitInterceptor는 edge 속도 제한이 호출자를 거부하면 Retry-After와 함께 429 RATE_LIMIT_EXCEEDED로 답한다. RATE_LIMIT_UNAVAILABLE은 호출자가 무언가를 넘었다는 뜻이 아니라 속도 제한 저장소에 닿지 못했다는 뜻이다. 호출자가 아니라 저장소를 본다.

Envelope가 아닌 오류

애플리케이션이 쓰는 모든 HTTP 오류는 GlobalExceptionHandler가 쓰는 Envelope이고 (spring.mvc.problemdetails.enabled=false), client가 분기하는 error.code를 가진다.

  • 빨리 확인하는 법: 검증에 실패해야 하는 요청을 보내고 본문에 error.code가 있는지 본다. 없으면(Spring의 ProblemDetail이나 container의 오류 쪽) handler가 설치되지 않았거나 응답이 edge에서 왔다.

응답이 잘리거나 문서 중간에 connection이 끊긴다

원인은 둘이고, client가 받은 상태로 구분한다.

  • client가 상태를 받고 그다음 아무것도 없다 — 응답이 commit 뒤에 실패했다. 상태는 되돌릴 수 없으므로 문서 중간에 connection이 끝난다.
  • client가 애플리케이션에서 아무것도 받지 못했다 — proxy가 거부했다. nginx의 client_max_body_size는 Envelope가 아니라 자기 HTML로 답한다. repository-adaptation.md §8을 본다.

재시도한 쓰기가 두 번 일어났다

통제 수단은 멱등 key이고, 그것이 적용되지 않는 길은 정확히 셋이다.

  1. client가 key를 보내지 않았다. endpoint가 key를 요구하지 않으니 보호 없이 돌았다. 중복을 받아들일 수 없으면 key를 요구한다.
  2. client가 다른 본문을 보냈다. 422 IDEMPOTENT_REQUEST_MISMATCH로 답하고 절대 다시 보내지 않는다. 다시 보내면 호출자가 한 적 없는 요청의 영수증을 돌려주게 된다.
  3. 기록이 만료됐다. TTL은 연산마다 정하고 상한은 72h다. 만료 뒤의 재시도는 정의상 새 요청이다.

409 IDEMPOTENT_IN_FLIGHT(retryable=true, Retry-After: 2)는 실패가 아니다. 앞 시도가 아직 돌고 있고 그 결과를 모른다. 호출자는 Retry-After 뒤에 같은 Idempotency-Key로 다시 보낸다. 새 key는 새 요청이고, 쓰기가 두 번 적용되는 길이 그것이다. 멱등성 답 넷은 http-contract.md §2에 있다.

rolling 배포가 인스턴스를 반쯤 비운 채 멈춘다

shutDownGracefully는 진행 중인 일을 기다리고, 열려 있지만 노는 keep-alive connection이 진행 중으로 셀 수 있다. 그 기다림 중에 stop()을 부르면 멈춘다.

  • 증상: 요청을 받지도 않고 끝나지도 않는 인스턴스. 로그에 오류가 없다.
  • 원인: 상한 없는 graceful 기다림. GracefulShutdownProbe는 정한 유예 시간으로 그것을 제한하고, 시간이 지나면 어쨌든 서버를 멈춘다. 배포도 같게 해야 한다.
  • 설정: spring.lifecycle.timeout-per-shutdown-phase. 상한이 없으면 배포는 영영 놀지 않을 수도 있는 connection을 기다린다.

metric이 오지 않거나 청구액이 뛰었다

거의 늘 가짓수가 많은 tag다. 흔히 풀린 경로를 담은 routeTemplate이고, 자원마다 시계열 하나가 된다.

  • 확인: metric 저장소에서 routeTemplate의 tag 값을 본다. 중괄호가 있으면 template이고, 식별자가 있으면 풀린 경로가 새어 나갔다.
  • 절대 tag로 쓰지 않는 것: URL, query string, 식별자, tenant, key, token, cookie, 본문. tag 값은 가려지지 않은 채 metric 저장소에 닿고, 보통 그와 함께 외부 SaaS에도 닿는다.

브라우저에서만 cross-origin 요청이 실패한다

API는 맞게 답하는데 브라우저가 응답을 거부한다. CORS는 SecurityConfig가 적용하는 CorsSettings(app.cors.*)다. 시작 단계는 두 설정을 거부한다.

  • origin 없이 APP_SECURITY_CORS_ENABLED=true.
  • APP_SECURITY_CORS_ALLOW_CREDENTIALS=true와 함께 APP_SECURITY_CORS_ORIGINS의 * — 어떤 브라우저도 받아들이지 않는다.

다음 둘은 시작은 되지만 브라우저에서 여전히 실패한다.

  • origin 목록의 https://*.example.com — 글자 그대로 비교하므로 아무것에도 맞지 않는다.
  • 경로가 있는 origin(https://app.example.com/ui) — origin은 scheme, host, port뿐이다.

응답은 오는데 브라우저 코드에서 헤더가 null로 읽힌다(Retry-After, X-Request-Id, Location, tus Upload-Offset): 그 헤더가 Access-Control-Expose-Headers에 없다. 노출 목록은 CorsExposedHeaders.PLATFORM과 모듈마다의 CorsExposedHeaders bean이다(docs/web/http-contract.md §3). 서비스가 더한 헤더에는 자기 bean이 필요하다. Access-Control-Expose-Headers를 지우거나 고쳐 쓰는 proxy도 같은 증상을 낸다.

preflight가 401로 답하면 CORS가 인증 뒤에 돈 것이다. preflight는 설계상 credential을 싣지 않는다. 순서는 WebPipelineOrderContract가 단언한다.

요청 하나에 접근 로그 줄이 둘

async 요청은 servlet filter chain을 두 번 지난다. 처음 요청 때 한 번, ASYNC 재전달 때 또 한 번이다. isAsyncStarted()를 확인하지 않고 기록한 완료는 두 번 쓰이고, 그 데이터로 계산한 모든 지연 백분위수는 그럴듯해 보이면서 틀린다. WebPipelineOrderContract가 모든 container에서 논리 요청마다 관측이 정확히 하나임을 단언한다.

확인 명령

./gradlew :adapter:inbound:web:test                          # 단위, 경계, 아키텍처
./gradlew :adapter:inbound:web:systemTest                    # Tomcat, 실제 socket
./gradlew :adapter:inbound:web:webJettyCompatTest            # 두 번째 servlet container