Files
clean-architecture-backend-…/src/adapter/inbound/websocket
DongHyeonka 5786126cfa fix!: 남은 리뷰 항목과 합친 뒤 드러난 결함을 고친다
문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에
fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도
HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가
있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox
Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission
controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입
등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음).

방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션·
멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와
PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는
MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단
제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에
정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는
infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다.

위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security
오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다.
템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에
있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다.

검증: ci, mainCheck, integrationCheck, -p optional-platforms ci
integrationCheck, performanceCheck, releaseCheck(-PgitRevision),
verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동:
local-fileserver, notification ingest·serving·handoff, local-redis,
all-adapters(smoke 3개 포함).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절
BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고,
app.security의 모르는 키는 기동을 거부한다. MessageHandler에
schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
2026-11-03 19:52:06 +09:00
..

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, /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인 이유: 거부 사유가 클라이언트가 아니라 지금 이 노드의 부하라서, 일반 클라이언트가 물러났다가(가능하면 다른 노드로) 다시 붙게 한다.
  • 처리 실패는 모두 빈 본문의 ERROR 프레임이 되고 message 헤더는 고정값 WEBSOCKET_REQUEST_REJECTED다. error-code 헤더는 원인 사슬에 ApiErrorCarrier가 있으면 그 코드, IllegalArgumentException이면 BAD_PARAMETER, 나머지는 WEBSOCKET_REQUEST_REJECTED다.
  • LiveEventProjector<T> bean이 정확히 하나 있는 @DomainEvent 타입만 broadcast한다. 도메인 객체를 그대로 직렬화하지 않고, projector가 만든 bounded Map<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의 "제거된 코드" 표에 있다.