¿Cómo se manejan los WebSockets en FastAPI?

Question

Accepted Answer

FastAPI soporta **WebSockets** para comunicación bidireccional en tiempo real (chat, actualizaciones en vivo, notificaciones) a través del decorador `@app.websocket`. A diferencia del modelo request-response de HTTP, una conexión WebSocket permanece abierta, permitiendo que el servidor y el cliente envíen mensajes libremente.

## Un endpoint WebSocket básico

```python
from fastapi import WebSocket, WebSocketDisconnect

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()                  # accept the connection
    try:
        while True:
            data = await websocket.receive_text()    # receive a message from the client
            await websocket.send_text(f"Echo: {data}")  # send a message back
    except WebSocketDisconnect:
        print("client disconnected")           # handle disconnection (cleanup)
```

El patrón: `accept()` la conexión, luego loop — `receive_text()`/`receive_json()` lee mensajes, `send_text()`/`send_json()` los envía. Una excepción `WebSocketDisconnect` señala que el cliente se desconectó (donde limpias).

## Broadcasting a múltiples clientes (p.ej. chat)

```python
class ConnectionManager:
    def __init__(self): self.active: list[WebSocket] = []
    async def connect(self, ws): await ws.accept(); self.active.append(ws)
    def disconnect(self, ws): self.active.remove(ws)
    async def broadcast(self, msg):
        for conn in self.active:
            await conn.send_text(msg)          # send to ALL connected clients

manager = ConnectionManager()

@app.websocket("/chat")
async def chat(ws: WebSocket):
    await manager.connect(ws)
    try:
        while True:
            msg = await ws.receive_text()
            await manager.broadcast(msg)        # everyone gets the message
    except WebSocketDisconnect:
        manager.disconnect(ws)                  # remove on disconnect
```

Administrar una lista de conexiones activas te permite **hacer broadcast** a todos los clientes — la base de las características de chat y actualizaciones en vivo.

## Advertencia sobre escalado

```text
⚠️ WebSocket connections are STATEFUL and live on ONE server instance.
To scale across multiple instances, use a Redis Pub/Sub (or similar) backplane so
messages/broadcasts reach clients connected to OTHER instances.
(Like sessions, don't keep connection state only in one process when scaling horizontally.)
```

## Por qué es importante

Los WebSockets permiten características **bidireccionales en tiempo real** — chat, notificaciones en vivo, presencia, edición colaborativa, dashboards en vivo — que el modelo request-response de HTTP no puede proporcionar (el servidor puede hacer push a clientes, no solo responder).

Comprender el soporte de WebSocket en FastAPI es valioso para construir aplicaciones interactivas modernas: el decorador `@app.websocket` con el loop accept/receive/send cubre comunicación básica en tiempo real, y administrar conexiones activas permite **broadcasting** (la base de características multiusuario como chat).

El fundamento async de FastAPI es adecuado para WebSockets.

Críticamente importante es la **advertencia sobre escalado**: las conexiones WebSocket tienen estado y están vinculadas a una única instancia del servidor, así que escalar a través de múltiples instancias requiere un **Redis Pub/Sub backplane** para retransmitir mensajes entre instancias — una trampa común, ya que (como las sesiones) el estado de conexión no puede vivir en la memoria de un solo proceso cuando se ejecutan múltiples instancias.

Conocer el patrón básico de WebSocket, broadcasting, manejo de desconexión y la consideración de escalado es un conocimiento importante a nivel senior para construir las experiencias interactivas y en tiempo real que se esperan cada vez más en aplicaciones modernas.