문제: 앞 커밋이 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
114 lines
9.7 KiB
Markdown
114 lines
9.7 KiB
Markdown
# 05. 멱등성·결과 불명 처리
|
|
|
|
## 핵심
|
|
|
|
쓰기 요청의 결과는 세 가지다: 됐다, 안 됐다, **모른다**. "모른다"를 "안 됐다(다시 해도 됨)"로 적으면
|
|
같은 작업이 두 번 적용된다. 그래서 결과를 증명할 수 없을 때는 항상 "모른다"로 답하고, 클라이언트가
|
|
안전하게 다시 물을 방법(같은 멱등성 키)을 준다.
|
|
|
|
```text
|
|
클라이언트 ── POST + Idempotency-Key ──▶ 컨트롤러 ──▶ KEYED 유스케이스
|
|
│ IdempotencyExecutor
|
|
├─ 처음 본 키 → 실행 → 결과 저장 → 응답
|
|
├─ 끝난 키 → 저장된 결과 재생
|
|
├─ 실행 중 키 → 409 IDEMPOTENT_IN_FLIGHT (retryable, Retry-After 2)
|
|
└─ 다른 본문 → 422 IDEMPOTENT_REQUEST_MISMATCH
|
|
DB 커밋 중 연결 끊김 ─────────────────────────────────────▶ 500 DB_COMPLETION_UNKNOWN (retryable=false)
|
|
```
|
|
|
|
정본: `docs/web/http-contract.md` 2절(wire 응답), `src/application/core/README.md` 「멱등성 (KEYED) — feature-rate-limit-idempotency-contract」
|
|
(executor 구조), `docs/adr/ADR-JPA-003-completion-unknown.md`(커밋 결과 불명).
|
|
|
|
## 판단: 이 쓰기를 KEYED로 만드나
|
|
|
|
- **고르는 기준**: 클라이언트가 응답을 못 받았을 때 다시 보내는가, 그리고 두 번 적용되면 피해가 있는가.
|
|
- **기본값**: 생성·결제·주문·발송처럼 "두 번 = 피해"인 쓰기는 `KEYED`. 같은 입력이면 같은 결과인
|
|
쓰기(상태를 X로 설정)는 `IDEMPOTENT`. 그 밖은 `NOT_IDEMPOTENT`(생성 명령의 기본값 — 바꿀지 여기서
|
|
정한다).
|
|
- **예외**: 자연 키가 있어 DB 유일성 제약이 중복을 막으면(04장) 키 없이도 두 번째 요청이 409로 끝난다.
|
|
다만 그 409는 "이미 있음"이지 "첫 요청의 결과"가 아니다. 클라이언트가 첫 결과를 받아야 하면 KEYED.
|
|
|
|
### KEYED로 만드는 순서
|
|
|
|
1. `@UseCaseCapability(idempotency = Idempotency.KEYED)`.
|
|
2. 유스케이스 본문을 `IdempotencyExecutor`로 감싼다. executor를 유스케이스가 만들지 않는다 —
|
|
`composition:idempotency`가 한 번 만든다.
|
|
3. scope digest(주체 + 키 + operation 코드의 HMAC)와 요청 fingerprint(SHA-256)를 유스케이스 밖(전송)에서
|
|
만든다. 원본 키는 저장소에 닿지 않는다.
|
|
4. 작업 결과를 `IdempotentAction.Outcome`(`Success` / `RetryableNoEffect` / `EffectUnknown`)으로 돌려준다.
|
|
예외를 던지면 effect-unknown으로 센다.
|
|
5. 저장소 provider를 고른다: `app.capabilities.idempotency.provider` = `postgresql` 또는 `redis`
|
|
(기본 `disabled`). 운영에서 in-memory 금지.
|
|
|
|
예: 키 헤더 검증은 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/http/IdempotencyKeyHeader.java`,
|
|
executor 조립과 실제 PostgreSQL 저장소 왕복은 `PostgreSqlIdempotencyProviderIntegrationTest`(app-bootstrap
|
|
`integrationTest`)다. KEYED 유스케이스를 HTTP부터 끝까지 이은 업무 기능 예는 템플릿에 없다.
|
|
|
|
## 클라이언트에게 무엇을 약속하나
|
|
|
|
| 응답 | 의미 | 클라이언트 행동 |
|
|
| --- | --- | --- |
|
|
| 409 `IDEMPOTENT_IN_FLIGHT`, `retryable=true`, `Retry-After: 2` | 같은 키가 아직 실행 중. 결과 불명 | **같은 키로** 기다렸다 재전송. 새 키 금지 |
|
|
| 422 `IDEMPOTENT_REQUEST_MISMATCH` | 같은 키에 다른 본문 | 클라이언트 버그. 재전송 안 함 |
|
|
| 503 `IDEMPOTENCY_UNAVAILABLE` | 실행 전 거부(저장소 응답 없음, 또는 claim의 lease가 시작 전에 끝남) | 같은 키로 나중에 |
|
|
| 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, `retryable=true` | 실행 뒤 결과 기록 실패. 적용됐을 수 있음 | "적용 안 됨"이라 하지 않는다. **같은 키로** 나중에 재전송, 새 키 금지 |
|
|
| 500 `IDEMPOTENCY_RECOVERY_REQUIRED` | 이전 시도 효과를 증명 못함 | 자동 재시도 안 함. 같은 키 재전송은 안전(재생·실행·다시 500을 서버가 판정, 다시 돌리지 않음). 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차에 따라 새 키 |
|
|
| 500 `DB_COMPLETION_UNKNOWN`, `retryable=false` | DB 커밋 중 연결 끊김. 커밋됐을 수도 있음 | 키 없이 재시도 금지. KEYED면 같은 키로 재전송하면 서버가 판정 |
|
|
|
|
같은 키 재전송이 무엇을 막는지는 저장소마다 다르다(정본
|
|
`docs/web/http-contract.md` 2절). Redis 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을 다시 돌리지
|
|
않는다. PostgreSQL 저장소를 템플릿처럼 쓰기 트랜잭션 하나로 쓰면 실패한 요청의 기록은 롤백되어 다음 같은 키
|
|
요청이 다시 실행한다. 그래서 트랜잭션 밖 효과는 따로 멱등하게 만든다. 첫 시도가 processing lease(기본 30s)보다
|
|
오래 걸릴 때 보이는 모습도 저장소마다 다르다.
|
|
|
|
- **Redis**: 첫 시도가 실행을 시작한 뒤 lease가 지나면 그 기록을 넘겨주지 않고 500
|
|
`IDEMPOTENCY_RECOVERY_REQUIRED`로 답한다. 넘겨받는 것은 실행 전 claim과 재시도 가능한 실패뿐이다. 이 답은
|
|
기록을 바꾸지 않는다. executor는 lease를 늘리지 않아 30s를 넘는 정상 요청도 lease가 지나는데, 그 첫
|
|
시도가 나중에 끝나면 결과가 기록되고 첫 요청은 정상 응답을 받으며 그 뒤 같은 키 요청은 그 결과를
|
|
재생한다(2026-11-04 소유자 결정).
|
|
- **PostgreSQL**: executor를 유스케이스의 쓰기 트랜잭션 하나 안에서 부르면(템플릿의 모양) claim 기록은 그
|
|
트랜잭션과 함께 커밋되거나 롤백된다. 같은 키 요청은 409·500 대신 첫 요청이 끝날 때까지 기다렸다가
|
|
재생(커밋)이나 새 실행(롤백)을 받는다. 작업이 예외로 끝나면 실패 기록도 함께 롤백되어 다음 같은 키
|
|
요청이 다시 실행한다. 쓰기 트랜잭션 제한(기본 30s)을 넘긴 요청도 기록과 함께 롤백된다
|
|
(`DB_QUERY_CANCELED`). 그래서 이 저장소가 막는 중복은 같은 트랜잭션 안의 DB 효과다. 트랜잭션 밖 효과는
|
|
다음 요청에서 다시 일어날 수 있다.
|
|
|
|
claim의 lease가 작업 시작 전에 끝나면 두 저장소 모두 시작을 거절하고(`LEASE_EXPIRED`), executor는 작업을
|
|
돌리지 않은 채 503 `IDEMPOTENCY_UNAVAILABLE`로 답한다. 다음 같은 키 요청이 그 claim을 넘겨받아 실행한다.
|
|
`IdempotencyClaimAttempt`를 재시도 사이에 들고 있다가 같은 attempt로 다시 부르는 호출자도 넘겨받는다(2026-11-05
|
|
확인 리뷰가 찾아 고쳤다. 전에는 같은 claim을 재생받아 시작을 다시 거절당해 기록이 사라질 때까지 503이었다).
|
|
같은 attempt를 두 호출이 동시에 쓰면 서버가 가려내지 못하므로, 재시도는 앞 호출이 돌아온 뒤에 한다.
|
|
기록은 lease + `replay-ttl` 동안 남고, `replay-ttl`이 lease보다 짧으면 기동이 실패한다
|
|
(`IdempotencyStoreContract`). 작업이 실패로 끝나 executor가 포기나
|
|
재시도 가능으로 표시한 기록은 표시한 때부터 `failure-retention`(기본 24h) 동안 남는다(PostgreSQL을 트랜잭션
|
|
하나로 쓰면 위처럼 롤백과 함께 사라진다). `failure-retention`이 `replay-ttl`보다 짧으면 기동이 실패한다.
|
|
짧으면 효과 불명으로 포기한 기록이 먼저 사라져 같은 키 재전송이 작업을 다시 돌리기 때문이다(2026-11-04
|
|
소유자 결정). 거꾸로 말하면 `replay-ttl`(`APP_IDEMPOTENCY_TTL`)은 lease 이상, `failure-retention`
|
|
이하로 둔다.
|
|
|
|
409를 `retryable=true`로 바꾼 이유(2026-11-01 소유자 결정): 같은 키 재전송은 서버가 안전하게 판정하므로 다시
|
|
보내는 것이 맞고, 새 키로 보내면 서버가 막지 못한다. 짝 프론트 분류기도 이 표를 따른다.
|
|
|
|
## 결과 불명을 만드는 곳마다 같은 규칙
|
|
|
|
2026-11-01 성숙도 리뷰가 찾은 반복 원인 첫째가 "결과 불명을 확실함으로 기록"이었다. 알림 발송·DB
|
|
커밋·메시지 relay 세 경계에서 같은 실수가 나왔다. 새 경계를 만들 때 아래 질문에 답한다.
|
|
|
|
- **고르는 기준**: 실패한 호출이 **상대편에서 이미 효과를 냈을 수 있는가**.
|
|
- **기본값**: 그럴 수 있으면 "결과 불명"으로 분류한다. 재시도 가능(`retryable=true`)으로 분류하지
|
|
않는다. 근거 코드:
|
|
- DB 커밋 중 끊김 → `DB_COMPLETION_UNKNOWN`
|
|
(`src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java`)
|
|
- 메시지 발행 응답 없음 → `OutboxPublishAmbiguousException`(application-core `outbox`)
|
|
- 알림 발송 시작 뒤 crash → 재발송하지 않고 reconcile(application-notification evidence 모델)
|
|
- **예외**: 요청이 상대에게 **도달하기 전**에 실패한 것이 증명되면(연결 수립 실패, 실행 전 거부)
|
|
재시도 가능이다. 반대 방향 실수(확실히 안 간 것을 불명으로)도 결함이다(2026-11-01 성숙도 리뷰가
|
|
Redis 연결 수립 실패에서 찾았다).
|
|
- 불명 상태를 푸는 방법(reconcile, 키 재전송, 운영자 확인)을 runbook에 적는다(`docs/runbooks/`).
|
|
|
|
## 지금 이해하면 되는 것
|
|
|
|
- "두 번 = 피해"인 쓰기는 KEYED. executor는 composition이 만든다.
|
|
- 409 in-flight는 같은 키로 다시, 422는 버그, 500 completion-unknown은 키 없이 재시도 금지.
|
|
- 상대편에 효과가 났을 수 있으면 "모른다"로 분류한다.
|