# adapter-inbound-websocket 모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 [CLAUDE.md](CLAUDE.md)가 SSOT다. 이 문서는 무엇을 제공하는지, 어떻게 붙이는지, 왜 이런 모양인지를 적는다. 이 leaf는 두 가지를 제공한다. 서로 참조하지 않는다. | | 무엇 | 켜는 방법 | | --- | --- | --- | | STOMP 채널 (`stomp/`) | STOMP-over-SockJS 서버 push. 설정 키 `app.websocket.*` | `runtimeOnly` 한 줄. servlet 앱에 모듈이 있으면 켜진다 | | 라이브러리 API (`servlet/`, `outbound/`, `budget/`) | raw WebSocket 요청/응답 handler와 bounded 송신 큐 | 서비스의 어댑터 leaf가 직접 `new` 해서 등록. 설정 키 없음 | 두 경로 모두 기본 bootJar(`app-bootstrap`)에는 들어 있지 않다. ## STOMP 채널 ### 제공하는 것 - `/ws`(설정 가능) SockJS endpoint, `/topic` simple broker, `/app` application prefix. - HTTP 계층이 이미 인증한 `Principal`이 있어야 handshake가 통과한다. 이 leaf는 자격 증명을 직접 해석하지 않는다. - SUBSCRIBE는 설정된 broadcast destination 하나만, SEND는 `/app/**`만 허용한다. 클라이언트가 `/topic/**`으로 직접 보내는 것은 거부한다. - 세션 하나에 구독은 하나다. 같은 세션의 두 번째 SUBSCRIBE는 id가 달라도 ERROR 프레임으로 거부한다(UNSUBSCRIBE·DISCONNECT로 풀린다). simple broker는 subscription id마다 한 번씩 보내므로, 막지 않으면 한 클라이언트가 같은 destination을 N번 구독해 broadcast 한 건을 N번 받고 broker 큐를 N배로 차지한다. 이 채널에는 구독할 destination이 하나뿐이라 정상 클라이언트에는 비용이 없다. - 노드 연결 상한(`APP_WEBSOCKET_MAX_CONNECTIONS`). 상한을 넘는 연결은 STOMP handler에 닿기 전에 1013(Try Again Later)으로 닫는다. handshake에서 503으로 거부하지 않은 이유: 자리를 돌려주는 것은 세션 종료 콜백뿐이고, 통과한 SockJS handshake가 세션이 되지 않을 수도 있어 두 곳에서 세면 자리가 샌다. 1008이 아니라 1013인 이유: 거부 사유가 클라이언트가 아니라 지금 이 노드의 부하라서, 일반 클라이언트가 물러났다가(가능하면 다른 노드로) 다시 붙게 한다. - handler 메서드가 돌기 전의 처리 실패(inbound interceptor의 거부 등)는 빈 본문의 ERROR 프레임이 되고 `message` 헤더는 고정값 `WEBSOCKET_REQUEST_REJECTED`다. `error-code` 헤더는 원인 사슬에 `ApiErrorCarrier`가 있으면 첫 carrier의 코드(`IllegalArgumentException` 뒤에 있어도), `IllegalArgumentException`이면 `BAD_PARAMETER`, 나머지는 `WEBSOCKET_REQUEST_REJECTED`다. - `@MessageMapping` 메서드의 실패는 inbound 채널 executor에서 끝나서 프레임이 나가지 않는다. 서버 로그는 `StompHandlerFailureLog`가 web·GraphQL·gRPC와 같은 줄로 남긴다(`ServerFailureLog`): persistence 실패는 분류만, 5xx carrier는 예외와 함께, 4xx carrier는 남기지 않는다. 다른 예외로 감싼 carrier도 원인 사슬의 첫 carrier로 같은 줄을 남긴다(재리뷰 RR7-01-05). `IllegalArgumentException`은 `BAD_PARAMETER`로 보고 WARN 한 줄(`request refused as BAD_PARAMETER by <예외 타입>`)만 남긴다. 메시지는 입력값이 들 수 있어 남기지 않는다. - handler가 돌기 전에 Spring이 클라이언트 메시지를 거부한 실패도 같은 모양 WARN 한 줄로 남긴다. 코드는 web이 같은 실패에 답하는 코드다(재리뷰 RR7-01-06): - 읽지 못한 payload(`MessageConversionException`, 받은 메시지가 실린 것): `VALIDATION_FAILED` - 비었거나 검증에 걸린 payload(`MethodArgumentNotValidException`): `VALIDATION_FAILED` - `@DestinationVariable`·`@Header` 값이 파라미터 타입으로 바뀌지 않음(`ConversionFailedException`): `BAD_PARAMETER` 이 예외들의 메시지는 받은 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). - `LiveEventProjector` bean이 정확히 하나 있는 `@DomainEvent` 타입만 broadcast한다. 도메인 객체를 그대로 직렬화하지 않고, projector가 만든 bounded `Map`만 보낸다. ### 추가할 한 줄 ```groovy // app-bootstrap/build.gradle runtimeOnly project(':adapter:inbound:websocket') // WebSocket (STOMP push) ``` `WebSocketConfig`가 모듈 자신의 `AutoConfiguration.imports`에 있다. servlet 앱에 모듈이 있으면 켜지고, `APP_WEBSOCKET_ENABLED=false`로만 끈다. 이 줄을 지우면 endpoint, broker, 설정 바인딩이 모두 함께 빠진다. 기본 조립에는 없다. ### env 키 | env | 기본값 | 뜻 | | --- | --- | --- | | `APP_WEBSOCKET_ENABLED` | `true` | `false`면 STOMP 채널을 끈다 | | `APP_WEBSOCKET_ENDPOINT` | `/ws` | handshake 경로 | | `APP_WEBSOCKET_ALLOWED_ORIGINS` | `http://localhost:3000` | 쉼표 구분 origin 목록. wildcard 금지 | | `APP_WEBSOCKET_BROADCAST_DESTINATION` | `/topic/events` | 서버 push 대상. `/topic/` 아래 경로 하나 | | `APP_WEBSOCKET_CHANNEL_QUEUE_CAPACITY` | `10000` | STOMP 인바운드·아웃바운드 채널 executor 큐 상한. 가득 차면 메시지를 거부한다(스레드 수는 CPU×2 고정) | | `APP_WEBSOCKET_MESSAGE_SIZE_LIMIT` | `64KB` | 수신 STOMP 메시지 상한. 넘으면 세션을 닫는다 | | `APP_WEBSOCKET_SEND_BUFFER_SIZE_LIMIT` | `512KB` | 세션 하나의 미전송 버퍼 상한. 넘으면 느린 소비자로 보고 닫는다 | | `APP_WEBSOCKET_SEND_TIME_LIMIT` | `10s` | 송신 한 번이 막혀 있을 수 있는 시간. 넘으면 닫는다 | | `APP_WEBSOCKET_TIME_TO_FIRST_MESSAGE` | `60s` | 새 세션이 첫 프레임을 보내기까지 기다리는 시간 | | `APP_WEBSOCKET_MAX_CONNECTIONS` | `1000` | 노드 하나가 동시에 여는 STOMP 세션 수. 다음 연결은 1013으로 닫는다 | 전송 한도 네 개의 기본값은 Spring 기본값(`WebSocketTransportRegistration`) 그대로다. 예전에도 이 값으로 돌았지만 코드에 없었다. 키로 꺼내 지금 어떤 상한이 걸려 있는지 보이게 하고, 라이브러리 업그레이드가 기본값을 바꿔도 조용히 따라가지 않게 했다. 연결 상한 기본값 1000은 1000 × 512 KiB(send buffer) ≈ 512 MiB를 최악의 송신 버퍼로 잡은 값이다. 노드 heap에 맞춰 조정한다. 켠 상태에서 값이 잘못되면(wildcard origin, 정규화되지 않은 경로) 기동이 실패한다. ### 한계 simple broker는 한 프로세스 안의 best-effort 전달이다. 영속·트랜잭션 연동·재전송·노드 간 전달이 없고, 발행이 트랜잭션 rollback보다 먼저 일어날 수 있다. 이런 전달이 필요하면 outbox/relay로 설계한다. - **principal별 연결 상한 없음.** 상한은 노드 단위다. 인증된 사용자 한 명(또는 탈취된 토큰)이 한 노드의 자리를 모두 차지할 수 있다. principal별 상한은 모든 노드가 공유하는 카운터(Redis 등)가 필요해 이 leaf 범위를 넘는다. 필요하면 서비스가 프록시나 공유 카운터로 막는다. - **연결 수명 동안 토큰을 다시 확인하지 않는다.** 인증은 handshake 한 번이다. 토큰이 만료되거나 폐기돼도 열린 연결은 유지된다. 연결 수명은 프록시 read timeout이나 서비스의 세션 정책으로 끊는다. ## 라이브러리 API — 서비스의 어댑터 leaf에서 직접 조립 설정 키도 자동 설정도 없다. 서비스의 어댑터 leaf가 `implementation project(':adapter:inbound:websocket')`로 받아 아래 타입을 직접 만든다(AGENTS.md capability 규칙의 라이브러리형 예외). | 진입점 | 역할 | | --- | --- | | `servlet.PlatformWebSocketHandler(budget, globalBudget, maxConnections, application)` | 텍스트 메시지 하나를 받아 `BiFunction>`에 넘기고, 응답을 연결별 큐로 보낸다. `maxConnections`(필수)를 넘는 연결은 1013으로 닫는다. `SmartLifecycle`이라 context 종료 시 열린 연결을 1001로 닫고, `stop()` 뒤 들어온 연결도 즉시 1001로 닫는다 | | `budget.WebSocketConnectionBudget(maxMessageBytes, maxBufferedOutboundBytes)` | 연결 하나의 수신 메시지 상한(UTF-8 바이트)과 미전송 버퍼 상한 | | `outbound.GlobalBufferBudget(maxBufferedBytes)` | 노드 전체 미전송 바이트 상한. 모든 연결이 공유한다 | | `outbound.OutboundQueue`, `outbound.SerializedOutboundWriter` | 우선순위·conflation·drop 정책을 가진 bounded 큐와 연결당 단일 writer. handler 없이 따로 쓸 수 있다 | 동작: ```text client ──connect──> PlatformWebSocketHandler.afterConnectionEstablished ├─ stop() 뒤 → close 1001 └─ maxConnections 도달 → close 1013 client ──text──> container(whole message) ──> PlatformWebSocketHandler ├─ > maxMessageBytes → close 1009 └─ application.apply(id, text) └─ reply → OutboundQueue → SerializedOutboundWriter → socket └─ 큐가 가득 참(GUARANTEED) → close 1013 context close ──> PlatformWebSocketHandler.stop() ──> 열린 연결 모두 close 1001 ──> web server graceful shutdown ``` 조립 예: ```java @Configuration @EnableWebSocket class LiveSocketConfig implements WebSocketConfigurer { private final LiveCommandUseCase useCase; // 서비스의 application 포트 LiveSocketConfig(LiveCommandUseCase useCase) { this.useCase = useCase; } @Bean // bean이어야 SmartLifecycle로 종료 순서에 들어간다 PlatformWebSocketHandler platformWebSocketHandler() { return new PlatformWebSocketHandler( new WebSocketConnectionBudget(64 * 1024, 1024 * 1024), new GlobalBufferBudget(64L * 1024 * 1024), 1_000, // 노드 연결 상한. 넘는 연결은 1013 (connection, text) -> useCase.handle(text)); // Optional: 응답 또는 empty } @Override public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { registry .addHandler(platformWebSocketHandler(), "/ws/v1/live") .setAllowedOrigins("https://app.example.com"); } @Bean // 컨테이너가 메시지를 버퍼에 모으므로 수신 상한과 idle timeout은 여기서 정한다 ServletServerContainerFactoryBean webSocketContainer() { ServletServerContainerFactoryBean container = new ServletServerContainerFactoryBean(); container.setMaxTextMessageBufferSize(64 * 1024); container.setMaxSessionIdleTimeout(90_000L); return container; } } ``` 서비스가 챙길 것: - **인증**: handler는 인증하지 않는다. upgrade 경로를 Spring Security 같은 HTTP 계층에서 막는다. - **origin**: `setAllowedOrigins`에 정확한 origin만 쓴다. WebSocket handshake는 same-origin 정책과 preflight의 보호를 받지 않는다. - **수신 크기**: servlet API는 애플리케이션에 frame을 보여주지 않는다. 컨테이너가 메시지를 자기 버퍼(Tomcat 기본 8 KiB)에 모으고, 그보다 크면 컨테이너가 1009로 닫는다. 컨테이너 버퍼를 `maxMessageBytes`와 같게 두면 두 상한이 일치한다. - **연결 수 상한(필수)**: 생성자의 `maxConnections`. 1013(Try Again Later)으로 닫는 이유는 거부 사유가 노드 부하라서 클라이언트가 물러났다 다시 붙게 하기 위해서다. upgrade 전에 503으로 막고 싶으면 서비스의 `HandshakeInterceptor`에서 따로 한다. principal별 상한은 없다(공유 카운터 필요). - **idle timeout·연결 수명**: handler에는 없다. 컨테이너(`setMaxSessionIdleTimeout`)와 프록시의 read timeout으로 정한다. - **서버 주도 push 없음**: handler는 받은 메시지에 대한 응답만 보낸다. 임의 시점 push가 필요하면 STOMP 채널을 쓴다. 검증하는 lane: ```bash cd src ./gradlew :adapter:inbound:websocket:test # 큐·writer·budget·handler 단위 ./gradlew :adapter:inbound:websocket:systemTest # Tomcat 실제 소켓: echo·1009·순서·abuse·종료 1001 ./gradlew :adapter:inbound:websocket:websocketJettyTest # 같은 계약을 Jetty에서 ./gradlew :adapter:inbound:websocket:websocketNginxTest # 실제 Nginx 뒤에서. Docker 필요, 없으면 실패 ``` ## 제거한 것 2026-09-25에 어느 Spring 설정에서도 닿지 않던 플랫폼 코드(`advanced/**`, handshake·session· protocol catalog·codec·ordering·lifecycle·observability·admin·security·webflux 등)와 `app.websocket.platform.*`·`app.websocket.advanced.sockjs.enabled` 설정 키를 지웠다. 목록과 복구 커밋은 `docs/capability-status.md`의 "제거된 코드" 표에 있다.