Skip to content

README.md

Latest commit

 

History

History
104 lines (91 loc) · 7.83 KB

README.md

File metadata and controls

104 lines (91 loc) · 7.83 KB
Raw

spring-websocket — WebSocket, SockJS, STOMP over WebSocket

Spring Framework 7.1.0-SNAPSHOT 기준 해설.

한 줄 정의

spring-websocket은 서버/클라이언트 양쪽에서 WebSocket 연결을 맺고(핸드셰이크), 그 위로 메시지를 주고받으며, 브라우저 호환을 위한 SockJS 폴백과 STOMP 서브프로토콜까지 얹는 모듈이다.

이 모듈이 푸는 문제

순수 Servlet/Jakarta WebSocket API만으로 실시간 양방향 통신을 구현하려면 핸드셰이크 검증, 서버별 업그레이드 차이, 동시 전송 동기화, 끊긴 연결 정리, 구형 브라우저/프록시 환경에서의 폴백, 그리고 "어디로 보낼지"를 정하는 메시징 라우팅까지 전부 직접 다뤄야 한다. 이 모듈은 이 문제들을 다음 네 층으로 나눠 해결한다.

  1. 저수준 WebSocket 추상화 — WebSocketHandler / WebSocketSession. 서버 구현(Tomcat, Jetty, ...)에 독립적인 메시지 핸들링 모델.
  2. 서버 핸드셰이크/업그레이드 — HTTP GET(또는 HTTP/2 CONNECT) 요청을 검증하고 서버별 RequestUpgradeStrategy로 실제 업그레이드를 위임. Spring MVC HandlerMapping에 자연스럽게 통합.
  3. SockJS 폴백 — WebSocket을 쓸 수 없는 환경에서 XHR streaming/polling, EventSource, HtmlFile 같은 HTTP 기반 전송으로 WebSocket "처럼" 보이게 에뮬레이션.
  4. STOMP 서브프로토콜 — WebSocket 프레임 위에 STOMP를 얹어 메시지를 spring-messaging의 채널/브로커로 라우팅. @EnableWebSocketMessageBroker 한 줄로 풀스택 메시징을 구성.

의존 관계

          ┌────────────────────────────────────────────────┐
          │                spring-websocket                 │
          └────────────────────────────────────────────────┘
   의존(사용) ▼                                    ▲ 의존받음
 ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
 │ spring-messaging │  │   spring-webmvc  │  │ (애플리케이션)    │
 │ (STOMP, 채널,    │  │ (HandlerMapping, │  │  @EnableWebSocket │
 │  브로커, 메시지) │  │  HttpRequest-    │  │  @EnableWebSocket │
 │                  │  │  Handler)        │  │  MessageBroker    │
 └──────────────────┘  └──────────────────┘  └──────────────────┘
 ┌──────────────────┐  ┌──────────────────┐
 │   spring-web     │  │   spring-core    │
 │ (ServerHttp-     │  │ (Lifecycle,      │
 │  Request/Resp,   │  │  TaskScheduler)  │
 │  CORS, URI)      │  │                  │
 └──────────────────┘  └──────────────────┘
          │
          ▼ 런타임 SPI
 Jakarta WebSocket API(jakarta.websocket) / Jetty WebSocket / (선택) Jackson
  • 사용하는 모듈: spring-messaging(STOMP 인코더/디코더, 메시지 채널, 브로커, 사용자 레지스트리), spring-web(ServerHttpRequest/Response, CORS, URI), spring-webmvc(HandlerMapping, HttpRequestHandler), spring-core(Lifecycle, TaskScheduler).
  • 런타임 SPI: Jakarta WebSocket API 2.1+ (기본 StandardWebSocketUpgradeStrategy), Jetty WebSocket(선택). JSON 직렬화는 Jackson(SockJS 메시지 코덱) 선택 의존.

하위 챕터 목차

  1. 01-websocket-핵심-api와-세션-모델.md — WebSocketHandler, WebSocketSession, 메시지 타입, 그리고 핸들러/세션 데코레이터.
  2. 02-서버-핸드셰이크와-업그레이드.md — HandshakeHandler, 인터셉터 체인, RequestUpgradeStrategy, MVC 통합.
  3. 03-sockjs-폴백-프로토콜.md — SockJsService, 전송 타입과 TransportHandler, 세션 관리.
  4. 04-stomp-over-websocket.md — SubProtocolWebSocketHandler, StompSubProtocolHandler, 메시징 브리지와 이벤트.
  5. 05-설정-DSL과-부트스트랩.md — @EnableWebSocket / @EnableWebSocketMessageBroker와 등록 DSL.
  6. 06-클라이언트.md — WebSocketClient, WebSocketConnectionManager, WebSocketStompClient, SockJsClient.

전체 패키지 구조 ASCII 맵

org.springframework.web.socket
│
├─ (root)                      WebSocketHandler, WebSocketSession, WebSocketMessage
│                              TextMessage/BinaryMessage/Ping/Pong, CloseStatus,
│                              WebSocketExtension, SubProtocolCapable, WebSocketHttpHeaders
│
├─ adapter                     서버 네이티브 세션 → WebSocketSession 어댑터
│  ├─ standard                 Jakarta WebSocket(JSR-356) 어댑터
│  └─ jetty                    Jetty 네이티브 어댑터
│
├─ handler                     WebSocketHandler 기반 헬퍼/데코레이터
│                              AbstractWebSocketHandler, Text/BinaryWebSocketHandler,
│                              Exception/Logging/Concurrent... Decorator,
│                              PerConnectionWebSocketHandler
│
├─ server                      서버 핸드셰이크 SPI
│  │                           HandshakeHandler, HandshakeInterceptor, RequestUpgradeStrategy
│  ├─ support                  AbstractHandshakeHandler, DefaultHandshakeHandler,
│  │                           WebSocketHttpRequestHandler, WebSocketHandlerMapping,
│  │                           Origin/HttpSession HandshakeInterceptor
│  ├─ standard                 StandardWebSocketUpgradeStrategy, ServerEndpointExporter
│  └─ jetty                    Jetty 업그레이드 전략
│
├─ client                      클라이언트 측 WebSocket 연결
│  │                           WebSocketClient, WebSocketConnectionManager
│  └─ standard                 StandardWebSocketClient (Jakarta)
│
├─ sockjs                      SockJS 폴백 프로토콜
│  │                           SockJsService, 예외 계층
│  ├─ frame                    SockJsFrame, SockJsMessageCodec(Jackson)
│  ├─ support                  AbstractSockJsService, SockJsHttpRequestHandler
│  ├─ transport                TransportType, TransportHandler, SockJsSession,
│  │  │                        TransportHandlingSockJsService
│  │  ├─ handler               DefaultSockJsService, Xhr/EventSource/HtmlFile/WebSocket
│  │  │                        TransportHandler 구현들
│  │  └─ session               SockJsSession 구현들(Polling/Streaming/WebSocketServer)
│  └─ client                   SockJsClient, Transport(WebSocket/Xhr) 클라이언트
│
├─ messaging                   STOMP over WebSocket + spring-messaging 브리지
│                              SubProtocolHandler, SubProtocolWebSocketHandler,
│                              StompSubProtocolHandler, WebSocketStompClient,
│                              Session*Event, DefaultSimpUserRegistry
│
└─ config.annotation           Java 설정 DSL
                               @EnableWebSocket / @EnableWebSocketMessageBroker,
                               WebSocketConfigurer / WebSocketMessageBrokerConfigurer,
                               *HandlerRegistry, StompEndpointRegistry, *Registration