¿Cómo construyes características en tiempo real con gateways WebSocket?

Question

Accepted Answer

NestJS soporta **comunicación bidireccional en tiempo real** a través de **gateways WebSocket** — clases decoradas con `@WebSocketGateway()` que manejan conexiones y mensajes WebSocket (típicamente sobre Socket.IO). Habilitan características como chat, notificaciones en vivo y dashboards en vivo, usando la misma estructura de NestJS (inyección de dependencias, decoradores).

## Definir 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 usa `@SubscribeMessage("event")` para manejar eventos entrantes (análogo a `@Post` para HTTP) y el `server` inyectado para **emitir** eventos de vuelta a los clientes — `server.emit` transmite a todos.

## Hooks del ciclo de vida de conexión

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

Los gateways pueden reaccionar a clientes conectándose y desconectándose — útil para seguimiento de presencia y limpieza.

## Dirigirse a clientes específicos y salas

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

**Las salas** agrupan clientes (por ej. una sala de chat, colaboradores de un documento), permitiéndote transmitir a subconjuntos específicos en lugar de a todos — esencial para características en tiempo real con alcance.

## Los gateways reutilizan características 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.
```

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

## Por qué es importante

Los gateways WebSocket son cómo NestJS soporta **características bidireccionales en tiempo real** — chat, notificaciones en vivo, presencia, edición colaborativa, dashboards en vivo, interacciones multijugador — que el modelo de solicitud-respuesta de REST no puede proporcionar (el servidor puede enviar a los clientes, no solo responder a solicitudes).

Comprender estos gateways es un conocimiento valioso de nivel senior para construir aplicaciones interactivas modernas.

La fortaleza clave es que los gateways se adaptan a la estructura familiar de NestJS: son proveedores que soportan **inyección de dependencias** y pueden usar **guards, pipes, interceptores y filtros** igual que los controladores HTTP, así que los mismos patrones y organización del código aplican al tiempo real como a REST.

Saber cómo manejar eventos (`@SubscribeMessage`), transmitir a clientes (`server.emit`), usar **salas** para limitar transmisiones a subconjuntos relevantes (salas de chat, colaboradores de documentos) y gestionar el ciclo de vida de conexión (presencia, limpieza) cubre el toolkit práctico en tiempo real.

Críticamente importante es la **consideración de escalabilidad**: las conexiones WebSocket son con estado y están vinculadas a una única instancia de servidor, así que escalar horizontalmente requiere un **adaptador Redis** para coordinar transmisiones/salas entre instancias (una trampa común — como las sesiones, el estado en tiempo real no puede vivir en la memoria de un solo proceso cuando se ejecutan múltiples instancias).

Esta es una capacidad importante e cada vez más relevante para construir las experiencias interactivas en tiempo real que los usuarios modernos esperan, y la integración limpia de NestJS la hace accesible mientras reutiliza la estructura del framework.