Files
clean-architecture-backend-…/src/bootstrap/idempotency/README.md
T
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

105 lines
7.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# composition:idempotency — 요청 멱등성 executor 조립
- Module ID: `composition-idempotency`
- Gradle path: `:composition:idempotency`
- Package: `dev.caskeleton.composition.idempotency`
- 테스트: `./gradlew :composition:idempotency:test --console=plain`
## 제공하는 것
선택한 provider의 저장소 위에 `IdempotencyExecutor`를 하나 만든다. KEYED use case는
application-core의 `IdempotencyExecutor`만 받는다.
```
composition:idempotency
├─ IdempotencyAutoConfiguration provider != disabled 일 때만: 설정 바인딩 + executor 하나
├─ IdempotencySettings 수명 정책(lease·replay TTL·retention·codec·revision), strict 바인딩
└─ config/module-defaults/idempotency.yml (설정 기본값, support 로더가 읽음)
```
- 저장소는 포트(`IdempotencyStorePort`)다. Redis는 `adapter:outbound:cache-redis`, PostgreSQL은
`adapter:outbound:persistence-jpa`가 `app.capabilities.idempotency.provider`에 따라 하나를
기여한다. 선택한 provider의 저장소가 정확히 하나가 아니면(0개: 모듈이 없거나 꺼짐, 2개: 다른
곳이 하나 더 등록) 기동이 개수와 함께 실패한다.
- 켜기와 끄기: 모듈이 있어도 `provider=disabled`(기본)면 아무것도 바인딩하거나 만들지 않는다.
- 설정 바인딩은 `StrictSettingsBinder`다. 같은 prefix 아래 Redis 저장소가 자기 키(`key-version`,
`command-timeout`)를 두므로 그 두 키만 빼고 엄격하게 본다. 수명 정책 키를 잘못 쓰면 기본값이
조용히 쓰이는 대신 기동이 실패한다.
- app-bootstrap이 이 한 줄을 쓴다. 예전의 샘플 모듈 복사본
(`SampleIdempotencyConfig`, 상한 검증 없이 `Binder`로 읽고 저장소를 하나로 가정)은 삭제했다.
## 추가할 한 줄
```groovy
// src/bootstrap/app/build.gradle
runtimeOnly project(':composition:idempotency') // 요청 멱등성 executor
```
기본 조립에 있다. provider가 `disabled`면 꺼져 있으므로 저장소 모듈 없이도 안전하다. 이 줄을 지우면
executor, 설정 기본값이 함께 빠진다(그때 KEYED use case는 executor를 받지 못해 기동이 실패한다).
## 필요한 env 키
전체 목록과 타입은 `docs/registries/env-keys.yaml`의 `APP_IDEMPOTENCY_*` 행이 SSOT다.
| 언제 | 키 |
| --- | --- |
| 켤 때 | `APP_IDEMPOTENCY_PROVIDER` (`redis` 또는 `postgresql`), 그리고 그 provider 모듈의 줄과 env |
| 조정할 때 | `APP_IDEMPOTENCY_PROCESSING_LEASE`(≤1h), `APP_IDEMPOTENCY_TTL`(≤72h, processing lease 이상, `APP_IDEMPOTENCY_FAILURE_RETENTION` 이하 — 24h보다 올리면 failure retention도 함께 올린다), `APP_IDEMPOTENCY_FAILURE_RETENTION`(≤30d, `APP_IDEMPOTENCY_TTL` 이상) |
## 설계 결정 참조 (app-bootstrap에서 옮김)
이 모듈의 코드는 2026-09-28에 app-bootstrap `autoconfigure/idempotency`에서 옮겨 왔다(소유자 결정 3). 아래 근거는 그때의 기록이다.
### IdempotencyAutoConfiguration
- **`IdempotencyExecutor`를 여기서 한 번만 만든다.** provider 모듈은 `IdempotencyStorePort`만
내놓는다 — `redis`는 `cache-redis`의 `RedisIdempotencyConfig`, `postgresql`은 `persistence-jpa`의
`PostgreSqlIdempotencyStoreConfig`. lease·replay TTL·retention·codec id·policy revision 은 어느
store 든 같은 정책이라 `IdempotencySettings` 하나에서 읽는다. executor 를 application-core 밖에서
만드는 이유는 이 설정을 `application-core`가 직접 읽으면 안 되기 때문이다.
- **store 가 정확히 하나가 아니면 기동을 거부한다.** 0개는 provider 모듈이 runtime classpath 에
없거나 스위치가 꺼진 경우, 2개는 다른 무언가가 store 를 등록한 경우다. 둘 다 빈 누락 오류나 엉뚱한
store 로 요청을 처리하는 대신 개수를 담은 startup 실패로 드러난다.
- `provider=disabled`(기본)면 executor 빈 자체가 없다. `jdbc` 값과 V1 조립(`IdempotencyConfig`,
`config/idempotency.yml`)은 삭제됐다.
- `postgresql` provider 는 PostgreSQL data source 가 아니면 기동을 거부한다. `bootRunH2` 에서는
`disabled` 나 `redis` 를 쓴다.
### IdempotencySettings
- `app.capabilities.idempotency` 에 바인딩되는 유일한 설정 record 다(값은
`config/module-defaults/idempotency.yml`).
| 키 | env | 기본값 | 상한 |
| --- | --- | --- | --- |
| `provider` | `APP_IDEMPOTENCY_PROVIDER` | `disabled` | `disabled` \| `redis` \| `postgresql` |
| `processing-lease` | `APP_IDEMPOTENCY_PROCESSING_LEASE` | 30s | 1h |
| `replay-ttl` | `APP_IDEMPOTENCY_TTL` | 24h | 72h, 그리고 `processing-lease` 이상·`failure-retention` 이하 |
| `failure-retention` | `APP_IDEMPOTENCY_FAILURE_RETENTION` | 24h | 30d, 그리고 `replay-ttl` 이상 |
| `response-codec-id` | — | `json-v2` | 1–64자 |
| `policy-revision` | — | 2 | 양수 |
| `reaper-interval` | — | 10m | 양수 |
Redis store 튜닝값 `key-version`, `command-timeout`(`APP_IDEMPOTENCY_REDIS_COMMAND_TIMEOUT`)도
같은 prefix 아래 있지만 lifecycle 정책이 아니라서 이 record 에 두지 않고 `cache-redis`가 읽는다.
- **`replay-ttl` 이 `processing-lease` 보다 짧으면 기동을 거부한다.** 같은 키로 다시 보내라는 답을 받은
클라이언트는 lease 안 어느 때든 돌아올 수 있다. 재생 창이 그보다 먼저 닫히면 그 재전송은 작업을 한 번
더 돌린다(재리뷰 2026-11-04 RR-03-11). 두 store 는 이 관계와 상관없이 기록을 lease + replay TTL 동안
둔다 — 이 검사는 store 를 지키는 것이 아니라 재생을 무력하게 만드는 정책을 막는다.
`IdempotencyClaimRequest` 에는 두지 않았다: 포트는 어떤 값 쌍으로도 쓸 수 있고, store 가 모든 쌍에서
안전한지는 공유 계약이 본다.
- **`failure-retention` 이 `replay-ttl` 보다 짧으면 기동을 거부한다.** 실패로 표시된 기록(포기·재시도
가능)은 표시부터 이 기간만 남는다. `replay-ttl` 보다 짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은
키 재전송이 작업을 다시 돌린다. 메시지는 두 키와 값을 함께 보여 준다. 기본값(둘 다 24h)은 그대로 뜬다.
재리뷰 RR3-03-02 때는 지금 기동하는 설정을 깨지 않으려고 문서로만 두었고, 2026-11-04 소유자 결정으로
검사를 넣었다.
- **상한 검사는 컴팩트 생성자에서 fail-fast 로 던진다.** `Duration`의 상한은 JSR-303(`@Valid`)
애너테이션으로 표현할 수 없어 생성자에서 직접 검증한다. 검증을 느슨하게 두면 과도하게 긴 TTL 이
저장소를 조용히 부풀리고 멱등성 키 추측 공격의 유효 시간 창을 넓히기 때문에, 부팅 시점에 즉시
실패시키는 쪽을 택했다.
- **replay TTL 상한(72h) / 기본값(24h)을 바꿀 때는 보안 베이스라인의 JWT 키 회전 겹침(overlap)
윈도와 반드시 함께 검토해야 한다.** 멱등성 레코드의 수명이 키 회전 겹침 윈도(현재 24h)보다 길면,
가명화(pseudonym) 기준이 회전된 principal 에 대해 레코드가 재생(replay)될 수 있다. 이 불변식을
강제하는 CI 게이트는 security-operational-baseline 쪽에 위임돼 있다.
- **`reaper-interval`은 전용 환경변수가 없다.** reaper 실행 주기는 비밀이나 배포별 값이 아니라 순수
운영 튜닝 값이다. reaper 는 provider 가 `postgresql` 일 때만 돈다.