문제(round7 리뷰 RR7-01-03~06): - 분산 락 timeout(LockAcquisitionTimeoutException)이 ApiErrorCarrier가 아니어서 web·GraphQL·gRPC 모두 500 INTERNAL_ERROR(재시도 불가)와 "unhandled" ERROR로 답한다. 레지스트리·runbook·Javadoc은 409 재시도 가능을 약속한다. web은 carrier가 되어도 Retry-After 표에 이 코드가 없어 헤더가 빠진다. - 다른 예외로 감싼 carrier를 gRPC만 원인 사슬에서 찾고 web·GraphQL· STOMP는 500 INTERNAL_ERROR로 답하며 SQL 원인째 ERROR로 남긴다. - gRPC 서비스가 IllegalArgumentException을 원인으로 든 raw status를 던지면 INTERNAL_ERROR·ERROR(입력이 든 메시지 첨부)이고, onError로 넘기면 BAD_PARAMETER·WARN이다. - STOMP @MessageMapping 앞에서 Spring이 거부한 클라이언트 메시지(읽지 못한 payload, 비었거나 검증에 걸린 payload, 변환되지 않는 @DestinationVariable·@Header)를 ERROR와 예외 메시지(받은 JSON 조각· 값)로 남긴다. 고른 방법: - shared-contract ApiErrorCarrier.firstIn(Throwable): 원인 사슬의 첫 carrier를 찾는다(자기 자신 포함, 사슬이 돌면 멈춤). web 처리기 둘, GraphQL 매퍼, gRPC 인터셉터, STOMP advice와 ERROR 프레임이 모두 이 함수를 쓰고 gRPC carrierOf와 STOMP의 carrier 루프는 지웠다. 로그 줄은 찾은 carrier로 정해 감싼 persistence 실패도 분류 한 줄만 남는다 (소유자 결정 2026-11-06 (a)). - LockAcquisitionTimeoutException이 ApiErrorCarrier를 구현한다. errorCode() 반환 타입은 OperationalError로 둔다(공변 반환, 호출부 변경 없음). RetryAfterAdvisor에 LOCK_ACQUISITION_TIMEOUT=1(레지스트리 값)을 더한다. 버린 안: web 전용 @ExceptionHandler — GraphQL·gRPC가 그대로 남는다. - gRPC close는 status 예외를 벗긴 실패 하나(failureBehind)로 carrier·IAE 판정과 로그를 모두 한다. 버린 안: closeWithError에서 status를 다시 만드는 것 — 판정과 로그가 또 다른 값을 볼 수 있다. - ServerFailureLog.refused(code, failure): refusedArgument와 같은 WARN 한 줄(타입만, 메시지·예외 없음). STOMP advice가 받은 메시지가 실린 MessageConversionException과 MethodArgumentNotValidException을 VALIDATION_FAILED, @DestinationVariable·@Header 대상 ConversionFailedException을 BAD_PARAMETER로 남긴다(web이 같은 실패에 답하는 코드). 응답을 쓰다 난 변환 실패는 받은 메시지가 없어 ERROR로 남는다. 위험·한계: - 응답이 바뀐다: 락 timeout 500 → 409(+Retry-After: 1), 감싼 carrier 500 → 그 carrier 코드, IAE가 감싼 carrier 400 → carrier 코드, gRPC가 던진 IAE 원인 raw status INTERNAL → INVALID_ARGUMENT. 업그레이드 안내 B-45·B-46과 5절에 적었다. - STOMP 쓰기/읽기 변환 실패 구분은 Spring 7.0.9 변환기가 읽기 실패에만 failedMessage를 싣는 데 기댄다(바이트코드로 확인). 바뀌면 aReplyTheConverterCannotWriteIsLoggedAtErrorWithTheFailure가 실패한다. - 고치지 않은 같은 모양(범위 밖, 보고에 적음): RetryAfterAdvisor 표에서 빠진 레지스트리 값 7개, GraphQL @Argument BindException의 INTERNAL_ERROR·ERROR, STOMP 필수 header 누락의 ERROR. 검증(desktop, flock /tmp/claude-gates/heavy.lock, 로그 ~/r8-f1-logs/): - RED(기준73d39212+ 테스트만): 7개 leaf에서 17건 실패, 모두 위 결함의 값(500 INTERNAL_ERROR, INTERNAL, ERROR + 입력 메시지 등). red.log, red-websocket.log - GREEN(이 트리b540d48e): shared-contract 269, application-core 413(skip 19, 이전부터), web 334, graphql 401, grpc 74, websocket 105, app-bootstrap 225(skip 4, 이전부터) 실패 0. green-test.log - :ci :verifyDependencyLocks --warning-mode=fail rc=0 - :sample-portfolio:check :sample-portfolio:qualityCheck rc=0 - :verifyStrictLaneStages --dry-run, -p optional-platforms 같은 것 rc=0 - -p optional-platforms ci rc=0 - web·graphql·websocket systemTest, :conditionalTransportQualification rc=0(web 18, graphql 34+8, grpc 29, websocket 21+7) - :app-bootstrap:documentContractTest rc=0(66) - 바뀐 7개 leaf testQualityCheck rc=0 - scripts/verify-compose-profile-contracts.sh rc=0 BREAKING CHANGE: 분산 락 timeout은 409 LOCK_ACQUISITION_TIMEOUT (retryable, Retry-After: 1), 다른 예외로 감싼 carrier는 web·GraphQL에서도 그 carrier 코드, gRPC가 던진 IllegalArgumentException 원인 raw status는 INVALID_ARGUMENT로 답한다. 클라이언트는 error.code로 가르면 바꿀 것이 없다. 업그레이드 안내 B-45·B-46. Refs: docs/reviews/2026-11-03-rereview/round7/01-core-inbound.md RR7-01-03, RR7-01-04, RR7-01-05, RR7-01-06
1.3 KiB
1.3 KiB
title, category, error_codes, severity, owner, last_updated, status
| title | category | error_codes | severity | owner | last_updated | status | |
|---|---|---|---|---|---|---|---|
| Runbook — LOCK_ACQUISITION_TIMEOUT (분산 락 획득 타임아웃) | CONFLICT |
|
P2 | oncall | 2026-11-07 | stub |
Runbook: LOCK_ACQUISITION_TIMEOUT (runbook://lock/acquisition-timeout)
Symptoms
- HTTP 409 with
error.code=LOCK_ACQUISITION_TIMEOUTandRetry-After: 1; GraphQL extensioncode=LOCK_ACQUISITION_TIMEOUT, gRPC trailererror-code: LOCK_ACQUISITION_TIMEOUT(ABORTED), allretryable=true. A 4xx answer, so no server ERROR line — look at the metric. - Before 2026-11-07 the template answered this as 500
INTERNAL_ERRORwith an "unhandled exception" ERROR line (the exception was not anApiErrorCarrier). A service on an older template sees that instead. - Distributed lock wait exceeded configured timeout; high contention on a resource
Diagnosis
- Check
lock.acquisitionmetric for lock name and duration - Identify lock holders (check DB
integration_locktable)
Action
- Client should retry with backoff (retryable=true)
- Optimize critical section holding time if lock contention is systemic
Escalation
- Escalate if lock holder appears stuck (potential deadlock in distributed lock)
Stub: Phase D2 — author body after domain adoption. (feature-operational-runbook-contract D9)