# 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`. Organised by what you observe, because that is what you have during an incident. ## Clients report 1006 — "closed abnormally, no reason" 1006 is indistinguishable from a network failure and drives every client into its most aggressive reconnect path. - **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. ## Connections work locally and not behind the load balancer Three nginx directives, each producing a different failure: | 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. | `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. ## Connections vanish with no close frame and no error 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. ## Clients are closed with 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. ## Clients are closed with 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. ## 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. ## 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 ```