Come gestisci i WebSocket in FastAPI?

Question

Accepted Answer

FastAPI supporta i **WebSocket** per la comunicazione bidirezionale in tempo reale (chat, aggiornamenti live, notifiche) tramite il decoratore `@app.websocket`. A differenza del modello request-response di HTTP, una connessione WebSocket rimane aperta, permettendo al server e al client di inviare messaggi liberamente.

## Un endpoint WebSocket di base

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

Lo schema: `accept()` la connessione, poi fai un loop — `receive_text()`/`receive_json()` legge i messaggi, `send_text()`/`send_json()` li invia. Un'eccezione `WebSocketDisconnect` segnala che il client se n'è andato (dove effettui la pulizia).

## Broadcasting a più client (ad esempio 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
```

Gestire una lista di connessioni attive ti permette di **fare broadcast** a tutti i client — la base delle funzionalità di chat e aggiornamento live.

## Caveat di scaling

```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.)
```

## Perché è importante

I WebSocket abilitano funzionalità **bidirezionali in tempo reale** — chat, notifiche live, presence, editing collaborativo, dashboard live — che il modello request-response di HTTP non può fornire (il server può spingere messaggi ai client, non solo rispondere).

Comprendere il supporto WebSocket di FastAPI è prezioso per costruire applicazioni interattive moderne: il decoratore `@app.websocket` con il loop accept/receive/send copre la comunicazione in tempo reale di base, e gestire le connessioni attive abilita il **broadcasting** (il nucleo delle funzionalità multi-utente come chat).

La fondazione asincrona di FastAPI si adatta bene ai WebSocket.

Criticamente importante è il **caveat di scaling**: le connessioni WebSocket sono stateful e legate a una singola istanza di server, quindi lo scaling tra più istanze richiede un **backplane Redis Pub/Sub** per trasmettere i messaggi tra le istanze — una trappola comune, poiché (come le sessioni) lo stato della connessione non può risiedere nella memoria di un singolo processo quando si eseguono più istanze.

Conoscere lo schema WebSocket di base, il broadcasting, la gestione della disconnessione e la considerazione di scaling è importante per la conoscenza di livello senior nel costruire le esperienze interattive in tempo reale sempre più attese nelle applicazioni moderne.