How do you expose a reactive WebSocketHandler at a URL in Spring WebFlux — what beans (SimpleUrlHandlerMapping, WebSocketHandlerAdapter, HandshakeWebSocketService) are involved and what does each do?

## The request flow in WebFlux Every request in WebFlux enters `DispatcherHandler`, which holds ordered lists of: - **`HandlerMapping`** beans — map a request to a *handler object*. - **`HandlerAdapter`** beans — know how to *invoke* a given handler type. - **`HandlerResultHandler`** beans — process the result. For annotated controllers this is `RequestMappingHandlerMapping` + `RequestMappingHandlerAdapter`. For raw WebSockets you plug in the WebSocket equivalents. ## Bean 1 — SimpleUrlHandlerMapping (the routing) `SimpleUrlHandlerMapping` maps **URL path patterns → handler objects**. For WebSockets the handler objects are your `WebSocketHandler` instances: ```java @Bean public HandlerMapping webSocketMapping(EchoHandler echo, ChatHandler chat) { Map<String, WebSocketHandler> map = new LinkedHashMap<>(); map.put("/ws/echo", echo); map.put("/ws/chat", chat); SimpleUrlHandlerMapping mapping = new SimpleUrlHandlerMapping(); mapping.setUrlMap(map); mapping.setOrder(-1); // IMPORTANT: before annotated-controller mapping return mapping; } ``` **Order matters.** `RequestMappingHandlerMapping` has order 0 by default. If your `SimpleUrlHandlerMapping` has a higher (later) order, an unrelated controller mapping might match first or a not-found could short-circuit. Setting `order` to a negative value (e.g. `-1` or `Ordered.HIGHEST_PRECEDENCE`-ish) ensures the WebSocket path is resolved first. ## Bean 2 — WebSocketHandlerAdapter (the invocation) `WebSocketHandlerAdapter` is the `HandlerAdapter` that `supports(...)` a `WebSocketHandler`. When `DispatcherHandler` finds that the mapped handler is a `WebSocketHandler`, this adapter is selected. It delegates to a `WebSocketService`: ```java @Bean public WebSocketHandlerAdapter handlerAdapter() { return new WebSocketHandlerAdapter(); // default WebSocketService = new HandshakeWebSocketService() } ``` The no-arg constructor internally creates a `HandshakeWebSocketService`. You can pass a custom one: `new WebSocketHandlerAdapter(myWebSocketService)`. ## Bean 3 (implicit) — HandshakeWebSocketService (the upgrade) `HandshakeWebSocketService` implements `WebSocketService`. Its `handleRequest(exchange, handler)`: 1. **Validates the handshake**: the request must be a GET with `Upgrade: websocket` and `Connection: upgrade`, a valid `Sec-WebSocket-Version` (13), and `Sec-WebSocket-Key`. Invalid requests get 400/405/etc. 2. **Negotiates sub-protocol** if the handler declares `getSubProtocols()`. 3. **Delegates the actual upgrade** to a `RequestUpgradeStrategy` chosen for the running server — `ReactorNettyRequestUpgradeStrategy`, `TomcatRequestUpgradeStrategy`, `JettyRequestUpgradeStrategy`, `UndertowRequestUpgradeStrategy`. By default it detects the server from the classpath (`ServerLoader`). 4. On success, builds the `WebSocketSession` and calls `handler.handle(session)`, subscribing to the returned `Mono<Void>`. You usually don't declare `HandshakeWebSocketService` explicitly — it comes free with the default adapter — but you would if you need to configure a specific `RequestUpgradeStrategy`, custom `sessionAttributePredicate`, or handshake limits (e.g., max frame size on Reactor Netty via the strategy). ## Full minimal config ```java @Configuration public class WsConfig { @Bean HandlerMapping wsMapping(EchoHandler echo) { SimpleUrlHandlerMapping m = new SimpleUrlHandlerMapping(); m.setUrlMap(Map.of("/ws/echo", echo)); m.setOrder(-1); return m; } @Bean WebSocketHandlerAdapter wsAdapter() { return new WebSocketHandlerAdapter(); } } ``` That plus the `EchoHandler` bean is a complete, working reactive WebSocket endpoint. ## Gotchas - **Forgetting the WebSocketHandlerAdapter bean** → the mapping resolves the handler but `DispatcherHandler` finds no adapter that supports `WebSocketHandler`, yielding an error/500. Both beans are required. - **Order not set** → intermittent 404s or the path handled by the wrong mapping. - **This is NOT `@EnableWebSocket`/`WebSocketConfigurer`** — that is the Servlet stack. WebFlux uses these beans directly; there is no annotation-based enable for raw reactive WebSockets. - **Path matching** uses `PathPattern` matching in WebFlux (not AntPathMatcher), so patterns like `/ws/{room}` work and path variables are available via `session.getHandshakeInfo()`/exchange attributes. - **CORS / auth** happen before the upgrade at the Spring Security boundary (different leaf) — the handshake is an ordinary HTTP GET first.