@WS — Aquilia Documentation
Comprehensive guide and documentation for @WS in the Aquilia framework. View API reference, examples, and implementation patterns.
Back to Decorators @WS The @WS decorator creates WebSocket endpoints for real-time, bidirectional communication. Unlike HTTP handlers, WebSocket handlers maintain a persistent connection. Basic Usage Connection Lifecycle A WebSocket handler has a distinct lifecycle compared to HTTP handlers. 1. Handshake The connection starts as an HTTP Upgrade request. Aquilia routes this to your handler. You must call await ws.accept() to complete the handshake, or the connection will close. 2. Message Loop Typically implemented as a while True loop. Use receive_text(), receive_bytes(), or receive_json() to wait for messages. 3. Disconnection When the client disconnects, `receive_*` methods will raise a `WebSocketDisconnect` exception. It is best practice to wrap your loop in a try/except block to handle cleanups. Differences from HTTP No Response Object: You do not return a `Response` object. You send data directly via `ws.send_*`. Middleware Limitations: Some global middleware (like GZip or Content-Length helpers) may not apply to the WebSocket stream itself, only the initial handshake. Pipelines: Route pipelines (`pipeline=[...]`) do not apply to WebSockets in the same way, as there isn't a single request/response cycle. However, guards run before the handler is invoked, allowing you to reject the handshake (e.g., authentication). Previous: @OPTIONS Next: @route )
Go to Homepage