문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지 크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의 500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본 (TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR 테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로 만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져 객체 저장소 lane이 돌지 않았다. 방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은 결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD, S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한). MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자· mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고, scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과 왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와 결정은 리뷰 README 14절에 있다. 위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서 H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC· WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체, 샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개 (composition:durable-operation, adapter:inbound:messaging)와 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면 실패한다(runbook에 확인 쿼리). 검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함 전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절 BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션 기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가, 샘플 Idempotency-Key 오류 코드 변경.
11 KiB
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인 이유: 거부 사유가 클라이언트가 아니라 지금 이 노드의 부하라서, 일반 클라이언트가 물러났다가(가능하면 다른 노드로) 다시 붙게 한다. - 처리 실패는 모두 빈 본문의 ERROR 프레임이 되고
message헤더는 고정값WEBSOCKET_REQUEST_REJECTED다.error-code헤더는 원인 사슬에ApiErrorCarrier가 있으면 그 코드,IllegalArgumentException이면BAD_PARAMETER, 나머지는WEBSOCKET_REQUEST_REJECTED다. 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의 "제거된 코드" 표에 있다.