WebSockets

Execution Workflow

1. Choose the interface first: low-level @websocket, reactive @websocket_listener, or proactive @websocket_stream / send_websocket_stream().
2. Decide how data should be received and sent: text vs binary transport, raw socket methods vs typed serialization.
3. Keep connection acceptance, disconnect handling, and cleanup explicit.
4. Add DI, guards, DTOs, or custom websocket classes only where they simplify the endpoint contract.
5. Test both nominal message flow and disconnect or invalid-payload behavior.

Core Rules

• Use low-level websocket handlers when you need full control over receive loops and socket operations.
• Use websocket listeners when a callback-style, typed receive-return-send flow matches the problem.
• Use websocket streams for proactive push from an async generator.
• Use send_websocket_stream() when you need to combine streaming with receiving data concurrently.
• Treat send and receive transport modes as protocol-level choices, not direct proxies for Python types.
• Keep disconnect handling explicit so loops and background tasks terminate cleanly.
• Avoid reading from the same socket in multiple places unless the flow is intentionally coordinated.