문제: docs/websocket/runbook.md가 영어였다(language 예외). 고친 방법: 뜻을 그대로 옮기고 식별자·명령·close code·nginx 지시어·표 구조는 원문으로 둔다. 적힌 클래스·lane(`TomcatWebSocketShutdownIT`, `websocketNginxTest`, `websocketJettyTest`, `nginx-no-upgrade.conf` 등)은 모두 지금 있다. 위험·한계: 내용 감사는 하지 않았다. 검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/websocket을 읽는 테스트는 없다(`grep -rn 'docs/websocket' src --include=*.java` 결과 0).
5.0 KiB
WebSocket handler runbook
범위: 내보내는 조립은 WebSocket 런타임을 조립하지 않는다. 이 runbook은
PlatformWebSocketHandler를 스스로 등록한 서비스에 적용한다(src/adapter/inbound/websocket/README.md「라이브러리 API」). STOMP channel의 규칙은 leafCLAUDE.md에 있다.
무엇을 보았는지로 나눴다. 장애 중에 손에 있는 것이 그것이기 때문이다.
client가 1006을 보고한다 — 「비정상 종료, 이유 없음」
1006은 네트워크 장애와 구분할 수 없고, 모든 client를 가장 공격적인 재연결 경로로 몰아넣는다.
- 배포 중 — handler가 connection을 닫지 않았다. handler는
SmartLifecycle.stop()에서 1001 going away로 닫는다. container 자체의 graceful 종료는 닫지 않는다. 진행 중인 요청을 기다리는데, 맺어진 WebSocket은 요청이 아니기 때문이다. handler가 Spring bean인지 확인한다(아니면 Spring이stop()을 부르지 않는다).TomcatWebSocketShutdownIT가 순서를 보여 준다. handler의 phase가 web 서버보다 낮으면 client는 1006을 본다. - proxy 뒤 — upgrade를 잘못 다뤄서 close frame이 close frame이 되지 못한다. 다음 절을 본다.
- 둘 다 아님 — 닫는 중에 무언가 예외를 던졌다. 123바이트보다 긴 close 이유는 container가 닫는 도중에 예외를 던지게 한다. 그래서 handler가 이유를 자른다.
로컬에서는 되는데 load balancer 뒤에서는 안 된다
nginx 지시어 셋이고, 각각 다른 실패를 낸다.
| 빠진 것 | 증상 |
|---|---|
proxy_http_version 1.1 |
handshake가 400으로 답하거나 그냥 upgrade되지 않는다. HTTP/1.0에는 Upgrade 방식이 없다. |
Upgrade / Connection 전달 |
upstream이 보통 GET을 보고, 직접 시험하면 되는 route에 404나 200으로 답한다. hop-by-hop 헤더라서 proxy는 이것을 반드시 버린다. |
proxy_read_timeout 올리기 |
60초보다 조용한 connection은 close frame 없이 모두 죽는다. WebSocket은 원래 놀고 있다. |
websocketNginxTest가 실제 Nginx에 대해 이것을 단언하고, 일부러 망가뜨린 설정(nginx-no-upgrade.conf)을 지녀서 자기
단언이 실패할 수 있음을 증명한다.
close frame도 오류도 없이 connection이 사라진다
거의 늘 애플리케이션이 아니라 중간 장비의 idle timeout이다. TCP는 떠난 상대를 알려 주지 않는다. 닫힌 노트북 덮개,
셀룰러로 넘어가는 휴대폰, mapping을 잊은 NAT 모두 FIN을 만들지 않는다. handler에는 heartbeat나 idle timer가 없다.
container idle timeout(ServletServerContainerFactoryBean.setMaxSessionIdleTimeout)과 proxy read timeout을 정하고,
client가 그중 가장 작은 것보다 짧게 ping하게 한다.
client가 1009로 닫힌다
메시지가 상한을 넘었다. 상한을 강제하는 곳은 둘이다. container의 text buffer(Tomcat 기본 8 KiB)는 handler가 메시지를
보기 전에 닫고, handler는 메시지가 WebSocketConnectionBudget.maxMessageBytes(UTF-8 바이트)를 넘으면 닫는다. container
buffer를 같은 값으로 둬서 답이 어느 쪽이 먼저 걸렸는지에 달리지 않게 한다.
client가 1013으로 닫힌다
답을 큐에 넣지 못했다. connection의 송신 버퍼(maxBufferedOutboundBytes)나 노드 전체의 GlobalBufferBudget이 가득
찼다. 상대가 서비스가 답하는 것보다 느리게 읽는다는 뜻이다. 닫는 것은 일부러다. 다시 연결하는 client는 잃은 것이 없고,
조용히 답을 놓친 client는 틀렸는데 그것을 모른다.
메모리가 늘고 아무것도 실패하지 않는다
느린 소비자다. 오류를 내지 않는다. 서버가 쓰는 것보다 느리게 읽고 그 차이가 쌓인다. 재현에 도구가 필요 없다. 느리게 읽기만 하면 된다.
- 상한: connection마다(
maxBufferedOutboundBytes) 그리고 노드 전체(GlobalBufferBudget). 둘째는 쓸데없지 않다. connection마다 1메가바이트는 connection 백 개에서는 괜찮고 오만 개에서는 heap 전체다. - 버림:
OutboundQueue.snapshot().droppedCount()가 큐가 버린 droppable·conflatable 메시지를 센다. 데이터를 버리는 동안에도 connection 수와 버퍼 바이트는 멀쩡해 보인다. 그렇다고 말해 주는 숫자는 버린 수뿐이다. - 버린 수가 0인데도 메모리가 늘면: 큐 lock과 socket lock이 따로인지 본다. 하나였을 때는 멈춘 상대가 모든 생산자를 막아서 큐가 차지 않았고, 버리는 상한도 걸리지 않았다.
확인
cd src
./gradlew :adapter:inbound:websocket:test # 큐, writer, 예산, handler
./gradlew :adapter:inbound:websocket:systemTest # 실제 Tomcat, context 닫기 → 1001 포함
./gradlew :adapter:inbound:websocket:websocketJettyTest # 두 번째 servlet container
./gradlew :adapter:inbound:websocket:websocketNginxTest # 실제 Nginx. Docker가 필요하고 없으면 실패한다