fix(graphql)!: cursor·connection 거부와 STOMP 오류 frame을 등록된 코드로 답한다
pr / done (pull_request) Canceled after 0s

GraphQL cursor·connection 예외는 Javadoc이 「안정 요청 오류 코드」라면서
플랫폼 거부가 아니라 INTERNAL_ERROR와 ERROR 로그가 된다. STOMP ERROR
frame은 code만 싣고, 원인 사슬 어디에 IllegalArgumentException이 있든
BAD_PARAMETER로 본다(다른 전송은 실패 자신만 본다). STOMP broadcast는 모든
인증 세션에 가는데 projector가 무엇을 실어도 되는지 규칙이 없다.
maxInputListElements Javadoc은 실제보다 넓은 상한을 약속한다.

- 두 예외를 GraphQlPlatformRejection으로 만들고 GRAPHQL_CURSOR_REJECTED·
  GRAPHQL_CONNECTION_REJECTED를 catalog에 더한다.
- STOMP 오류 처리기는 MessagingException 포장을 벗긴 실패 자신만 IAE로
  보고, 등록된 코드면 error-category·error-retryable header를 더한다(gRPC
  trailer와 같은 이름·값).
- broadcast 규칙(모든 tenant의 인증 사용자가 읽어도 되는 것만)을
  projector Javadoc·README·AGENTS에 적는다. 버린 안: destination을
  tenant별로 나누기(projector가 tenant를 모르고, simple broker는 R1
  증거라 범위 밖).
- maxInputListElements Javadoc을 실제 검사 범위로 좁힌다.

위험: client가 보는 GraphQL 코드와 STOMP header가 바뀐다.
docs/upgrade/2026-11-round9-authz.md 12~13행.

검증: desktop :adapter:inbound:graphql:check·systemTest,
:adapter:inbound:websocket:check·systemTest rc=0(묶음 전체 실행).

Refs: RR9-02-19, RR9-02-31, RR9-03-14, RR9-03-29
BREAKING CHANGE: GraphQL cursor·connection 거부 코드와 STOMP ERROR frame의
  error-code(묻힌 IAE)·새 header. docs/upgrade/2026-11-round9-authz.md 12~13행.
This commit is contained in:
DongHyeonka
2026-11-13 12:24:54 +09:00
parent 2f0aefadee
commit 01caee3c01
14 changed files with 205 additions and 33 deletions
+8 -3
View File
@@ -1,8 +1,9 @@
# 업그레이드 안내 — 2026-11 인증·인가와 GraphQL·WebSocket 계약
- 범위: 2026-11-12 전체 리뷰의 인증·인가 묶음을 고친 변경. JWT 역할·claim 대응, JWKS 재조회 실패의 분류, 배포
산출물의 profile 검사, 알림 callback, GraphQL 인가·tenant, 전송별 권한 판정이 바뀌었다.
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 RR9-02-02·16·17·18·20·23·25·28·29
- 범위: 2026-11-12 전체 리뷰의 인증·인가 묶음과 GraphQL·WebSocket 계약 묶음을 고친 변경. JWT 역할·claim 대응, JWKS 재조회 실패의 분류, 배포
산출물의 profile 검사, 알림 callback, GraphQL 인가·tenant·오류 코드, 전송별 권한 판정, STOMP 오류 frame이 바뀌었다.
- 근거: 2026-11-12 전체 리뷰(`docs/reviews/2026-11-12-round9-review/`)의 RR9-02-02·16·17·18·19·20·23·25·28·29·31,
RR9-03-14·29
## 1. 누가 읽나
@@ -24,8 +25,12 @@
| 9 | tenant를 제안하는 입력 이름을 web-advanced와 GraphQL이 같은 어휘로 거부한다(`tenant`, `tenant_id`, `tenantId`, `X-Tenant-Id`, 대소문자·`-`·`_` 무관) | 그런 이름의 header·parameter·argument를 쓰던 client를 고친다 | 403 `TENANT_INPUT_UNTRUSTED`나 GraphQL tenant 거부가 난다 | tenant 입력 검사를 쓰는 서비스 |
| 10 | `PATCH_PATH_FORBIDDEN`의 `details.refusedPaths`는 16개까지, `[A-Za-z0-9_.~/-]` 128자 이하 이름만 그대로 싣고 나머지는 `<not echoed>`다 | 그 칸을 화면에 그대로 보이던 client는 대체 문자열을 처리한다 | — | web-advanced patch |
| 11 | 알림 callback: 설정하지 않은 profile로 온 callback은 400이다(전에는 500과 ERROR 로그). `ProviderCallbackAdapterRegistry.require`가 `find`(`Optional`)로 바뀌었다 | registry를 직접 구현한 서비스는 `find`를 구현한다 | 컴파일이 실패한다 | 알림 platform |
| 12 | GraphQL cursor·connection 거부가 `GRAPHQL_CURSOR_REJECTED`·`GRAPHQL_CONNECTION_REJECTED` 요청 오류다(전에는 `INTERNAL_ERROR`와 ERROR 로그) | client가 그 코드로 분기하게 한다 | — | GraphQL pagination API를 쓰는 서비스 |
| 13 | STOMP ERROR frame: 다른 실패의 원인으로 묻힌 `IllegalArgumentException`은 `BAD_PARAMETER`가 아니라 `WEBSOCKET_REQUEST_REJECTED`다. 모든 ERROR frame에 `error-retryable` header가 붙고, 등록된 코드면 `error-category`도 붙는다 | client가 새 header를 읽게 한다 | — | STOMP client |
## 3. 바뀌지 않은 것
- web의 403 응답(`AUTHZ_INSUFFICIENT_PERMISSION`), 401 응답 모양, `WWW-Authenticate`는 그대로다.
- `@RequiresPermission`·역할 매핑 설정 키는 그대로다.
- STOMP broadcast는 여전히 destination 하나로 모든 인증된 세션에 간다. 그래서 `LiveEventProjector`는 모든 tenant의 인증된
사용자가 읽어도 되는 것만 싣는다(`src/adapter/inbound/websocket/README.md` 「한계」). 이 규칙을 이번에 문서로 적었다.