public interface WebSocket

What an application implements to serve a websocket route.

One instance per ROUTE, not per connection – the same shape a @RestController has. Everything that belongs to one client lives on the WebSocketSession handed to each callback, so an endpoint can be stateless and a stateful one puts its state in WebSocketSession.setAttachment.

`@WebSocketMapping("/echo")`
public class Echo implements WebSocket {
public void onOpen(WebSocketSession session) { }
public void onText(WebSocketSession session, String message) throws Exception {
session.sendText(message);
}
public void onBinary(WebSocketSession session, byte\[\] message, int offset, int length)
throws Exception {
session.sendBinary(message, offset, length);
}
}

The build finds that and registers it. A server assembled by hand gets the same thing through a callback rather than a setter – see Backend.WebSocketEndpoints – because this runtime is asked for its configuration while it starts and never reconfigured once it is running.

Threading is the part worth reading twice. A callback runs on the thread that owns the connection – a virtual thread where the server has them, a pool worker otherwise – and the server reads nothing more from that connection until the callback returns. So an endpoint may block, and a slow endpoint slows down its own client and nobody else’s. What it must not do is assume it is alone: a session may be sent to from another thread entirely (that is what makes broadcast possible), and WebSocketSession is written to allow it.

The optional callbacks have empty defaults, so an endpoint overrides only what it cares about. PING is answered automatically before onPing is called; an endpoint never has to write the PONG itself.