review-followup Wave 3 라운드 2(P18): outbox canonical 통일, composition 모듈, legacy Kafka seam 삭제

- 결정 7: `LegacyOutboxAppendPort`·legacy 저장 모델·relay·Kafka R0 seam 삭제, 템플릿 JSON encoder(`JsonIntegrationEventEncoder`),
  durable operation·sample 이벤트가 `OutboxAppendPort` + encoder로, persistence-jpa V19(pre-canonical 미발행 row 거부)
- 결정 3: outbox relay·멱등성 executor 조립을 `composition:outbox-relay`·`composition:idempotency`로,
  sample이 복사한 bootstrap 인프라를 `composition:service-runtime`으로(sample `SampleIdempotencyConfig` 복사본 삭제)
- persistence-jpa outbox·멱등성 패키지 feature 기준 이동, messaging outbox·inbox leaf를 reliability / reliability-jdbc-postgresql로
- messaging outbox header를 jsonb로(P18-new-1 — `\`로 끝나는 값이 다음 header를 삼키던 결함)
- 통합(충돌 22건): P25 A-10c(전략 선택 설정 삭제)를 service-runtime `DomainContextConfig`에 적용, P25 startup 예외 통합을
  composition 설정 테스트에, P25 `CommandUseCase.handle` 이름을 PG 통합 테스트에, P15 `EventJson`은 호출자 0이 되어 삭제
- root CLAUDE.md의 legacy seam 문장 수정(P18-new-2)

검증: ./gradlew check architectureCheck verifyDependencyLocks verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys
configContractCheck :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest
persistence-jpa jpaPlatformContractTest·postgresql{Idempotency,OutboxAppendTransactional,OutboxConcurrentRelay,OutboxRowLifecycle}IntegrationTest
:messaging:messaging-reliability-jdbc-postgresql:integrationTest --continue 통과(700 task)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
donghyeon-ka
2026-09-29 12:30:01 +09:00
co-authored by Claude Opus 5.5
parent 25de288ab4
commit 423a29c46f
329 changed files with 6380 additions and 6850 deletions
+93
View File
@@ -0,0 +1,93 @@
# 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`가 `ca-skeleton.capabilities.idempotency.provider`에 따라 하나를
기여한다. 선택한 provider의 저장소가 정확히 하나가 아니면(0개: 모듈이 없거나 꺼짐, 2개: 다른
곳이 하나 더 등록) 기동이 개수와 함께 실패한다.
- 켜기와 끄기: 모듈이 있어도 `provider=disabled`(기본)면 아무것도 바인딩하거나 만들지 않는다.
- 설정 바인딩은 `StrictSettingsBinder`다. 같은 prefix 아래 Redis 저장소가 자기 키(`key-version`,
`command-timeout`)를 두므로 그 두 키만 빼고 엄격하게 본다. 수명 정책 키를 잘못 쓰면 기본값이
조용히 쓰이는 대신 기동이 실패한다.
- app-bootstrap과 sample-portfolio가 같은 한 줄을 쓴다. 예전의 sample 복사본
(`SampleIdempotencyConfig`, 상한 검증 없이 `Binder`로 읽고 저장소를 하나로 가정)은 삭제했다.
## 추가할 한 줄
```groovy
// app-bootstrap/build.gradle (sample-portfolio/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), `APP_IDEMPOTENCY_FAILURE_RETENTION`(≤30d) |
## 설계 결정 참조 (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
- `ca-skeleton.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 |
| `failure-retention` | `APP_IDEMPOTENCY_FAILURE_RETENTION` | 24h | 30d |
| `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`가 읽는다.
- **상한 검사는 컴팩트 생성자에서 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` 일 때만 돈다.