docs(websocket): WebSocket runbook을 한국어로 옮긴다

문제: 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).
This commit is contained in:
DongHyeonka
2026-11-07 17:29:57 +09:00
parent 4e2f08a687
commit 7c2cfa0601
2 changed files with 48 additions and 59 deletions
+48 -58
View File
@@ -1,83 +1,73 @@
# WebSocket handler runbook
> **Scope:** the shipped compositions do not assemble a WebSocket runtime. This runbook applies to
> a service that registered `PlatformWebSocketHandler` itself (see
> `src/adapter/inbound/websocket/README.md`, "라이브러리 API"). The STOMP channel's rules are in the
> leaf `CLAUDE.md`.
> **범위:** 내보내는 조립은 WebSocket 런타임을 조립하지 않는다. 이 runbook은 `PlatformWebSocketHandler`를 스스로 등록한
> 서비스에 적용한다(`src/adapter/inbound/websocket/README.md` 「라이브러리 API」). STOMP channel의 규칙은 leaf
> `CLAUDE.md`에 있다.
Organised by what you observe, because that is what you have during an incident.
무엇을 보았는지로 나눴다. 장애 중에 손에 있는 것이 그것이기 때문이다.
## Clients report 1006 — "closed abnormally, no reason"
## client가 1006을 보고한다 — 「비정상 종료, 이유 없음」
1006 is indistinguishable from a network failure and drives every client into its most aggressive
reconnect path.
1006은 네트워크 장애와 구분할 수 없고, 모든 client를 가장 공격적인 재연결 경로로 몰아넣는다.
- **During a deploy** — the handler did not close its connections. It closes them with
**1001 going away** from `SmartLifecycle.stop()`; a container's own graceful shutdown does not,
because it waits for in-flight *requests* and an established WebSocket is not a request. Check
the handler is a Spring bean (otherwise Spring never calls `stop()`). `TomcatWebSocketShutdownIT`
shows the order: with the handler's phase below the web server's, the client sees 1006.
- **Behind a proxy** — the upgrade is mishandled, so the close frame never becomes a close frame.
See the next section.
- **Neither** — something threw while closing. A close reason longer than 123 bytes makes the
container throw mid-close; the handler truncates for that reason.
- **배포 중** — 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가 이유를 자른다.
## Connections work locally and not behind the load balancer
## 로컬에서는 되는데 load balancer 뒤에서는 안 된다
Three nginx directives, each producing a different failure:
nginx 지시어 셋이고, 각각 다른 실패를 낸다.
| Missing | Symptom |
| 빠진 것 | 증상 |
| --- | --- |
| `proxy_http_version 1.1` | Handshake answered 400, or simply not upgraded. HTTP/1.0 has no Upgrade mechanism. |
| `Upgrade` / `Connection` forwarded | Upstream sees an ordinary GET and answers 404 or 200 for a route that works when tested directly. They are hop-by-hop headers, so a proxy is *required* to drop them. |
| `proxy_read_timeout` raised | Every connection quieter than 60s is killed with no close frame. A WebSocket is idle by nature. |
| `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` asserts these against a real Nginx, and carries a deliberately broken
configuration (`nginx-no-upgrade.conf`) so it proves its own assertions can fail.
`websocketNginxTest`가 실제 Nginx에 대해 이것을 단언하고, 일부러 망가뜨린 설정(`nginx-no-upgrade.conf`)을 지녀서 자기
단언이 실패할 수 있음을 증명한다.
## Connections vanish with no close frame and no error
## close frame도 오류도 없이 connection이 사라진다
Almost always an intermediary's idle timeout, not the application. TCP does not report a departed
peer — a closed laptop lid, a phone switching to cellular and a NAT forgetting its mapping all
produce no FIN. The handler has no heartbeat or idle timer; set the container idle timeout
(`ServletServerContainerFactoryBean.setMaxSessionIdleTimeout`) and the proxy read timeout, and have
clients ping below the smallest of them.
거의 늘 애플리케이션이 아니라 중간 장비의 idle timeout이다. TCP는 떠난 상대를 알려 주지 않는다. 닫힌 노트북 덮개,
셀룰러로 넘어가는 휴대폰, mapping을 잊은 NAT 모두 FIN을 만들지 않는다. handler에는 heartbeat나 idle timer가 없다.
container idle timeout(`ServletServerContainerFactoryBean.setMaxSessionIdleTimeout`)과 proxy read timeout을 정하고,
client가 그중 가장 작은 것보다 짧게 ping하게 한다.
## Clients are closed with 1009
## client가 1009로 닫힌다
The message exceeded a bound. Two places enforce one: the container's text buffer (Tomcat default
8 KiB) closes before the handler sees the message, and the handler closes when the message exceeds
`WebSocketConnectionBudget.maxMessageBytes` (UTF-8 bytes). Set the container buffer to the same
value so the answer does not depend on which one fired first.
메시지가 상한을 넘었다. 상한을 강제하는 곳은 둘이다. container의 text buffer(Tomcat 기본 8 KiB)는 handler가 메시지를
보기 전에 닫고, handler는 메시지가 `WebSocketConnectionBudget.maxMessageBytes`(UTF-8 바이트)를 넘으면 닫는다. container
buffer를 같은 값으로 둬서 답이 어느 쪽이 먼저 걸렸는지에 달리지 않게 한다.
## Clients are closed with 1013
## client가 1013으로 닫힌다
A reply could not be queued: the connection's outbound buffer (`maxBufferedOutboundBytes`) or the
node-wide `GlobalBufferBudget` is full, which means the peer reads more slowly than the service
answers. Closing is deliberate — a client that reconnects has lost nothing, while one that silently
missed a reply is wrong and does not know it.
답을 큐에 넣지 못했다. connection의 송신 버퍼(`maxBufferedOutboundBytes`)나 노드 전체의 `GlobalBufferBudget`이 가득
찼다. 상대가 서비스가 답하는 것보다 느리게 읽는다는 뜻이다. 닫는 것은 일부러다. 다시 연결하는 client는 잃은 것이 없고,
조용히 답을 놓친 client는 틀렸는데 그것을 모른다.
## Memory grows and nothing is failing
## 메모리가 늘고 아무것도 실패하지 않는다
A slow consumer. It does not error — it reads more slowly than the server writes and the difference
accumulates. Arranging it requires no tooling: reading slowly is enough.
느린 소비자다. 오류를 내지 않는다. 서버가 쓰는 것보다 느리게 읽고 그 차이가 쌓인다. 재현에 도구가 필요 없다. 느리게
읽기만 하면 된다.
- **Bounds:** per connection (`maxBufferedOutboundBytes`) *and* node-wide (`GlobalBufferBudget`).
The second is not redundant — a megabyte each is fine at a hundred connections and is the whole
heap at fifty thousand.
- **Drops:** `OutboundQueue.snapshot().droppedCount()` counts droppable and conflatable messages
the queue shed. Connection counts and buffered bytes look healthy while data is being shed; the
drop count is the only number that says so.
- **If drops are zero and memory still grows:** check that the queue lock and the socket lock are
separate. When they were one lock, a stalled peer blocked every producer, the queue never filled,
and the shedding bound never fired.
- **상한:** connection마다(`maxBufferedOutboundBytes`) *그리고* 노드 전체(`GlobalBufferBudget`). 둘째는 쓸데없지 않다.
connection마다 1메가바이트는 connection 백 개에서는 괜찮고 오만 개에서는 heap 전체다.
- **버림:** `OutboundQueue.snapshot().droppedCount()`가 큐가 버린 droppable·conflatable 메시지를 센다. 데이터를 버리는
동안에도 connection 수와 버퍼 바이트는 멀쩡해 보인다. 그렇다고 말해 주는 숫자는 버린 수뿐이다.
- **버린 수가 0인데도 메모리가 늘면:** 큐 lock과 socket lock이 따로인지 본다. 하나였을 때는 멈춘 상대가 모든 생산자를
막아서 큐가 차지 않았고, 버리는 상한도 걸리지 않았다.
## Verification
## 확인
```bash
cd src
./gradlew :adapter:inbound:websocket:test # queue, writer, budget, handler
./gradlew :adapter:inbound:websocket:systemTest # real Tomcat, incl. context close → 1001
./gradlew :adapter:inbound:websocket:websocketJettyTest # second servlet container
./gradlew :adapter:inbound:websocket:websocketNginxTest # real Nginx; needs Docker, fails without it
./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가 필요하고 없으면 실패한다
```
-1
View File
@@ -103,7 +103,6 @@ language docs/runbooks/startup-required-adapter-disabled.md
language docs/runbooks/startup-validation-failed.md
language docs/runbooks/template.md
language docs/storage-capability-boundary.md
language docs/websocket/runbook.md
language src/adapter/inbound/messaging/CLAUDE.md
language src/adapter/inbound/web-advanced/CLAUDE.md
language src/adapter/inbound/web/CLAUDE.md