Como você lida com WebSockets no FastAPI?

Question

Accepted Answer

FastAPI suporta **WebSockets** para comunicação real-time, bidirecional (chat, atualizações ao vivo, notificações) por meio do decorador `@app.websocket`. Ao contrário do request-response do HTTP, uma conexão WebSocket permanece aberta, permitindo que o servidor e o cliente enviem mensagens livremente.

## Um 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)
```

O padrão: `accept()` a conexão, depois um loop — `receive_text()`/`receive_json()` lê mensagens, `send_text()`/`send_json()` as envia. Uma exceção `WebSocketDisconnect` sinaliza que o cliente saiu (onde você faz limpeza).

## Transmissão para vários clientes (ex: 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
```

Gerenciar uma lista de conexões ativas permite **transmitir** para todos os clientes — a base dos recursos de chat e atualização ao vivo.

## Ressalva sobre escalabilidade

```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 que isso importa

WebSockets habilitam recursos **real-time, bidirecionais** — chat, notificações ao vivo, presença, edição colaborativa, dashboards ao vivo — que o modelo request-response do HTTP não consegue oferecer (o servidor pode fazer push para clientes, não apenas responder).

Entender o suporte a WebSocket do FastAPI é valioso para construir aplicações interativas modernas: o decorador `@app.websocket` com o loop accept/receive/send cobre comunicação real-time básica, e gerenciar conexões ativas possibilita **transmissão** (a base dos recursos multi-usuário como chat).

A fundação assíncrona do FastAPI é bem adequada para WebSockets.

Criticamente importante é a **ressalva sobre escalabilidade**: as conexões WebSocket são com estado e vinculadas a uma única instância de servidor, então a escalabilidade em múltiplas instâncias requer um **backplane Redis Pub/Sub** para retransmitir mensagens entre instâncias — uma armadilha comum, já que (como sessões) o estado da conexão não pode viver na memória de um processo quando múltiplas instâncias estão em execução.

Conhecer o padrão WebSocket básico, transmissão, tratamento de desconexão e a consideração de escalabilidade é conhecimento importante em nível sênior para construir as experiências real-time e interativas cada vez mais esperadas em aplicações modernas.