fix(inbound): 인자 변환 실패는 원인의 carrier와 상관없이 거부로 본다

문제(round8 리뷰 01 「Declined to judge」, 리뷰 README 19.4절 ④):
- 결정 「감싼 carrier를 전송이 읽는 법」이 인자 변환 단계까지 덮는지
  정해지지 않았다. STOMP advice는 @DestinationVariable·@Header의
  ConversionFailedException과 받은 메시지가 실린
  MessageConversionException의 원인에 carrier가 있으면 거부 WARN 한 줄
  대신 그 carrier의 줄(5xx면 ERROR와 예외)을 남긴다. web은 같은 실패에
  원인을 보지 않고 BAD_PARAMETER·VALIDATION_FAILED로 답한다.

고른 방법(소유자 결정 2026-11-07, ④ (a)):
- 인자 변환 단계는 carrier를 보지 않는다. StompHandlerFailureLog가 거부
  판정(clientRefusalOf)을 원인 사슬의 carrier 검색보다 먼저 한다.
  응답 프레임은 그대로다(handler 경로는 프레임을 보내지 않는다).
- web은 지금 동작이 결정과 같아 코드를 바꾸지 않았다. 경로 변수 변환기와
  Jackson creator가 carrier를 던지는 지킴 테스트 둘을 더하고,
  handleTypeMismatch·handleHttpMessageNotReadable Javadoc에 이유를 적었다.
- GraphQL @Argument binder는 변환기가 던진 실패를 binding result에 담고
  BindException의 원인으로 싣지 않아, carrier를 던져도 BAD_PARAMETER다.
  실제 binder 경로 지킴 테스트 하나와 매퍼 Javadoc·README 한 줄.
- 버린 안: (b) 세 전송의 변환 단계가 원인의 carrier를 먼저 본다 — 요청
  형식 오류의 코드가 변환기 구현에 따라 바뀐다.

위험·한계:
- 바뀌는 것은 STOMP 로그 줄뿐이다. 템플릿에는 carrier를 던지는 변환기가
  없다. 안내 B-46에 적었다.
- GraphQL 지킴 테스트는 Spring for GraphQL 2.0.5 binder의 동작에 기댄다.
  binder가 원인을 싣게 바뀌면 그 테스트가 실패한다.

검증(desktop, flock, --no-build-cache, 로그 ~/r9-g1-inbound-logs/):
- RED(기준 3eb3b067 + 테스트만, 트리 4feb83c6): :adapter:inbound:websocket:test
  --tests StompHandlerFailureLogTest rc=1, 13건 중 2건 실패. 두 경우 모두
  기대 WARN "request refused as VALIDATION_FAILED|BAD_PARAMETER by
  <변환 예외>", 실제 ERROR "persistence failure classified as
  DB_UNAVAILABLE ...". red/R2c-websocket.log
- 지킴(RED 없음 — 지금 동작이 결정과 같다): web TransportErrorHandlingTest
  12건(red/R3c-web-guard.log)과 GraphQlArgumentBindingFailureTest
  (트리 7c45e303, red/R1b-graphql.log)가 기준 커밋에서 통과. 변이:
  handleTypeMismatch가 원인의 carrier를 먼저 보게 바꾸면 12건 중 1건
  (경로 변수) 실패, 400 대신 503. red/R7c-web-guard-mutant.log
- GREEN(이 커밋 트리 1a5b4a8f): :adapter:inbound:websocket:check
  :adapter:inbound:web:check :adapter:inbound:graphql:check
  :shared-contract:check rc=0, websocket 107·web 343·graphql 408·
  shared-contract 269건 실패 0·skip 0, FROM-CACHE 0. green2/B1-check.log
- testQualityCheck 첫 실행(green/D16)에서 이 커밋의 테스트 record 둘
  (Signup, `if (email != null)`)이 SpotBugs NP_LOAD_OF_KNOWN_NULL_VALUE로
  걸려 `!email.isEmpty()`로 고쳤다. 고친 테스트로 RED·지킴·변이를 다시
  돌렸고(위 R2c·R3c·R7c), 마지막 트리에서 web·websocket spotbugsTest가
  실행되어 통과했다(green2/D16).

Refs: docs/reviews/2026-11-03-rereview/README.md 19.4절 ④, round8/01-transport-errors.md 「Declined to judge」
This commit is contained in:
DongHyeonka
2026-11-07 08:22:59 +09:00
parent e1fb049b64
commit ee5b4e1b7e
13 changed files with 221 additions and 11 deletions
+5
View File
@@ -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).
@@ -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<Envelope<Void>> 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<Object> handleHttpMessageNotReadable(
HttpMessageNotReadableException ex,
@@ -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<String, String> invoice(@PathVariable("number") InvoiceNumber number) {
return Map.of("ok", "unreachable: the number never converts");
}
@PostMapping(value = "/t/signup", consumes = MediaType.APPLICATION_JSON_VALUE)
Map<String, String> signup(@RequestBody Signup signup) {
return Map.of("ok", "unreachable: the body never reads");
}
@GetMapping("/t/async-timeout")
Map<String, String> 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);
}
}
}
}