durable operation은 core 공통 타입을 따르지 않는다. tenant·principal이 문자열이고 operation id는 controller가 만들며, UUIDv7 파생은 유스케이스가 한다. operation id 문법이 셋인데 이유가 없고, 멱등 판정 셋 중 둘이 executor를 쓰지 않는 이유도 없다. 쓰는 곳 없는 공개 타입이 일곱이고, final 유스케이스가 둘이며, 포트 둘은 실패 결과를 적지 않았고, 소스 문자열에 NUL 바이트가 있다. 고른 방법: OperationCommand·query·command가 Optional<TenantId>를 받고 SubmitDurableOperationUseCase가 DurableOperationIdFactory로 id를 만든다. UUIDv7 파생은 IntegrationIdentity로 옮긴다. id 문법 셋은 다니는 곳(URL 경로, header·Redis key, 비교만)이 달라 합치지 않고 OperationId Javadoc에 비교를 적는다. executor를 쓰지 않는 중복 판정 둘은 manual 05에 결정으로 적는다. 안 쓰는 타입은 지우고, final을 떼고, 실패 결과 Javadoc을 쓰고, NUL은 \u0000으로 쓴다. final을 뗀 유스케이스는 SpotBugs CT_CONSTRUCTOR_THROW에 걸려, config/spotbugs/exclude.xml의 CGLIB 그룹을 @UseCaseCapability가 붙은 *UseCase class까지 넓힌다(유스케이스 계약이 final을 금한다). 버린 대안: operation id 값 타입 하나로 통일(path segment가 '/'를 실을 수 있게 되거나 지금 유효한 caller id를 거절한다). 위험·한계: 공개 생성자와 타입이 바뀐다. 파생 서비스가 할 일은 docs/upgrade/2026-11-round9-application.md 1·2행이다(최종 안내에서는 4·7행). 검증: PR 본문의 desktop 결과. Refs: RR9-05-11, RR9-05-12, RR9-05-13, RR9-05-14, RR9-05-15, RR9-05-16, RR9-05-17, RR9-05-18 BREAKING CHANGE: OperationCommand·GetDurableOperationQuery·CancelDurableOperationCommand의 tenant가 Optional<TenantId>이고 OperationCommand에 operation id 인자가 없다. SubmitDurableOperationUseCase 생성자가 DurableOperationIdFactory를 받는다. ReadConsistency, FileserverSpans, ProviderEventId, NotificationExpiredException, BatchNotificationProviderAdapter, CollapseCapability, ProviderCollapseMapping을 지웠다.
12 KiB
05. 멱등성·결과 불명 처리
핵심
쓰기 요청의 결과는 세 가지다: 됐다, 안 됐다, 모른다. "모른다"를 "안 됐다(다시 해도 됨)"로 적으면 같은 작업이 두 번 적용된다. 그래서 결과를 증명할 수 없을 때는 항상 "모른다"로 답하고, 클라이언트가 안전하게 다시 물을 방법(같은 멱등성 키)을 준다.
클라이언트 ── 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로 만드는 순서
@UseCaseCapability(idempotency = Idempotency.KEYED).- 유스케이스 본문을
IdempotencyExecutor로 감싼다. executor를 유스케이스가 만들지 않는다 —composition:idempotency가 한 번 만든다. - scope digest(주체 + 키 + operation 코드의 HMAC)와 요청 fingerprint(SHA-256)를 유스케이스 밖(전송)에서 만든다. 원본 키는 저장소에 닿지 않는다.
- 작업 결과를
IdempotentAction.Outcome(Success/RetryableNoEffect/EffectUnknown)으로 돌려준다. 예외를 던지면 effect-unknown으로 센다. - 저장소 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부터 끝까지 이은 업무 기능 예는 템플릿에 없다.
executor를 쓰지 않는 중복 판정 둘 (2026-11-13 결정)
템플릿에는 IdempotencyExecutor 말고 중복을 판정하는 곳이 둘 더 있다. 둘 다 일부러 executor로 옮기지 않는다.
executor는 응답을 다시 돌려주는 기록이다: HTTP Idempotency-Key 헤더로 들어오고, 원본 키 대신 scope digest만
저장하고, 기록은 TTL이 지나면 지운다. 아래 둘은 업무 행 자체의 정체성이라 수명과 판정 대상이 다르다.
| 어디 | 키 | 같은 키·같은 요청 | 같은 키·다른 요청 | 수명 |
|---|---|---|---|---|
| executor(KEYED 유스케이스) | Idempotency-Key 헤더의 scope digest |
저장된 응답 재생 | 422 IDEMPOTENT_REQUEST_MISMATCH |
TTL |
알림 받기(AcceptNotificationApplicationUseCase) |
본문의 idempotencyKey. 없으면 알림 plan 지문 |
처음 만든 알림의 receipt | IDEMPOTENCY_CONFLICT(요청 지문 비교) |
알림 행과 같다 |
durable operation 제출(SubmitDurableOperationUseCase) |
제출 scope(tenant·principal·operation 이름)와 payload 지문 | 처음 받은 operation | 지문이 키에 들어 있어 다른 키다. 새 operation | operation 보존 기간 |
- 알림: 키는 tenant 안에서 같은 알림을 한 번만 만드는 업무 키다. 저장소의 유일 제약이 동시 제출을 막고, 진 쪽은 이긴 행을 읽어 같은 receipt로 수렴한다. 키를 주지 않은 호출자도 중복을 막도록 plan 지문으로 키를 만든다. executor로 옮기면 TTL 뒤 같은 알림을 다시 만들고, 키 없는 호출은 중복을 막지 못한다. 저장한 키 값을 어떻게 다룰지(원본 저장)는 보안 검토 항목이다.
- durable operation: 결정 15·26(서버가 id를 만들고 payload 지문으로 재제출을 판정)이 정한다. capability의
KEYED는 "같은 scope·같은 payload로 다시 보내면 같은 작업"이라는 뜻이고, 그 판정은 operation 저장소의 scope 유일성이 한다. - 새 기능이 이 둘을 따라 할 일은 거의 없다. 클라이언트가 응답을 못 받아 다시 보내는 쓰기는 위 순서대로 executor를 쓴다. 업무 행 자체가 영구히 하나여야 하면(04장 유일 제약) 그 행의 키로 판정한다.
클라이언트에게 무엇을 약속하나
| 응답 | 의미 | 클라이언트 행동 |
|---|---|---|
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-coreoutbox) - 알림 발송 시작 뒤 crash → 재발송하지 않고 reconcile(application-notification evidence 모델)
- DB 커밋 중 끊김 →
- 예외: 요청이 상대에게 도달하기 전에 실패한 것이 증명되면(연결 수립 실패, 실행 전 거부) 재시도 가능이다. 반대 방향 실수(확실히 안 간 것을 불명으로)도 결함이다(2026-11-01 성숙도 리뷰가 Redis 연결 수립 실패에서 찾았다).
- 불명 상태를 푸는 방법(reconcile, 키 재전송, 운영자 확인)을 runbook에 적는다(
docs/runbooks/).
지금 이해하면 되는 것
- "두 번 = 피해"인 쓰기는 KEYED. executor는 composition이 만든다.
- 409 in-flight는 같은 키로 다시, 422는 버그, 500 completion-unknown은 키 없이 재시도 금지.
- 상대편에 효과가 났을 수 있으면 "모른다"로 분류한다.