Cum construiești funcționalități real-time cu WebSocket gateways?

Question

Accepted Answer

NestJS suportă **comunicare real-time, bidirectională** prin **WebSocket gateways** — clase decorate cu `@WebSocketGateway()` care gestionează conexiuni și mesaje WebSocket (de obicei peste Socket.IO). Acestea activează funcționalități precum chat, notificări live și dashboard-uri live, folosind aceeași structură NestJS (DI, decoratori).

## Definirea unui 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 folosește `@SubscribeMessage("event")` pentru a gestiona evenimentele primite (analog cu `@Post` pentru HTTP) și serverul injectat pentru a **emite** evenimente înapoi clienților — `server.emit` transmite tuturor.

## Hook-uri lifecycle de conexiune

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

Gateway-urile pot reacționa la clienti care se conectează și se deconectează — util pentru presence tracking și cleanup.

## Țintirea clienților specifici și a room-urilor

```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-urile** grupează clienți (de ex. o cameră de chat, colaboratorii unui document), permițând transmiterea către subseturi specifice în loc de toți — esențial pentru funcționalități real-time cu domeniu de aplicare.

## Gateway-urile reutilizează funcționalitățile 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.
```

## Scalarea WebSocket-urilor

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

## De ce contează

WebSocket gateway-urile sunt modul în care NestJS suportă **funcționalități real-time, bidirectionale** — chat, notificări live, presence, editare colaborativă, dashboard-uri live, interacții multiplayer — pe care modelul request-response al REST nu le poate furniza (serverul poate transmite clienților, nu doar răspunde la cereri).

Înțelegerea lor este cunoaștere valoroasă la nivel senior pentru construirea aplicațiilor interactive moderne.

Punctul forte cheie este că gateway-urile se potrivesc structurii familiare NestJS: sunt provideri care suportă **dependency injection** și pot folosi **guards, pipes, interceptors și filters** la fel ca și controlerele HTTP, deci același pattern și organizare de cod se aplică real-time și REST.

Cunoscând cum să gestionezi evenimentele (`@SubscribeMessage`), cum să transmite clienților (`server.emit`), cum să folosești **room-urile** pentru a-și limita transmisiile la subseturi relevante (camere de chat, colaboratori de documente) și cum să gestionezi lifecycle-ul de conexiune (presence, cleanup), acoperă toolkit-ul practic real-time.

Critic important este considerația **scalare**: conexiunile WebSocket sunt cu stare și legate de o singură instanță de server, deci scalarea orizontală necesită un **adaptor Redis** pentru a coordona transmisii/room-uri pe instanțe (o capcană comună — ca și sesiunile, starea real-time nu poate să trăiască în memoria unui singur proces când se rulează mai multe instanțe).

Acesta este un capabilitate importantă, din ce în ce mai relevantă pentru construirea experiențelor real-time și interactive pe care utilizatorii moderni le așteaptă, iar integrarea curată a NestJS o face accesibilă reutilizând structura framework-ului.