diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index 7349473a..7deb37c1 100644 --- a/docs/upgrade/2026-11-maturity-review.md +++ b/docs/upgrade/2026-11-maturity-review.md @@ -4,7 +4,7 @@ - 커밋: `34565130` High·P1 19건 · `1400dc15` 남은 발견·매뉴얼·생성 명령 · `5786126c` 남은 항목과 합친 뒤 결함 · `7ef8d0b4` 재리뷰 기록 · `bbe944bd` 재리뷰 결함 · `ecc74b7d` 2차 재리뷰 기록·이 안내 · `1885bf8d` 2차 재리뷰 결함 · `339cf8fd` 3차 확인 리뷰 기록 · `f40c03c6` 3차 확인 리뷰 Minor · `c2e55510` 마지막 확인 리뷰 기록 · - `2678955c` 테스트 코드 정적 분석(B-40) · `70fb80bf` 소유자가 다시 정한 기본값 3가지(늦은 멱등 완료 기록, `failure-retention` 기동 검사, workflow `cd`) · B4 성능 lane 단언 상시화(2026-11-06, B-43) · `paths` 필터 trigger를 단계 실행으로 세지 않음(2026-11-06 소유자 결정, B-36) · r8-f1 전송 오류 처리(2026-11-07, B-45~B-48) · r9-g1 GraphQL 판정 순서(2026-11-07 소유자 결정, B-45·B-46) · 태그 push·`release` workflow는 `releaseCheck`에만 셈(2026-11-07 소유자 결정, B-36) — `docs(...)` 커밋은 문서만 바꾼다 + `2678955c` 테스트 코드 정적 분석(B-40) · `70fb80bf` 소유자가 다시 정한 기본값 3가지(늦은 멱등 완료 기록, `failure-retention` 기동 검사, workflow `cd`) · B4 성능 lane 단언 상시화(2026-11-06, B-43) · `paths` 필터 trigger를 단계 실행으로 세지 않음(2026-11-06 소유자 결정, B-36) · r8-f1 전송 오류 처리(2026-11-07, B-45~B-48) · r9-g1 GraphQL 판정 순서와 인자 변환 단계(2026-11-07 소유자 결정, B-45·B-46) · 태그 push·`release` workflow는 `releaseCheck`에만 셈(2026-11-07 소유자 결정, B-36) — `docs(...)` 커밋은 문서만 바꾼다 - 근거 문서: `docs/reviews/2026-11-01-maturity-review/README.md` 13~16절, `docs/reviews/2026-11-03-rereview/README.md` 4·6·8~13절, 각 커밋의 `BREAKING CHANGE:` 꼬리말 - 아래 표의 각 줄은 위 범위의 diff와 코드로 확인했다. 확인하지 못한 것은 그 자리에 "확인 못 함"으로 적었고 9절에 @@ -101,7 +101,7 @@ | B-32 | 새·바뀐 오류 코드: 비동기 요청 timeout 500 `INTERNAL_ERROR` → 503 `REQUEST_TIMEOUT`(retryable). `IDEMPOTENCY_KEY_INVALID` 400(`details.reason`=`MISSING`·`MALFORMED`, `IdempotencyKeyHeader.parse`를 쓰는 엔드포인트, sample은 `BAD_PARAMETER`에서 바뀜). web-advanced 예외 10종이 모두 500 `INTERNAL_ERROR`였다가 각자 코드(`ADMISSION_REFUSED` 503 등) | 코드로 분기하던 클라이언트가 새 코드를 모른다 | 클라이언트 분기표에 더한다. web-advanced 표는 `src/adapter/inbound/web-advanced/README.md` 「오류 응답」 | `1400dc15` · `src/adapter/inbound/web/.../error/WebTransportError.java`, `HttpStatusErrorCodes.java`, `src/adapter/inbound/web-advanced/.../error/WebAdvancedError.java` | | B-33 | DB 실패 분류: 낙관적 잠금 충돌 500 → 409 `DB_OPTIMISTIC_CONFLICT`. 커밋 단계 연결 끊김(08xxx, 40003 등)을 재시도 가능으로 답하던 것 → 500 `DB_COMPLETION_UNKNOWN`(retryable=false) | 응답 status·code가 바뀐다 | 409는 다시 읽고 재시도, `DB_COMPLETION_UNKNOWN`은 업무 데이터로 결과를 확인 | `34565130`, `1400dc15` · `src/adapter/outbound/persistence-jpa/.../failure/PersistenceExceptionTranslator.java` | | B-45 | 분산 락 timeout(`LockAcquisitionTimeoutException`): 500 `INTERNAL_ERROR`(retryable=false) → 409 `LOCK_ACQUISITION_TIMEOUT`(retryable=true, `Retry-After: 1`). GraphQL extension `code`·`retryable`, gRPC `ABORTED` + trailer `error-code`도 같은 코드. 예외가 `ApiErrorCarrier`가 되어 레지스트리가 약속한 값으로 답한다. 4xx라 "unhandled exception" ERROR 줄이 사라진다 | 500을 "재시도 금지"로 읽던 클라이언트가 이제 409를 받는다. 이 예외에 자기 `@ExceptionHandler`를 둔 서비스는 web에서 그쪽 응답이 그대로 나간다. GraphQL에서 이 예외를 `GraphQlExceptionResolver`에 등록한 매핑은 쓰이지 않는다: 실패 자신이 carrier라 그 코드가 등록 매핑보다 먼저다 | `Retry-After` 뒤 같은 요청을 다시 보내게 한다. 자기 처리기와 GraphQL 등록 매핑을 두었다면 지워도 된다 | r8-f1(2026-11-07, 재리뷰 RR7-01-04), r9-g1(2026-11-07, 재리뷰 RR8-01-01) · `src/application-core/.../lock/LockAcquisitionTimeoutException.java`, `src/adapter/inbound/web/.../observability/RetryAfterAdvisor.java` | -| B-46 | 다른 예외로 감싼 carrier: web·GraphQL도 gRPC처럼 원인 사슬의 첫 carrier 코드로 답한다(전에는 500 `INTERNAL_ERROR`). `IllegalArgumentException`이 carrier를 감쌌으면 `BAD_PARAMETER` 대신 그 carrier 코드다. STOMP ERROR 프레임의 `error-code`도 `IllegalArgumentException` 뒤의 carrier를 그 코드로 낸다. gRPC는 `Status.INVALID_ARGUMENT.withCause(iae)`처럼 `IllegalArgumentException`을 원인으로 든 raw status를 던져도 `onError`로 넘긴 것과 같이 `INVALID_ARGUMENT`·`BAD_PARAMETER`다(전에는 던지면 `INTERNAL`). 바뀌지 않는 것(소유자 결정 2026-11-07): GraphQL에서 앱이 `GraphQlExceptionResolver`에 등록한 실패는 carrier를 원인으로 들어도 등록한 코드로 답한다(등록 매핑이 원인 사슬의 carrier보다 먼저, 실패 자신이 carrier면 그 코드가 먼저). | 감싼 실패에 500·`INTERNAL`을 받던 클라이언트가 이제 그 carrier 코드(예: 503 `DB_UNAVAILABLE`)를 받는다. GraphQL 등록 매핑의 답은 그대로다 | 클라이언트 분기는 `error.code`로 한다(바꿀 것 없음). 감싼 실패를 일부러 500으로 보내려면 감싸지 말고 `IllegalStateException`을 던진다 | r8-f1(2026-11-07, 소유자 결정 2026-11-06, 재리뷰 RR7-01-05·RR7-01-03), r9-g1(2026-11-07, 재리뷰 RR8-01-01, README 19.4절 ①) · `src/shared-contract/.../error/ApiErrorCarrier.java` `firstIn`, 네 전송의 오류 처리기 | +| B-46 | 다른 예외로 감싼 carrier: web·GraphQL도 gRPC처럼 원인 사슬의 첫 carrier 코드로 답한다(전에는 500 `INTERNAL_ERROR`). `IllegalArgumentException`이 carrier를 감쌌으면 `BAD_PARAMETER` 대신 그 carrier 코드다. STOMP ERROR 프레임의 `error-code`도 `IllegalArgumentException` 뒤의 carrier를 그 코드로 낸다. gRPC는 `Status.INVALID_ARGUMENT.withCause(iae)`처럼 `IllegalArgumentException`을 원인으로 든 raw status를 던져도 `onError`로 넘긴 것과 같이 `INVALID_ARGUMENT`·`BAD_PARAMETER`다(전에는 던지면 `INTERNAL`). 바뀌지 않는 것 둘(소유자 결정 2026-11-07): GraphQL에서 앱이 `GraphQlExceptionResolver`에 등록한 실패는 carrier를 원인으로 들어도 등록한 코드로 답한다(등록 매핑이 원인 사슬의 carrier보다 먼저, 실패 자신이 carrier면 그 코드가 먼저). 인자 변환 단계 — web `MethodArgumentTypeMismatchException`·`HttpMessageNotReadableException`, GraphQL `@Argument` binder — 는 원인에 carrier가 있어도 `BAD_PARAMETER`·`VALIDATION_FAILED`다. STOMP는 `@DestinationVariable`·`@Header`의 `ConversionFailedException`과 받은 메시지가 실린 `MessageConversionException`을 원인의 carrier와 상관없이 거부 WARN 한 줄로 남긴다 | 감싼 실패에 500·`INTERNAL`을 받던 클라이언트가 이제 그 carrier 코드(예: 503 `DB_UNAVAILABLE`)를 받는다. GraphQL 등록 매핑과 인자 변환 실패의 답은 그대로다 | 클라이언트 분기는 `error.code`로 한다(바꿀 것 없음). 감싼 실패를 일부러 500으로 보내려면 감싸지 말고 `IllegalStateException`을 던진다 | r8-f1(2026-11-07, 소유자 결정 2026-11-06, 재리뷰 RR7-01-05·RR7-01-03), r9-g1(2026-11-07, 재리뷰 RR8-01-01, README 19.4절 ①·④) · `src/shared-contract/.../error/ApiErrorCarrier.java` `firstIn`, 네 전송의 오류 처리기 | | B-47 | `Retry-After`를 레지스트리 `retry_after_seconds`대로 붙인다. 새로 붙는 응답: 503 `DB_UNAVAILABLE` 5초, 409 `DB_SERIALIZATION_FAILURE`·`DB_DEADLOCK` 1초, 503 `DB_IDLE_IN_TX_TIMEOUT` 2초(나머지 `OUTBOX_PUBLISH_FAILED`·`JOB_*`는 HTTP로 나가지 않는 코드다). 전에는 web 표에서 빠져 헤더가 없었다. 표와 레지스트리를 `OperationalErrorRegistryContractTest`(document-contract, `mainCheck`)가 대조한다 | 이 응답에 `Retry-After`가 생긴다. 템플릿 `OperationalError` 행의 `retry_after_seconds`를 바꾼 서비스는 `RetryAfterAdvisor` 표도 같이 바꾸지 않으면 `mainCheck`가 실패한다(대조 대상은 `OperationalError` 코드뿐이다) | 헤더를 따르는 클라이언트는 그만큼 기다렸다 재시도한다. 자기 코드의 값은 그 코드가 `RetryAfterHint`로 말한다 | r8-f1(2026-11-07, 소유자 결정) · `src/adapter/inbound/web/.../observability/RetryAfterAdvisor.java`, `src/app-bootstrap/src/test/.../contract/OperationalErrorRegistryContractTest.java` | | B-48 | GraphQL `@Argument` 값이 컨트롤러 파라미터 타입으로 바뀌지 않으면(Spring 인자 binder의 `BindException`) `INTERNAL_ERROR`(`INTERNAL`) 대신 `BAD_PARAMETER`(`REQUEST`, `BAD_REQUEST`)로 답한다. 로그는 ERROR + 예외(`rejected value [...]`가 실림) 대신 WARN 한 줄 `request refused as BAD_PARAMETER by org.springframework.validation.BindException (executionId=…)`이다 | 그 실패에 `INTERNAL_ERROR`를 받던 클라이언트가 `BAD_PARAMETER`를 받는다. ERROR 경보가 잘못된 인자에 울리지 않는다 | 클라이언트는 `extensions.code`로 가른다. `BindException`에 자기 `GraphQlExceptionResolver` 매핑을 둔 서비스는 그 매핑이 그대로 먼저다 | r8-f1(2026-11-07, 소유자 결정) · `src/adapter/inbound/graphql/.../error/GraphQlWireErrorMapper.java` | diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 086151bf..0e8db3d7 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -91,8 +91,9 @@ | Draft-12 offset 불일치 | problem 문서는 프로토콜 예외로 유지 | 소유자 | 결정 12 | | 알림 category 생략 | 거부(400), 판정은 유스케이스 | 소유자 | 결정 13 | | 오류 코드 로그 레벨 | `error-codes.yaml`에 `log_level` 칸을 두지 않는다. 레벨은 실패 종류·경로가 정한다(`ServerFailureLog`, 보안 필터 `AuthErrorResponseWriter`). 칸이 다시 생기면 `OperationalErrorRegistryContractTest`가 실패한다. 보안 필터는 5xx(`AUTH_JWKS_UNAVAILABLE`·`INTERNAL_AUTH_MISCONFIGURATION`)를 ERROR, 4xx를 WARN으로 남긴다. 401 서명·issuer·audience 불일치는 WARN | 소유자 | 2026-11-06, `docs/superpowers/specs/2026-11-06-error-code-log-level-design.md` 10절 | -| 감싼 carrier를 전송이 읽는 법 | web·GraphQL·STOMP·gRPC 네 전송 모두 원인 사슬의 첫 carrier를 본다. 감싼 carrier의 응답이 500 `INTERNAL_ERROR` 대신 그 carrier의 코드가 된다. 그보다 먼저 답하는 것은 아래 「GraphQL 판정 순서」 행(등록 매핑)이다 | 소유자 | `1103` 18.4절(RR7-01-05), 2026-11-06 | +| 감싼 carrier를 전송이 읽는 법 | web·GraphQL·STOMP·gRPC 네 전송 모두 원인 사슬의 첫 carrier를 본다. 감싼 carrier의 응답이 500 `INTERNAL_ERROR` 대신 그 carrier의 코드가 된다. 그보다 먼저 답하는 것은 아래 「GraphQL 판정 순서」(등록 매핑)와 「인자 변환 단계의 감싼 carrier」 두 행이다 | 소유자 | `1103` 18.4절(RR7-01-05), 2026-11-06 | | GraphQL 판정 순서 | 플랫폼 거부 → 실패 자신이 carrier → 등록된 application 매핑 → 원인 사슬의 첫 carrier → 거부된 인자(`IllegalArgumentException`, 인자 binder의 `BindException`) → 가림(`INTERNAL_ERROR`). 앱이 등록한 실패는 carrier를 원인으로 들어도 등록한 코드로 답한다(web에서 앱의 도메인 advice가 먼저 받는 것과 같다). 실패 자신이 carrier인 타입(예: `LockAcquisitionTimeoutException`)을 등록한 매핑은 쓰이지 않는다. 로그 줄은 어느 단계가 답하든 원인 사슬의 첫 carrier로 정한다 — 등록 매핑이 답해도 그 안의 서버 쪽 carrier 줄은 남는다 | 소유자(2026-11-07). 로그 줄은 기본값(2026-11-07) | `1103` 19.4절 ①(RR8-01-01), 2026-11-07 총괄 세션 전달 | +| 인자 변환 단계의 감싼 carrier | 「감싼 carrier를 전송이 읽는 법」은 인자 변환 단계를 덮지 않는다. web `MethodArgumentTypeMismatchException`·`HttpMessageNotReadableException`과 GraphQL `@Argument` binder 실패는 원인에 carrier가 있어도 `BAD_PARAMETER`·`VALIDATION_FAILED`다. STOMP는 `@DestinationVariable`·`@Header`의 `ConversionFailedException`과 받은 메시지가 실린 `MessageConversionException`을 원인 사슬의 carrier보다 먼저 거부로 보고 WARN 한 줄(타입만)을 남긴다. 요청 형식 오류의 코드는 전송이 정한다 | 소유자(2026-11-07) | `1103` 19.4절 ④(round8/01 「Declined to judge」), 2026-11-07 총괄 세션 전달 | | `Retry-After` 값 | web `RetryAfterAdvisor` 표는 레지스트리 `retry_after_seconds` 칸과 코드마다 같다. 빠져 있던 7개(`DB_UNAVAILABLE` 5, `DB_SERIALIZATION_FAILURE` 1, `DB_DEADLOCK` 1, `DB_IDLE_IN_TX_TIMEOUT` 2, `OUTBOX_PUBLISH_FAILED` 30, `JOB_EXECUTOR_REJECTED` 5, `JOB_TIMEOUT` 10)를 채웠고, `OperationalErrorRegistryContractTest`가 둘을 대조한다 | 소유자 | 2026-11-07 총괄 세션 전달(소유자 원문 "권하는 안대로"), r8-f1 보고 「범위 밖」 1 | | GraphQL 인자 변환 실패 | Spring GraphQL 인자 binder의 `BindException`(`@Argument` 값이 파라미터 타입으로 바뀌지 않음)은 `BAD_PARAMETER`(`REQUEST`)로 답하고, WARN 한 줄(예외 타입만, 입력값 없음)을 남긴다. web이 바뀌지 않는 경로 변수에 답하는 것과 같다 | 소유자 | 2026-11-07 같은 전달, r8-f1 보고 「범위 밖」 2 | | 약속한 응답으로 맞추기 | 레지스트리·`docs/web/http-contract.md`·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이다. 고치기 전에 묻지 않고, 응답이 바뀌니 업그레이드 안내 행은 적는다. 약속한 곳끼리 다르면 묻는다 | 기본값(2026-11-07) | `docs/work/improve.md` 7절, `docs/work/evidence.md` 11절 | diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index bed4b92a..5462d7aa 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -77,7 +77,9 @@ instrumentation, data fetcher resolver 세 곳이 같은 bean 을 받는다). 감싼 carrier 를 그 코드로 매핑(재리뷰 RR7-01-05). 5. **`IllegalArgumentException`과 인자 binder의 `BindException`** → `BAD_PARAMETER`(`REQUEST`, `BAD_REQUEST`) — web·gRPC·STOMP 와 같다. `BindException`은 `@Argument` 값이 파라미터 타입으로 바뀌지 않을 때 Spring 이 컨트롤러 - 전에 던진다(web 의 경로 변수 변환 실패와 같은 답, 소유자 결정 2026-11-07). 로그도 같은 WARN 한 줄 + 전에 던진다(web 의 경로 변수 변환 실패와 같은 답, 소유자 결정 2026-11-07). 변환기가 던진 실패는 binding + result 에 남고 원인으로 실리지 않아, 변환기가 carrier 를 던져도 답은 `BAD_PARAMETER`다(인자 변환 단계는 carrier 를 + 보지 않는다, 소유자 결정 2026-11-07). 로그도 같은 WARN 한 줄 `request refused as BAD_PARAMETER by <예외 타입> (executionId=)` 이고, 입력값이 들 수 있는 메시지 (`BindException`은 `rejected value [...]`)는 남기지 않는다. 6. 나머지는 `INTERNAL_ERROR` 로 가려지고 같은 executionId 로 ERROR 로그 한 줄이 남는다. diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapper.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapper.java index 97ba2cf3..3dceb849 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapper.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapper.java @@ -130,6 +130,10 @@ public final class GraphQlWireErrorMapper { * Spring for GraphQL's argument binder raises when an {@code @Argument} the client sent does not * convert to the parameter's type, as the web adapter answers a path variable that does not * (owner decision 2026-11-07). + * + *

The binder keeps a converter's failure in the binding result, not as a cause, so a carrier a + * converter throws never answers in place of {@code BAD_PARAMETER}: the argument conversion stage + * does not read a carrier (owner decision 2026-11-07). */ public GraphQlWireError map(Throwable failure, GraphQlErrorContext context) { if (failure instanceof GraphQlPlatformRejection rejection) { diff --git a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlArgumentBindingFailureTest.java b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlArgumentBindingFailureTest.java index 286d0112..a738d769 100644 --- a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlArgumentBindingFailureTest.java +++ b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/runtime/GraphQlArgumentBindingFailureTest.java @@ -7,10 +7,13 @@ import ch.qos.logback.classic.Logger; import ch.qos.logback.classic.spi.ILoggingEvent; import ch.qos.logback.core.read.ListAppender; import dev.caskeleton.adapter.inbound.graphql.error.GraphQlWireErrorMapper; +import dev.caskeleton.shared.error.OperationalError; +import dev.caskeleton.shared.error.PersistenceFailureException; import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.List; import java.util.UUID; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.slf4j.LoggerFactory; import org.springframework.context.annotation.AnnotationConfigApplicationContext; @@ -33,7 +36,8 @@ import org.springframework.stereotype.Controller; */ class GraphQlArgumentBindingFailureTest { - private static final String SCHEMA = "type Query { order(id: ID!): String }"; + private static final String SCHEMA = + "type Query { order(id: ID!): String invoice(number: String!): String }"; private static final String QUERY = "{ order(id: \"alice@example.com\") }"; @@ -71,6 +75,21 @@ class GraphQlArgumentBindingFailureTest { null); } + @Test + @DisplayName("변환기가 carrier 를 던져도 인자 변환 실패는 BAD_PARAMETER 다(인자 변환 단계는 carrier 를 보지 않는다)") + void anArgumentWhoseConverterThrowsACarrierIsStillABadParameterRequestError() { + // when + List errors = errorsOf("{ invoice(number: \"INV-1\") }"); + + // then + assertThat(errors) + .singleElement() + .extracting( + error -> error.getExtensions().get("code"), + error -> error.getExtensions().get("category")) + .containsExactly("BAD_PARAMETER", "REQUEST"); + } + private static List errorsOf(String document) { AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext(); context.registerBean(OrderController.class); @@ -123,5 +142,25 @@ class GraphQlArgumentBindingFailureTest { String order(@Argument UUID id) { return id.toString(); } + + @QueryMapping + String invoice(@Argument InvoiceNumber number) { + return "unreachable: the number never converts"; + } + } + + /** An argument type whose conversion fails with a server-side carrier, as a lookup could. */ + public static final class InvoiceNumber { + + private InvoiceNumber() {} + + /** The conversion the binder finds; a lookup that fails with a carrier for any number. */ + public static InvoiceNumber valueOf(String value) { + if (!value.isEmpty()) { + throw new PersistenceFailureException( + OperationalError.DB_UNAVAILABLE, "invoice lookup failed for " + value, null); + } + return new InvoiceNumber(); + } } } diff --git a/src/adapter/inbound/web/README.md b/src/adapter/inbound/web/README.md index dba5396d..a172a5d4 100644 --- a/src/adapter/inbound/web/README.md +++ b/src/adapter/inbound/web/README.md @@ -215,6 +215,11 @@ commit-aware response wrapper 계약을 구현한다. 또한 이 모듈은 HTML 원인 사슬의 첫 carrier(`ApiErrorCarrier.firstIn`)를 찾아 `handleCarrier` 로 넘긴다. 감싼 persistence 실패도 500 `INTERNAL_ERROR` 와 SQL 원인 대신 그 분류 코드와 분류 한 줄로 남는다. GraphQL·gRPC·STOMP 도 같은 함수를 쓴다(소유자 결정 2026-11-06, 재리뷰 RR7-01-05). +- 인자 변환 단계는 원인의 carrier 를 보지 않는다. 경로 변수·쿼리 파라미터가 바뀌지 않은 + `MethodArgumentTypeMismatchException` 은 `BAD_PARAMETER`, 읽지 못한 본문의 `HttpMessageNotReadableException` 은 + `VALIDATION_FAILED` 다. 사용자 `Converter` 나 Jackson creator 가 carrier 를 던져 그 원인에 있어도 같다. 요청 + 형식 오류이고 그 코드는 전송이 정한다(소유자 결정 2026-11-07, 재리뷰 README 19.4절 ④). STOMP 도 같은 실패를 + 거부로 남긴다. 단언은 `TransportErrorHandlingTest`. - 개별 override 가 없는 Spring MVC 예외(필수 파라미터·헤더·part 누락, binding 실패 등)는 `handleExceptionInternal` override 가 상태 코드 → 코드로 바꿔 같은 Envelope 로 보낸다. 503(Spring 의 async 요청 시간 초과)은 `INTERNAL_ERROR` 가 아니라 `REQUEST_TIMEOUT`(503, retryable) 이다(리뷰 02-08). diff --git a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java index 4b04a6c3..22563880 100644 --- a/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java +++ b/src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/error/GlobalExceptionHandler.java @@ -108,6 +108,12 @@ public class GlobalExceptionHandler extends ResponseEntityExceptionHandler { return ErrorResponseFactory.envelope(OperationalError.VALIDATION_FAILED, violations); } + /** + * A path variable, query parameter or header that does not convert to its parameter's type is + * {@code BAD_PARAMETER}, whatever the conversion threw: a carrier a user {@code Converter} threw + * is not searched for, because the argument conversion stage answers a malformed request with the + * transport's own code (owner decision 2026-11-07). STOMP logs the same failure as a refusal. + */ @ExceptionHandler(MethodArgumentTypeMismatchException.class) public ResponseEntity> handleTypeMismatch(MethodArgumentTypeMismatchException ex) { Class requiredType = ex.getRequiredType(); @@ -224,6 +230,11 @@ public class GlobalExceptionHandler extends ResponseEntityExceptionHandler { HttpStatusCode.valueOf(OperationalError.VALIDATION_FAILED.httpStatus())); } + /** + * An unreadable body is {@code VALIDATION_FAILED}, or {@code PAYLOAD_TOO_LARGE} when the body + * ceiling cut the read. A carrier a Jackson creator threw is not searched for, for the same + * reason as {@link #handleTypeMismatch}. + */ @Override protected ResponseEntity handleHttpMessageNotReadable( HttpMessageNotReadableException ex, diff --git a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/TransportErrorHandlingTest.java b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/TransportErrorHandlingTest.java index 571a2323..85e9c0b7 100644 --- a/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/TransportErrorHandlingTest.java +++ b/src/adapter/inbound/web/src/test/java/dev/caskeleton/adapter/inbound/web/error/TransportErrorHandlingTest.java @@ -12,6 +12,8 @@ import static org.springframework.test.web.servlet.result.MockMvcResultMatchers. import dev.caskeleton.adapter.inbound.web.conditional.PreconditionFailedException; import dev.caskeleton.adapter.inbound.web.envelope.EnvelopeBodyAdvice; import dev.caskeleton.adapter.inbound.web.pagination.PageValidationException; +import dev.caskeleton.shared.error.OperationalError; +import dev.caskeleton.shared.error.PersistenceFailureException; import dev.caskeleton.shared.tracing.SpanErrorRecorder; import jakarta.validation.constraints.Max; import java.util.List; @@ -24,6 +26,7 @@ import org.springframework.test.web.servlet.MockMvc; import org.springframework.test.web.servlet.setup.MockMvcBuilders; import org.springframework.web.HttpMediaTypeNotAcceptableException; import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestHeader; @@ -150,9 +153,47 @@ class TransportErrorHandlingTest { .andExpect(jsonPath("$.error.details[0].rejectedValue").doesNotExist()); } + @Test + @DisplayName("경로 변수 변환기가 던진 carrier 는 원인에 있어도 보지 않는다: 400 BAD_PARAMETER(인자 변환 단계)") + void aPathVariableWhoseConverterThrowsACarrierIsStillABadParameter() throws Exception { + // when + var result = mvc.perform(get("/t/invoices/INV-1")); + + // then + result + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.error.code").value("BAD_PARAMETER")); + } + + @Test + @DisplayName("본문 생성자가 던진 carrier 는 원인에 있어도 보지 않는다: 400 VALIDATION_FAILED(인자 변환 단계)") + void aBodyWhoseCreatorThrowsACarrierIsStillValidationFailed() throws Exception { + // when + var result = + mvc.perform( + post("/t/signup") + .contentType(MediaType.APPLICATION_JSON) + .content("{\"email\": \"alice@example.com\"}")); + + // then + result + .andExpect(status().isBadRequest()) + .andExpect(jsonPath("$.error.code").value("VALIDATION_FAILED")); + } + @RestController static class Probe { + @GetMapping("/t/invoices/{number}") + Map invoice(@PathVariable("number") InvoiceNumber number) { + return Map.of("ok", "unreachable: the number never converts"); + } + + @PostMapping(value = "/t/signup", consumes = MediaType.APPLICATION_JSON_VALUE) + Map signup(@RequestBody Signup signup) { + return Map.of("ok", "unreachable: the body never reads"); + } + @GetMapping("/t/async-timeout") Map asyncTimeout() { throw new AsyncRequestTimeoutException(); @@ -203,4 +244,29 @@ class TransportErrorHandlingTest { throw new PageValidationException("size", "SIZE_EXCEEDS_MAX", "size must be <= 100"); } } + + /** A path-variable type whose conversion fails with a server-side carrier, as a lookup could. */ + public static final class InvoiceNumber { + + private InvoiceNumber() {} + + /** The conversion Spring finds; a lookup that fails with a carrier for any number. */ + public static InvoiceNumber valueOf(String value) { + if (!value.isEmpty()) { + throw new PersistenceFailureException( + OperationalError.DB_UNAVAILABLE, "invoice lookup failed for " + value, null); + } + return new InvoiceNumber(); + } + } + + /** A request body whose creator fails with a server-side carrier for any address. */ + record Signup(String email) { + Signup { + if (!email.isEmpty()) { + throw new PersistenceFailureException( + OperationalError.DB_UNAVAILABLE, "signup lookup failed", null); + } + } + } } diff --git a/src/adapter/inbound/websocket/README.md b/src/adapter/inbound/websocket/README.md index 242a7067..8bb1bf11 100644 --- a/src/adapter/inbound/websocket/README.md +++ b/src/adapter/inbound/websocket/README.md @@ -48,6 +48,11 @@ 이 예외들의 메시지는 받은 JSON 조각이나 값을 담는다. 그래서 타입만 남긴다. 응답을 JSON으로 쓰지 못한 `MessageConversionException`은 받은 메시지가 실리지 않는다. 서버 탓이라 ERROR로 남는다. + + 이 거부는 원인 사슬의 carrier보다 먼저 판정한다. payload creator나 destination 변수 타입의 변환이 carrier를 + 던져도(조회하다 DB 실패 등) 인자를 거부한 것이라 같은 WARN 한 줄이다. web이 읽지 못한 본문과 바뀌지 않는 경로 + 변수에 원인과 상관없이 `VALIDATION_FAILED`·`BAD_PARAMETER`로 답하는 것과 같다. 인자 변환 단계는 carrier를 보지 + 않는다(소유자 결정 2026-11-07, 재리뷰 README 19.4절 ④). - 그 밖의 예외는 예외와 함께 ERROR. 전에는 Spring이 예외 전체(persistence 실패의 SQL 원인 포함)를 ERROR로 남겼다. 필수 header·destination 변수가 없을 때의 `MessageHandlingException`도 ERROR다. 메시지에 입력값이 없고, Spring이 같은 타입으로 서버 실패도 감싸서 타입만으로는 클라이언트 탓을 가를 수 없다(결정 색인 기본값 2026-11-07). diff --git a/src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLog.java b/src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLog.java index 4e898f5b..18f8f6c9 100644 --- a/src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLog.java +++ b/src/adapter/inbound/websocket/src/main/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLog.java @@ -42,6 +42,12 @@ import org.springframework.web.bind.annotation.ControllerAdvice; * BAD_PARAMETER}, like a path variable). Their messages quote the input, so they are not logged. A * reply the converter could not write is the server's failure: Spring raises the same {@link * MessageConversionException} for it, but without a failed message, and it stays an error. + * + *

Those refusals are judged before the cause chain is searched for a carrier. A converter that + * throws a carrier — a payload creator or a destination-variable type that looks something up — + * still made a refusal of the argument, as the web adapter answers an unreadable body or a path + * variable that does not convert whatever their cause: the argument conversion stage does not read + * a carrier (owner decision 2026-11-07). */ @ControllerAdvice class StompHandlerFailureLog { @@ -50,6 +56,12 @@ class StompHandlerFailureLog { @MessageExceptionHandler void logFailure(Exception failure) { + Optional refusal = clientRefusalOf(failure); + if (refusal.isPresent()) { + ServerFailureLog line = ServerFailureLog.refused(refusal.get(), failure); + log.warn(line.format(""), line.arguments()); + return; + } Optional carrier = ApiErrorCarrier.firstIn(failure); if (carrier.isPresent()) { ServerFailureLog.of(carrier.get(), ((ApiErrorCarrier) carrier.get()).errorCode()) @@ -61,12 +73,6 @@ class StompHandlerFailureLog { log.warn(line.format(""), line.arguments()); return; } - Optional refusal = clientRefusalOf(failure); - if (refusal.isPresent()) { - ServerFailureLog line = ServerFailureLog.refused(refusal.get(), failure); - log.warn(line.format(""), line.arguments()); - return; - } log.error("unhandled failure in a STOMP message handler", failure); } diff --git a/src/adapter/inbound/websocket/src/test/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLogTest.java b/src/adapter/inbound/websocket/src/test/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLogTest.java index 179166e1..6f747789 100644 --- a/src/adapter/inbound/websocket/src/test/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLogTest.java +++ b/src/adapter/inbound/websocket/src/test/java/dev/caskeleton/adapter/inbound/websocket/stomp/StompHandlerFailureLogTest.java @@ -183,6 +183,39 @@ class StompHandlerFailureLogTest { .containsExactly(Level.WARN, "request refused as " + code + " by " + failureType, null); } + /** Arguments whose conversion threw a server-side carrier: the converter, not the use case. */ + static Stream conversionRefusalsAroundACarrier() { + return Stream.of( + Arguments.of( + "/app/signup", + "{\"email\": \"alice@example.com\"}".getBytes(StandardCharsets.UTF_8), + "VALIDATION_FAILED", + "org.springframework.messaging.converter.MessageConversionException"), + Arguments.of( + "/app/invoices/INV-1", + new byte[0], + "BAD_PARAMETER", + "org.springframework.core.convert.ConversionFailedException")); + } + + @ParameterizedTest + @MethodSource("conversionRefusalsAroundACarrier") + @DisplayName("변환기가 던진 carrier 를 원인으로 든 인자 변환 실패도 거부로 WARN 한 줄이다(인자 변환 단계는 carrier 를 보지 않는다)") + void aConversionRefusalAroundACarrierIsStillLoggedAsARefusal( + String destination, byte[] payload, String code, String failureType) { + // when + List logged = loggedWhileHandling(destination, payload, Map.of()); + + // then + assertThat(logged) + .singleElement() + .extracting( + ILoggingEvent::getLevel, + ILoggingEvent::getFormattedMessage, + ILoggingEvent::getThrowableProxy) + .containsExactly(Level.WARN, "request refused as " + code + " by " + failureType, null); + } + @Test void aReplyTheConverterCannotWriteIsLoggedAtErrorWithTheFailure() { // when @@ -321,6 +354,12 @@ class StompHandlerFailureLogTest { @MessageMapping("/count") void count(@Header("count") int count) {} + @MessageMapping("/signup") + void signup(@Payload Signup signup) {} + + @MessageMapping("/invoices/{number}") + void invoice(@DestinationVariable InvoiceNumber number) {} + @MessageMapping("/unwritable-reply") UnwritableReply unwritableReply() { return new UnwritableReply(); @@ -340,6 +379,31 @@ class StompHandlerFailureLogTest { /** A payload a client sends as JSON. */ record Greeting(String name) {} + /** A payload whose creator fails with a server-side carrier for any address. */ + record Signup(String email) { + Signup { + if (!email.isEmpty()) { + throw new PersistenceFailureException( + OperationalError.DB_UNAVAILABLE, "signup lookup failed", null); + } + } + } + + /** A destination-variable type whose conversion fails with a server-side carrier. */ + public static final class InvoiceNumber { + + private InvoiceNumber() {} + + /** The conversion Spring finds; a lookup that fails with a carrier for any number. */ + public static InvoiceNumber valueOf(String value) { + if (!value.isEmpty()) { + throw new PersistenceFailureException( + OperationalError.DB_UNAVAILABLE, "invoice lookup failed for " + value, null); + } + return new InvoiceNumber(); + } + } + /** A reply the JSON converter cannot write: its only property is itself. */ static final class UnwritableReply { public UnwritableReply getSelf() { diff --git a/src/shared-contract/README.md b/src/shared-contract/README.md index 168ac86c..b74c619f 100644 --- a/src/shared-contract/README.md +++ b/src/shared-contract/README.md @@ -89,6 +89,9 @@ Spring/Lettuce 타입을 노출하지 않는다. - 원인 사슬의 carrier 보다 먼저 답하는 것이 있다. - GraphQL 에서 앱이 `GraphQlExceptionResolver` 에 등록한 실패 타입은 원인에 carrier 가 있어도 등록한 코드로 답한다. 실패 자신이 carrier 면 그 코드가 등록 매핑보다 먼저다(소유자 결정 2026-11-07, 재리뷰 README 19.4절 ①). + - 인자 변환 단계(web 경로 변수·본문, STOMP payload·destination 변수·header, GraphQL `@Argument` binder)의 실패는 + 원인에 carrier 가 있어도 거부(`BAD_PARAMETER`·`VALIDATION_FAILED`)다(소유자 결정 2026-11-07, 재리뷰 README + 19.4절 ④). ### ServerFailureLog — 모든 전송이 같은 로그 줄로 - carrier로 답한 실패의 서버 로그 줄을 정한다. web·GraphQL·gRPC·STOMP 어댑터가 이 클래스 하나를 쓴다 diff --git a/src/shared-contract/src/main/java/dev/caskeleton/shared/error/ApiErrorCarrier.java b/src/shared-contract/src/main/java/dev/caskeleton/shared/error/ApiErrorCarrier.java index 052eaad3..62549670 100644 --- a/src/shared-contract/src/main/java/dev/caskeleton/shared/error/ApiErrorCarrier.java +++ b/src/shared-contract/src/main/java/dev/caskeleton/shared/error/ApiErrorCarrier.java @@ -37,6 +37,10 @@ public interface ApiErrorCarrier { *

A mapping a GraphQL application registered for the failure's own type answers before a * carrier found behind the failure (owner decision 2026-11-07). * + *

An argument that did not convert is refused by each transport's argument conversion stage + * whatever the conversion threw; that stage does not search for a carrier (owner decision + * 2026-11-07). + * * @param failure the failure a transport is answering; may be {@code null} * @return the carrier as the throwable it is — hand that to {@link ServerFailureLog#of}, not the * wrapper, so its type still decides what may be logged