Comment construire des fonctionnalités en temps réel avec les WebSocket gateways ?

Question

Accepted Answer

NestJS supporte la **communication bidirectionnelle en temps réel** via les **WebSocket gateways** — des classes décorées avec `@WebSocketGateway()` qui gèrent les connexions et messages WebSocket (généralement sur Socket.IO). Elles permettent des fonctionnalités comme le chat, les notifications en direct et les tableaux de bord en direct, en utilisant la même structure NestJS (injection de dépendances, décorateurs).

## Définir une 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
  }
}
```

Une gateway utilise `@SubscribeMessage("event")` pour gérer les événements entrants (analogue à `@Post` pour HTTP) et le `server` injecté pour **émettre** des événements vers les clients — `server.emit` diffuse à tout le monde.

## Hooks du cycle de vie des connexions

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

Les gateways peuvent réagir aux clients se connectant et se déconnectant — utile pour le suivi de présence et le nettoyage.

## Cibler des clients spécifiques et des salons

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

Les **salons** regroupent les clients (p. ex. une salle de chat, les collaborateurs d'un document), vous permettant de diffuser à des sous-ensembles spécifiques plutôt qu'à tout le monde — essentiel pour les fonctionnalités en temps réel ciblées.

## Les gateways réutilisent les fonctionnalités de 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 les WebSockets

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

## Pourquoi c'est important

Les WebSocket gateways sont comment NestJS supporte les **fonctionnalités bidirectionnelles en temps réel** — chat, notifications en direct, présence, édition collaborative, tableaux de bord en direct, interactions multijoueurs — que le modèle requête-réponse de REST ne peut pas fournir (le serveur peut envoyer aux clients, pas seulement répondre aux requêtes).

Les comprendre est une connaissance précieuse au niveau senior pour construire des applications interactives modernes.

La force clé est que les gateways s'intègrent à la structure familière de NestJS : ce sont des providers supportant l'**injection de dépendances** et peuvent utiliser les **guards, pipes, interceptors et filters** tout comme les contrôleurs HTTP, donc les mêmes patterns et l'organisation du code s'appliquent au temps réel et à REST.

Savoir comment gérer les événements (`@SubscribeMessage`), diffuser aux clients (`server.emit`), utiliser les **salons** pour limiter les diffusions aux sous-ensembles pertinents (salons de chat, collaborateurs de documents) et gérer le cycle de vie des connexions (présence, nettoyage) couvre la boîte à outils pratique du temps réel.

Critiquement important est la **considération de scaling** : les connexions WebSocket sont statefull et liées à une seule instance de serveur, donc le scaling horizontal nécessite un **adaptateur Redis** pour coordonner les diffusions/salons entre les instances (une erreur courante — comme les sessions, l'état en temps réel ne peut pas vivre dans la mémoire d'un seul processus quand plusieurs instances tournent).

C'est une capacité importante et de plus en plus pertinente pour construire les expériences en temps réel et interactives que les utilisateurs modernes attendent, et l'intégration propre de NestJS la rend accessible tout en réutilisant la structure du framework.