S3 control 저장소는 SDK가 응답을 잃고 다시 보낸 조건부 PUT의 412를 충돌로 본다. MongoDB 집계는 결과 바이트 예산을 보지 않고 전부 메모리에 올린다. tenant client registry는 쓰는 중인 client를 내보내고, 내보내다 닫기에 실패하면 다른 tenant의 acquire가 실패한다. migration lease를 잃은 runner가 그 뒤에도 checkpoint를 쓴다. HTTP client는 SOCKS proxy를 HTTP로 붙이고, 압축을 켜면 Apache는 스스로 풀어 max-wire-bytes가 푼 크기를 세며, JDK transport는 그 설정을 읽지 않는다. 고른 방법: S3는 412에서 다시 읽어 이 호출이 쓴 record 그대로면 성공으로 본다. 집계는 $limit(maxResults + 1)과 maxResultBytes를 집행한다. registry acquire는 Lease를 돌려주고 쓰는 중에는 내보내지 않으며 idle은 마지막 close부터 잰다. 상한·lease 수·내보내기는 registry 밖에서 잡을 수 없는 전용 lock 하나로 묶는다. 닫기 실패는 evictionCloseFailures가 센다. migration ledger는 lock 문서의 현재 fence로 쓴다. ProxyType은 HTTP만 남긴다. 압축은 RestClient 기본 헤더로 보내고 ContentDecoding이 버퍼·스트리밍 본문을 모두 푼다(겹친 coding과 그 밖의 coding은 거부, 빈 본문은 빈 본문). Jetty HTTP/3는 기동 뒤 decoder를 비운다. 버린 대안: SOCKS 지원 (transport 셋 중 하나만 된다), transport마다 자동 풀기(크기 상한이 transport마다 달라진다), 집계를 RawBsonDocument로 재기(converter를 거치지 않으면 반환 타입 mapping이 갈라진다). 위험·한계: MongoTenantClientRegistry.acquire 반환형과 ProxyType이 바뀐다. S3에서 두 writer가 같은 버전에서 같은 record를 쓰면 둘 다 성공으로 본다 (Javadoc과 안내 3절). 집계 결과는 converter로만 바뀌어 entity callback이 돌지 않는다. evictionCloseFailures 지표는 지표 묶음에 넘긴다. 검증: desktop RED(pr2-red2). GREEN은 PR 본문의 verify.sh pr 결과. Refs: RR9-01-08, RR9-01-11, RR9-01-19, RR9-01-20, RR9-01-27, RR9-01-28, RR9-01-30, RR9-01-31 BREAKING CHANGE: MongoTenantClientRegistry.acquire가 Lease를 돌려주고, migration lease를 잃은 refresh가 MongoOperationRejectedException을 던진다. HTTP client ProxyType.SOCKS가 없어져 그 설정은 바인딩이 실패한다. request.compression이 모든 transport에서 같은 coding만 받는다. docs/upgrade/2026-11-round9-outbound.md
10 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부터 끝까지 이은 업무 기능 예는 템플릿에 없다.
클라이언트에게 무엇을 약속하나
| 응답 | 의미 | 클라이언트 행동 |
|---|---|---|
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 저장소에서 같은 키 재전송은 효과가 있었을 수 있는 작업을 다시 돌리지
않는다. 단, 그 기록이 Redis에 남아 있는 동안만이다. Sentinel·Cluster failover는 비동기 복제라 primary가 받고
replica에 아직 넘기지 못한 기록을 잃을 수 있고, 그러면 같은 키 요청은 처음 보는 키로 다시 실행된다
(docs/runbooks/redis-capability-incident.md 「Topology and persistence」). 이 창이 업무상 받아들일 수 없는
작업은 PostgreSQL 저장소를 쓰거나 업무 데이터의 유일 제약으로 따로 막는다. 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은 키 없이 재시도 금지.
- 상대편에 효과가 났을 수 있으면 "모른다"로 분류한다.