Come creare funzionalità real-time con i gateway WebSocket?

Question

Accepted Answer

NestJS supporta **comunicazione real-time e bidirezionale** tramite **gateway WebSocket** — classi decorate con `@WebSocketGateway()` che gestiscono connessioni e messaggi WebSocket (tipicamente su Socket.IO). Abilitano funzionalità come chat, notifiche live e dashboard live, utilizzando la stessa struttura NestJS (DI, decoratori).

## Definire un gateway

```ts
import { WebSocketGateway, SubscribeMessage, MessageBody, WebSocketServer } from "@nestjs/websockets";
import { Server } from "socket.io";

@WebSocketGateway({ cors: true })
export class ChatGateway {
  @WebSocketServer()
  server: Server;                        // the Socket.IO server instance

// handle a 'message' event from a client
  @SubscribeMessage("message")
  handleMessage(@MessageBody() data: { text: string }) {
    // BROADCAST to all connected clients
    this.server.emit("message", data);   // everyone receives the message
  }
}
```

Un gateway utilizza `@SubscribeMessage("event")` per gestire gli eventi in arrivo (analogo a `@Post` per HTTP) e il `server` iniettato per **emettere** eventi ai client — `server.emit` trasmette a tutti.

## Hook del ciclo di vita della connessione

```ts
export class ChatGateway implements OnGatewayConnection, OnGatewayDisconnect {
  handleConnection(client: Socket) {
    console.log(`Client connected: ${client.id}`);   // a user joined
  }
  handleDisconnect(client: Socket) {
    console.log(`Client disconnected: ${client.id}`); // a user left — clean up
  }
}
```

I gateway possono reagire ai client che si connettono e disconnettono — utile per il tracciamento della presenza e la pulizia.

## Targeting di client specifici e room

```ts
@SubscribeMessage("joinRoom")
handleJoin(@ConnectedSocket() client: Socket, @MessageBody() room: string) {
  client.join(room);                              // add the client to a room
}

@SubscribeMessage("roomMessage")
sendToRoom(@MessageBody() data: { room: string; text: string }) {
  this.server.to(data.room).emit("message", data.text);   // emit only to that room
  // client.emit(...) → just that client; server.emit(...) → everyone
}
```

**Room** raggruppano i client (ad esempio una chat room, i collaboratori di un documento), permettendoti di trasmettere a sottoinsiemi specifici piuttosto che a tutti — essenziale per funzionalità real-time scoped.

## I gateway riutilizzano le funzionalità NestJS

```text
Gateways are providers → they support dependency injection (inject services),
and can use guards, pipes, interceptors, and filters — just like HTTP controllers.
→ The same structure/patterns apply to real-time as to REST.
```

## Scaling dei WebSocket

```text
⚠️ WebSocket connections are STATEFUL and live on ONE server instance.
To scale across multiple instances, use a Redis adapter (socket.io-redis) so
broadcasts/rooms work across all instances. (Like sessions, don't keep state in
one process's memory when scaling horizontally.)
```

## Perché è importante

I gateway WebSocket sono il modo in cui NestJS supporta **funzionalità real-time e bidirezionali** — chat, notifiche live, presenza, editing collaborativo, dashboard live, interazioni multigiocatore — che il modello request-response di REST non può fornire (il server può fare push ai client, non solo rispondere alle richieste).

Capirli è una conoscenza di livello senior per costruire applicazioni interattive moderne.

Il punto di forza principale è che i gateway si adattano alla struttura familiare di NestJS: sono provider che supportano **dependency injection** e possono usare **guard, pipe, interceptor e filter** proprio come i controller HTTP, quindi gli stessi pattern e l'organizzazione del codice si applicano al real-time quanto al REST.

Sapere come gestire gli eventi (`@SubscribeMessage`), trasmettere ai client (`server.emit`), usare **room** per scoped broadcast ai sottoinsiemi rilevanti (chat room, collaboratori di documenti) e gestire il ciclo di vita della connessione (presenza, pulizia) copre il toolkit pratico real-time.

Critico è considerare lo **scaling**: le connessioni WebSocket sono stateful e legate a una singola istanza server, quindi il scaling orizzontale richiede un **Redis adapter** per coordinare broadcast e room tra istanze (una trappola comune — come le sessioni, lo stato real-time non può vivere nella memoria di un processo quando si eseguono più istanze).

Questa è una capacità importante e sempre più rilevante per costruire le esperienze real-time e interattive che gli utenti moderni si aspettano, e l'integrazione pulita di NestJS la rende accessibile riutilizzando al contempo la struttura del framework.