litestar-realtime

Use the @websocket decorator on a handler that receives a WebSocket object, call socket.accept(), then loop over receive_json and send_json. Catch WebSocketDisconnect silently since client disconnects are normal, and set opt={"exclude_from_csrf": True, "exclude_from_auth": True} to bypass HTTP middleware.

Use plain WebSockets for one-off streams with few channel names. Use the Channels plugin when you need dynamic topics, message history, automatic /ws/{channel} handlers, or cross-process publishing from workers and scripts through a shared backend.

Browsers cannot set arbitrary headers during the WebSocket handshake, so pass a JWT as a token query parameter. Write a guard that decodes the token, loads the user, attaches it to connection.state, and raises WebSocketException with code 4001 on failure.

For sqlspec plus PostgreSQL stacks, use the SQLSpecChannelsBackend which reuses the existing connection pool via LISTEN/NOTIFY. Avoid adding Redis solely for Channels in a PostgreSQL-only project, and avoid PG backends when Redis already handles queues and caching.

Import the same ChannelsPlugin instance in your SAQ worker and call channels.wait_published with the channel name and payload. Since the backend is shared across processes, any worker or script can publish while only subscribed WebSocket clients receive messages.

The Channels backend may not be initialized before the Litestar lifespan runs, such as in early-starting background workers. The RealtimePublisher pattern catches this RuntimeError and skips the publish with a debug log instead of raising.