Files
clean-architecture-backend-…/docs/runbooks/idempotency-unavailable.md
T
DongHyeonka bbe944bd3c fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가
Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다.
@SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히
prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고,
GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로
나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역
발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다.

방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를
먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이
기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록,
@SystemInvoked bean은 기동 실패, complete 단계 실패는
IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도
SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도
행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도
내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제
지표(redis.lane.*) 기준으로 고쳤다.

위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이
브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류
디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어
파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은
기동을 막는다. httpclient failure-injection lane의 main 단계 중복
실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci
integrationCheck performanceCheck, :performanceCheck, :releaseCheck
(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과.
첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event
id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절
BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호
첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드
IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은
static·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00

2.7 KiB

title, category, error_codes, severity, owner, last_updated, status
title category error_codes severity owner last_updated status
Runbook — IDEMPOTENCY_UNAVAILABLE (멱등성 조정 저장소 사용 불가) TRANSIENT_DEPENDENCY
IDEMPOTENCY_UNAVAILABLE
IDEMPOTENCY_COMPLETION_UNKNOWN
IDEMPOTENCY_RECOVERY_REQUIRED
P2 oncall 2026-11-03 active

Runbook: IDEMPOTENCY_UNAVAILABLE (runbook://idempotency/unavailable)

Symptoms

  • HTTP 503 (error.code=IDEMPOTENCY_UNAVAILABLE, retryable=true) on endpoints that take an Idempotency-Key; the same code on the gRPC error-code trailer (UNAVAILABLE).
  • IdempotencyExecutor refused to run the action because the replay store (JPA or Redis, whichever app.idempotency selects) did not answer. Nothing was executed: the refusal happens before the action, so a client retry is safe.
  • HTTP 503 IDEMPOTENCY_COMPLETION_UNKNOWN (retryable=true) is the same outage hitting after the action ran: the store did not answer while the result was being recorded. Effects in the action's own transaction rolled back; anything else it did (an outbound call, a message) may have happened. This is not "nothing was executed". Clients resend with the same key.
  • HTTP 500 IDEMPOTENCY_RECOVERY_REQUIRED (retryable=false) means the opposite case: the store cannot tell whether an earlier attempt's external effect already happened.

Diagnosis

  • Check the health of the idempotency store the service uses (/actuator/health component of the JPA datasource or Redis, depending on the selected provider).
  • Look for connection-pool saturation or timeouts on that store in the same time window; the executor reports saturation as unavailable rather than guessing.
  • For IDEMPOTENCY_RECOVERY_REQUIRED, find the scope digest in the server log line of the failed request and inspect that record's state in the store.

Action

  • IDEMPOTENCY_UNAVAILABLE: restore the store; clients retry with the same key and backoff.
  • IDEMPOTENCY_COMPLETION_UNKNOWN: restore the store, then check the effects outside the transaction for the failed requests (the ERROR log line names the code). A same-key resend replays a result that was in fact recorded, gets IDEMPOTENT_IN_FLIGHT while the attempt's lease lasts, and IDEMPOTENCY_RECOVERY_REQUIRED after it — handle that one as below.
  • IDEMPOTENCY_RECOVERY_REQUIRED: do not ask the client to retry blindly. Confirm whether the downstream effect of the earlier attempt exists, then complete or release the record so the next request with that key replays or re-executes deterministically.

Escalation

  • P2 → P1 when the store stays unavailable for more than 10 minutes on a write path.
  • Page the owner of the idempotency store (database or Redis on-call).