fix(inbound)!: 네 전송이 같은 실패에 같은 코드와 로그로 답한다
문제(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
This commit is contained in:
@@ -577,8 +577,10 @@ application 계층은 락 획득/해제 계약만 알고, 실제 구현은 adapt
|
||||
- `OperationalError.LOCK_ACQUISITION_TIMEOUT`(CONFLICT, 409, retryable=true)을 운반한다. 락
|
||||
경합은 일시적이다 — 현재 보유자가 임계 구역을 떠나거나 lease TTL 이 만료되면 재시도가
|
||||
획득한다(D6 효율 락).
|
||||
- web adapter 가 `errorCode()` + 고정 client-safe 메시지로 409 를 만든다. 진단용 `getMessage()`
|
||||
(key·waitTime 포함)는 서버 로그 전용이고 API 클라이언트에 전달하면 안 된다.
|
||||
- `ApiErrorCarrier` 를 구현한다. 그래서 전송이 따로 처리기를 두지 않아도 web 은 409 +
|
||||
`Retry-After: 1`(레지스트리 값), GraphQL·gRPC 는 같은 코드로 답하고, 4xx 라 서버 로그를 남기지 않는다. 전에는
|
||||
carrier 가 아니어서 모든 전송이 500 `INTERNAL_ERROR`(재시도 불가)와 "unhandled" ERROR 로 답했다(재리뷰
|
||||
RR7-01-04). 진단용 `getMessage()`(key·waitTime 포함)는 서버 로그 전용이고 API 클라이언트에 전달하면 안 된다.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+9
-4
@@ -1,16 +1,20 @@
|
||||
package dev.caskeleton.application.lock;
|
||||
|
||||
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||
import dev.caskeleton.shared.error.OperationalError;
|
||||
import java.time.Duration;
|
||||
|
||||
/**
|
||||
* Thrown by {@link DistributedLockPort#tryAcquire(String, Duration, Duration)} when the lock could
|
||||
* not be acquired within the bounded {@code waitTime}. Carries {@link
|
||||
* OperationalError#LOCK_ACQUISITION_TIMEOUT} (CONFLICT, 409, retryable — contention is transient).
|
||||
* The web adapter maps it to 409 with a client-safe message; {@link #getMessage()} is
|
||||
* server-log-only. See README.
|
||||
* OperationalError#LOCK_ACQUISITION_TIMEOUT} (CONFLICT, 409, retryable — contention is transient)
|
||||
* through {@link ApiErrorCarrier}, the hook every inbound transport reads a code from: the web
|
||||
* adapter answers 409 with {@code Retry-After}, GraphQL and gRPC the same code, and none of them
|
||||
* logs it as an unhandled failure. Without the hook it was answered as a 500 {@code INTERNAL_ERROR}
|
||||
* (review 2026-11-06 RR7-01-04). {@link #getMessage()} is server-log-only. See README.
|
||||
*/
|
||||
public final class LockAcquisitionTimeoutException extends RuntimeException {
|
||||
public final class LockAcquisitionTimeoutException extends RuntimeException
|
||||
implements ApiErrorCarrier {
|
||||
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@@ -41,6 +45,7 @@ public final class LockAcquisitionTimeoutException extends RuntimeException {
|
||||
* Returns {@link OperationalError#LOCK_ACQUISITION_TIMEOUT}, the stable client-facing error code
|
||||
* for a distributed-lock timeout.
|
||||
*/
|
||||
@Override
|
||||
public OperationalError errorCode() {
|
||||
return OperationalError.LOCK_ACQUISITION_TIMEOUT;
|
||||
}
|
||||
|
||||
+7
@@ -2,6 +2,7 @@ package dev.caskeleton.application.lock;
|
||||
|
||||
import static org.assertj.core.api.Assertions.assertThat;
|
||||
|
||||
import dev.caskeleton.shared.error.ApiErrorCarrier;
|
||||
import dev.caskeleton.shared.error.OperationalError;
|
||||
import java.time.Duration;
|
||||
import org.junit.jupiter.api.Test;
|
||||
@@ -25,6 +26,12 @@ class LockAcquisitionTimeoutExceptionTest {
|
||||
assertThat(ex.errorCode()).isEqualTo(OperationalError.LOCK_ACQUISITION_TIMEOUT);
|
||||
}
|
||||
|
||||
@Test
|
||||
void isAnApiErrorCarrier() {
|
||||
assertThat(new LockAcquisitionTimeoutException("orders/42", Duration.ofSeconds(3)))
|
||||
.isInstanceOf(ApiErrorCarrier.class);
|
||||
}
|
||||
|
||||
@Test
|
||||
void messageContainsKey() {
|
||||
LockAcquisitionTimeoutException ex =
|
||||
|
||||
Reference in New Issue
Block a user