문제(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」
adapter-inbound-websocket
모듈 규칙(허용 의존, 설정 키, 테스트 명령)은 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,/topicsimple broker,/appapplication 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절 ④). - 읽지 못한 payload(
-
그 밖의 예외는 예외와 함께 ERROR. 전에는 Spring이 예외 전체(persistence 실패의 SQL 원인 포함)를 ERROR로 남겼다. 필수 header·destination 변수가 없을 때의
MessageHandlingException도 ERROR다. 메시지에 입력값이 없고, Spring이 같은 타입으로 서버 실패도 감싸서 타입만으로는 클라이언트 탓을 가를 수 없다(결정 색인 기본값 2026-11-07). -
LiveEventProjector<T>bean이 정확히 하나 있는@DomainEvent타입만 broadcast한다. 도메인 객체를 그대로 직렬화하지 않고, projector가 만든 boundedMap<String, String>만 보낸다.
추가할 한 줄
// 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<WebSocketConnectionId, String, Optional<String>>에 넘기고, 응답을 연결별 큐로 보낸다. 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 없이 따로 쓸 수 있다 |
동작:
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
조립 예:
@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<String>: 응답 또는 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:
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의 "제거된 코드" 표에 있다.