diff --git a/docs/upgrade/2026-11-maturity-review.md b/docs/upgrade/2026-11-maturity-review.md index 5990e3ab..7349473a 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) · 태그 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절에 @@ -100,8 +100,8 @@ | B-31 | 핸들러 밖 오류(`/error` 디스패치)를 `EnvelopeErrorController`가 실패 Envelope로 답한다. 전에는 Boot `/error` 맵이 `success:true`로 감싸져 요청 경로까지 실려 나갔다. 기본 JWT 체인에서 익명 400이 401로 바뀌지 않는다. 4xx·5xx 본문은 `success:true`로 감싸지 않는다. 보안 체인이 `DispatcherType.ERROR`를 허용한다 | 오류 본문 모양이 바뀐다. 자기 SecurityFilterChain이 ERROR 디스패치를 막으면 400이 401로 나간다 | 자기 체인에 `auth.dispatcherTypeMatchers(DispatcherType.ERROR).permitAll()`을 넣는다(템플릿 `SecurityConfig`와 같게) | `bbe944bd` · `src/adapter/inbound/web/.../error/EnvelopeErrorController.java`, `.../auth/SecurityConfig.java` | | 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`를 둔 서비스는 그쪽 응답이 그대로 나간다 | `Retry-After` 뒤 같은 요청을 다시 보내게 한다. 자기 처리기를 두었다면 지워도 된다 | r8-f1(2026-11-07, 재리뷰 RR7-01-04) · `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`) | 감싼 실패에 500·`INTERNAL`을 받던 클라이언트가 이제 그 carrier 코드(예: 503 `DB_UNAVAILABLE`)를 받는다 | 클라이언트 분기는 `error.code`로 한다(바꿀 것 없음). 감싼 실패를 일부러 500으로 보내려면 감싸지 말고 `IllegalStateException`을 던진다 | r8-f1(2026-11-07, 소유자 결정 2026-11-06, 재리뷰 RR7-01-05·RR7-01-03) · `src/shared-contract/.../error/ApiErrorCarrier.java` `firstIn`, 네 전송의 오류 처리기 | +| 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-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 00e6217f..086151bf 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -91,7 +91,8 @@ | 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의 코드가 된다 | 소유자 | `1103` 18.4절(RR7-01-05), 2026-11-06 | +| 감싼 carrier를 전송이 읽는 법 | web·GraphQL·STOMP·gRPC 네 전송 모두 원인 사슬의 첫 carrier를 본다. 감싼 carrier의 응답이 500 `INTERNAL_ERROR` 대신 그 carrier의 코드가 된다. 그보다 먼저 답하는 것은 아래 「GraphQL 판정 순서」 행(등록 매핑)이다 | 소유자 | `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 총괄 세션 전달 | | `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/CLAUDE.md b/src/adapter/inbound/graphql/CLAUDE.md index 29729833..069ebbf2 100644 --- a/src/adapter/inbound/graphql/CLAUDE.md +++ b/src/adapter/inbound/graphql/CLAUDE.md @@ -121,9 +121,10 @@ application/platform namespace split. 모든 client 에러는 `error/GraphQlWireErrorMapper` 하나를 거친다 — 전송 interceptor, 실행 전 pipeline(instrumentation), data fetcher resolver 세 곳이 같은 bean 을 받는다. 순서는 플랫폼 거부 -(예외가 구현한 `error/GraphQlPlatformRejection`) → `ApiErrorCarrier`(자기 또는 원인 사슬의 첫 carrier의 -`ApiErrorCode`) → 등록된 -application 매핑(`GraphQlExceptionResolver`) → `IllegalArgumentException`·인자 binder의 `BindException`=`BAD_PARAMETER`. 어디에도 안 +(예외가 구현한 `error/GraphQlPlatformRejection`) → 실패 자신이 `ApiErrorCarrier`면 그 `ApiErrorCode` → 등록된 +application 매핑(`GraphQlExceptionResolver`) → 원인 사슬의 첫 carrier → `IllegalArgumentException`·인자 binder의 +`BindException`=`BAD_PARAMETER`(2026-11-07 소유자 결정). 등록 매핑이 원인 사슬의 carrier보다 먼저라, 앱이 등록한 +실패는 하위 실패를 원인으로 들어도 등록한 코드로 답한다. 실패 자신이 carrier인 타입은 등록해도 쓰이지 않는다. 어디에도 안 걸린 예외는 `INTERNAL_ERROR` 로 가려지고, 같은 executionId 로 ERROR 로그 한 줄이 남는다. client 문구는 shared-contract `ClientErrorMessages`(Category 별 한국어 표), `retryable` 은 코드의 값이다. Category → wire category/`ErrorType` 표는 mapper 의 `RENDERINGS` 하나뿐이고 [README.md](README.md)에 옮겨 둔다. diff --git a/src/adapter/inbound/graphql/README.md b/src/adapter/inbound/graphql/README.md index aae4250b..bed4b92a 100644 --- a/src/adapter/inbound/graphql/README.md +++ b/src/adapter/inbound/graphql/README.md @@ -66,19 +66,24 @@ instrumentation, data fetcher resolver 세 곳이 같은 bean 을 받는다). 1. **플랫폼 거부** — 플랫폼 예외가 `error/GraphQlPlatformRejection`(wire code·shared `Category`· 필요하면 wire category/constraint)을 구현한다. `instanceof` 사슬로 등록하던 두 번째 목록은 없다. -2. **`ApiErrorCarrier`** — 실패 자신이나 원인 사슬의 첫 carrier(`ApiErrorCarrier.firstIn`, web·gRPC·STOMP와 - 같은 함수)를 그 `ApiErrorCode` 로 매핑. 로그 줄도 감싼 예외가 아니라 그 carrier 로 정한다(재리뷰 RR7-01-05). - shared-contract 의 `MappingException`· +2. **실패 자신이 `ApiErrorCarrier`** — 그 `ApiErrorCode` 로 매핑. shared-contract 의 `MappingException`· `AdapterDisabledException`·`PersistenceFailureException`(JPA 예외 포함)·`DependencyFailureException`, - application 의 멱등성 예외, DataLoader 키 실패(`GraphQlBatchLoadException`, **등록된 `ApiErrorCode` - 만** — 소유자 결정 25)가 모두 여기로 온다. -3. **등록된 application 매핑**(`GraphQlExceptionResolver`). -4. **`IllegalArgumentException`과 인자 binder의 `BindException`** → `BAD_PARAMETER`(`REQUEST`, `BAD_REQUEST`) — + application 의 멱등성·락 예외, DataLoader 키 실패(`GraphQlBatchLoadException`, **등록된 `ApiErrorCode` + 만** — 소유자 결정 25)가 모두 여기로 온다. 이런 타입을 `GraphQlExceptionResolver`에 등록해도 쓰이지 않는다. +3. **등록된 application 매핑**(`GraphQlExceptionResolver`). 앱이 그 실패 타입에 내린 결정이라 원인 사슬의 + carrier보다 먼저다. 앱이 등록한 실패가 하위 실패(예: `PersistenceFailureException`)를 원인으로 들어도 등록한 + 코드로 답한다. web 에서 앱의 도메인 advice 가 먼저 받는 것과 같다(소유자 결정 2026-11-07, 재리뷰 RR8-01-01). +4. **원인 사슬의 첫 carrier**(`ApiErrorCarrier.firstIn`, web·gRPC·STOMP와 같은 함수) — 등록되지 않은 예외가 + 감싼 carrier 를 그 코드로 매핑(재리뷰 RR7-01-05). +5. **`IllegalArgumentException`과 인자 binder의 `BindException`** → `BAD_PARAMETER`(`REQUEST`, `BAD_REQUEST`) — web·gRPC·STOMP 와 같다. `BindException`은 `@Argument` 값이 파라미터 타입으로 바뀌지 않을 때 Spring 이 컨트롤러 전에 던진다(web 의 경로 변수 변환 실패와 같은 답, 소유자 결정 2026-11-07). 로그도 같은 WARN 한 줄 `request refused as BAD_PARAMETER by <예외 타입> (executionId=)` 이고, 입력값이 들 수 있는 메시지 (`BindException`은 `rejected value [...]`)는 남기지 않는다. -5. 나머지는 `INTERNAL_ERROR` 로 가려지고 같은 executionId 로 ERROR 로그 한 줄이 남는다. +6. 나머지는 `INTERNAL_ERROR` 로 가려지고 같은 executionId 로 ERROR 로그 한 줄이 남는다. + +로그 줄은 어느 단계가 답하든 원인 사슬의 첫 carrier 로 정한다. 등록 매핑이 답한 실패도 그 안의 서버 쪽 carrier +(예: DB 연결 실패)는 그 carrier 의 줄(persistence 는 분류만)을 남긴다. 4xx carrier 는 남기지 않는다. - **client 문구**: shared-contract `ClientErrorMessages`(Category 별 한국어 문구 표 하나, 소유자 결정 11). 예외 메시지는 절대 나가지 않는다. diff --git a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolver.java b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolver.java index 47d9eee1..bea2abe4 100644 --- a/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolver.java +++ b/src/adapter/inbound/graphql/src/main/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlExceptionResolver.java @@ -13,6 +13,11 @@ import org.slf4j.LoggerFactory; * message. That default is the important half: a new exception type introduced anywhere in the * stack is masked automatically instead of leaking until someone notices. * + *

A registered mapping answers before a carrier in the failure's cause chain, so a failure the + * application models keeps its code when it keeps what it translated as its cause. A failure that + * is itself an {@code ApiErrorCarrier} answers with its own code before any mapping is consulted; + * registering such a type changes nothing ({@link GraphQlWireErrorMapper#map}). + * *

Partial data is untouched here. This maps one failing field; sibling fields that resolved stay * in the response. */ 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 47fdda2d..97ba2cf3 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 @@ -40,12 +40,13 @@ import org.springframework.validation.BindException; * the detail goes to the log under that id ({@link GraphQlExceptionResolver}). * *

A carrier is logged here, with {@link ServerFailureLog}'s line — the one the web and gRPC - * adapters write — plus the execution id the client received. A server-side code therefore leaves - * its detail in the log, such as the scope digest of an {@code IDEMPOTENCY_RECOVERY_REQUIRED} - * (review 2026-11-04 RR4-03-03); a persistence failure leaves its classification only. An unmapped - * {@link IllegalArgumentException} leaves the WARN line every transport writes for it, naming its - * type and never its message (review 2026-11-05 RR6-01-06); so does an {@code @Argument} the - * argument binder refused, whose message quotes the rejected value. + * adapters write — plus the execution id the client received, also when a registered mapping + * answers the failure that wraps it. A server-side code therefore leaves its detail in the log, + * such as the scope digest of an {@code IDEMPOTENCY_RECOVERY_REQUIRED} (review 2026-11-04 + * RR4-03-03); a persistence failure leaves its classification only. An unmapped {@link + * IllegalArgumentException} leaves the WARN line every transport writes for it, naming its type and + * never its message (review 2026-11-05 RR6-01-06); so does an {@code @Argument} the argument binder + * refused, whose message quotes the rejected value. */ public final class GraphQlWireErrorMapper { @@ -106,44 +107,60 @@ public final class GraphQlWireErrorMapper { /** * Maps a failure from any stage. * - *

Order: a platform rejection, then an {@link ApiErrorCarrier} — the failure itself or the - * first one in its cause chain, as on every transport (review 2026-11-06 RR7-01-05) — then the - * application's registered mappings, then a refused argument as {@code BAD_PARAMETER} (the same - * answer every transport gives), and finally the masked internal error. A refused argument is an - * {@link IllegalArgumentException} or the {@link BindException} 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). - * Platform rejections come first: an authorization denial raised from inside a resolver means the - * same thing to a client as one raised before execution. A registered mapping outranks the - * argument rule so an application that models its own {@code IllegalArgumentException} subtype - * keeps its code. + *

Order (owner decision 2026-11-07, re-review RR8-01-01): + * + *

    + *
  1. a platform rejection; + *
  2. a failure that is itself an {@link ApiErrorCarrier}, by its code; + *
  3. the application's registered mappings; + *
  4. the first carrier in the failure's cause chain, as on every transport (review 2026-11-06 + * RR7-01-05); + *
  5. a refused argument as {@code BAD_PARAMETER}, the same answer every transport gives; + *
  6. the masked internal error. + *
+ * + *

Platform rejections come first: an authorization denial raised from inside a resolver means + * the same thing to a client as one raised before execution. A registered mapping outranks a + * carrier in the cause chain because it is the application's decision about that failure type — a + * failure it models keeps its code when it keeps what it translated as its cause, as an + * application's own exception handler keeps it on the web transport. It does not outrank a + * failure that is itself a carrier: that failure already says its code. It outranks the argument + * rule so an application that models its own {@code IllegalArgumentException} subtype keeps its + * code. A refused argument is an {@link IllegalArgumentException} or the {@link BindException} + * 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). */ public GraphQlWireError map(Throwable failure, GraphQlErrorContext context) { if (failure instanceof GraphQlPlatformRejection rejection) { return fromRejection(rejection, context); } ApiErrorCode shared = sharedCodeOf(failure); + logAnswer(failure, shared, context); if (shared != null) { - logAnswer(failure, shared, context); return fromApiError(shared, context); } return applicationMappings.resolve(failure, context); } /** - * Writes {@link ServerFailureLog}'s line for a failure answered with a shared code: the carrier's - * line at ERROR — the carrier's, not a wrapper's — or nothing for a client-side carrier; an - * unmapped refused argument the WARN line naming its type, as on every transport. A binding - * failure's message quotes the rejected value, so it is never logged. + * Writes {@link ServerFailureLog}'s line for a failure: the line of the first carrier in its + * cause chain at ERROR — the carrier's, not a wrapper's — or nothing for a client-side carrier, + * whichever stage answers, so a failure the application registered still leaves the server-side + * carrier it wraps in the log; an unmapped refused argument the WARN line naming its type, as on + * every transport. A binding failure's message quotes the rejected value, so it is never logged. + * Anything else is logged by the masking resolver, or not at all when a mapping answers it. + * + * @param shared the shared code the failure is answered with, or {@code null} */ private static void logAnswer( Throwable failure, ApiErrorCode shared, GraphQlErrorContext context) { String suffix = " (executionId={})"; Optional carrier = ApiErrorCarrier.firstIn(failure); if (carrier.isPresent()) { - ServerFailureLog.of(carrier.get(), shared) + ServerFailureLog.of(carrier.get(), ((ApiErrorCarrier) carrier.get()).errorCode()) .ifPresent(line -> LOG.error(line.format(suffix), line.arguments(context.executionId()))); - } else if (isRefusedArgument(failure)) { + } else if (shared != null && isRefusedArgument(failure)) { ServerFailureLog line = ServerFailureLog.refused(OperationalError.BAD_PARAMETER, failure); LOG.warn(line.format(suffix), line.arguments(context.executionId())); } @@ -201,18 +218,24 @@ public final class GraphQlWireErrorMapper { } /** - * The shared code a failure carries, or {@code null}: the code of the first carrier in its cause - * chain. + * The shared code a failure is answered with, or {@code null} when a registered mapping or the + * masking answers it — stages 2, 4 and 5 of {@link #map}'s order. * *

A refused argument the application did not register a mapping for is {@link * OperationalError#BAD_PARAMETER}, as it is on the web, gRPC and STOMP transports. */ private ApiErrorCode sharedCodeOf(Throwable failure) { + if (failure instanceof ApiErrorCarrier carrier) { + return carrier.errorCode(); + } + if (applicationMappings.maps(failure)) { + return null; + } Optional carrier = ApiErrorCarrier.firstIn(failure); if (carrier.isPresent()) { return ((ApiErrorCarrier) carrier.get()).errorCode(); } - if (isRefusedArgument(failure) && !applicationMappings.maps(failure)) { + if (isRefusedArgument(failure)) { return OperationalError.BAD_PARAMETER; } return null; diff --git a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapperTest.java b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapperTest.java index 511c46d0..bf3a6673 100644 --- a/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapperTest.java +++ b/src/adapter/inbound/graphql/src/test/java/dev/caskeleton/adapter/inbound/graphql/error/GraphQlWireErrorMapperTest.java @@ -302,6 +302,75 @@ class GraphQlWireErrorMapperTest { null); } + @org.junit.jupiter.api.Test + void aRegisteredFailureThatKeepsACarrierAsItsCauseIsAnsweredWithItsRegisteredCode() { + // given + GraphQlWireErrorMapper mapper = new GraphQlWireErrorMapper(orderUnavailableRegistered()); + RuntimeException failure = new OrderUnavailableException(persistenceFailureWithASqlCause()); + + // when + GraphQlWireError error = mapper.map(failure, GraphQlErrorContext.test()); + + // then + assertThat(error.extensions()) + .extracting(extensions -> extensions.get("code"), extensions -> extensions.get("category")) + .containsExactly("ORDER_UNAVAILABLE", "BUSINESS"); + } + + @org.junit.jupiter.api.Test + void aRegisteredFailureThatKeepsACarrierAsItsCauseStillLeavesTheCarriersServerLine() { + // given + GraphQlWireErrorMapper mapper = new GraphQlWireErrorMapper(orderUnavailableRegistered()); + RuntimeException failure = new OrderUnavailableException(persistenceFailureWithASqlCause()); + + // when + List logged = + loggedWhile(() -> mapper.map(failure, GraphQlErrorContext.of("exec-9"))); + + // then + assertThat(logged) + .singleElement() + .extracting(ILoggingEvent::getFormattedMessage, ILoggingEvent::getThrowableProxy) + .containsExactly( + "persistence failure classified as DB_UNAVAILABLE (category=TRANSIENT_DEPENDENCY," + + " retryable=true) (executionId=exec-9)", + null); + } + + @org.junit.jupiter.api.Test + void aCarrierTheApplicationAlsoRegisteredIsAnsweredWithItsOwnCode() { + // given + GraphQlWireErrorMapper mapper = + new GraphQlWireErrorMapper( + GraphQlExceptionResolver.builder() + .map( + LockAcquisitionTimeoutException.class, + GraphQlErrorCode.of("ORDER_BUSY"), + GraphQlErrorCategory.BUSINESS, + "주문을 처리하는 중입니다") + .build()); + RuntimeException failure = + new LockAcquisitionTimeoutException("orders/42", Duration.ofSeconds(3)); + + // when + GraphQlWireError error = mapper.map(failure, GraphQlErrorContext.test()); + + // then + assertThat(error.extensions()) + .extracting(extensions -> extensions.get("code"), extensions -> extensions.get("retryable")) + .containsExactly("LOCK_ACQUISITION_TIMEOUT", true); + } + + private static GraphQlExceptionResolver orderUnavailableRegistered() { + return GraphQlExceptionResolver.builder() + .map( + OrderUnavailableException.class, + GraphQlErrorCode.of("ORDER_UNAVAILABLE"), + GraphQlErrorCategory.BUSINESS, + "주문을 지금 처리할 수 없습니다") + .build(); + } + private static PersistenceFailureException persistenceFailureWithASqlCause() { return new PersistenceFailureException( OperationalError.DB_UNAVAILABLE, @@ -309,6 +378,15 @@ class GraphQlWireErrorMapperTest { new SQLException("jdbc:postgresql://db.internal/customer?password=secret", "08006")); } + /** A failure the application models and registers; it keeps what it translated as its cause. */ + private static final class OrderUnavailableException extends RuntimeException { + private static final long serialVersionUID = 1L; + + OrderUnavailableException(Throwable cause) { + super("order unavailable", cause); + } + } + /** * Every line this package writes while {@code action} runs: the mapper's own and the masking * resolver's, so a failure that should have been classified but was masked shows up too. diff --git a/src/shared-contract/README.md b/src/shared-contract/README.md index 28f5acc6..168ac86c 100644 --- a/src/shared-contract/README.md +++ b/src/shared-contract/README.md @@ -86,6 +86,9 @@ Spring/Lettuce 타입을 노출하지 않는다. adapter가 carrier를 다른 예외로 감싸 던져도 네 전송 모두 그 carrier의 코드로 답한다. 전에는 gRPC만 사슬을 따라가고 web·GraphQL·STOMP는 500 `INTERNAL_ERROR`로 답했다(소유자 결정 2026-11-06, 재리뷰 RR7-01-05). 사슬이 자기 자신으로 돌아오면 거기서 멈춘다. +- 원인 사슬의 carrier 보다 먼저 답하는 것이 있다. + - GraphQL 에서 앱이 `GraphQlExceptionResolver` 에 등록한 실패 타입은 원인에 carrier 가 있어도 등록한 코드로 + 답한다. 실패 자신이 carrier 면 그 코드가 등록 매핑보다 먼저다(소유자 결정 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 7cc6c281..052eaad3 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 @@ -34,6 +34,9 @@ public interface ApiErrorCarrier { * alike, instead of {@code INTERNAL_ERROR} on some of them (review 2026-11-06 RR7-01-05). The * search stops where a cause chain loops back on itself. * + *

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). + * * @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