Jak budować funkcjonalności czasu rzeczywistego za pomocą bram WebSocket?

Question

Accepted Answer

NestJS obsługuje **komunikację czasu rzeczywistego, dwukierunkową** poprzez **bramy WebSocket** — klasy dekorowane `@WebSocketGateway()`, które obsługują połączenia WebSocket i wiadomości (zazwyczaj poprzez Socket.IO). Umożliwiają funkcjonalności takie jak czat, powiadomienia na żywo i pulpity nawigacyjne na żywo, wykorzystując tę samą strukturę NestJS (DI, dekoratory).

## Definiowanie bramy

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

Brama używa `@SubscribeMessage("event")` do obsługi przychodzących zdarzeń (analogicznie do `@Post` dla HTTP) i wstrzykniętego serwera do **emitowania** zdarzeń zwrotnie do klientów — `server.emit` rozgłasza do wszystkich.

## Hooks cyklu życia połączenia

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

Bramy mogą reagować na połączenie i rozłączenie się klientów — przydatne do śledzenia obecności i czyszczenia.

## Kierowanie do konkretnych klientów i pokoi

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

**Pokoje** grupują klientów (np. pokój czatu, współpracownicy dokumentu), pozwalając na rozgłaszanie do konkretnych podzbiorów zamiast do wszystkich — niezbędne dla funkcjonalności czasu rzeczywistego w ograniczonym zasięgu.

## Bramy ponownie wykorzystują funkcjonalności 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.
```

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

## Dlaczego to ważne

Bramy WebSocket to sposób, w jaki NestJS obsługuje **funkcjonalności czasu rzeczywistego, dwukierunkowe** — czat, powiadomienia na żywo, obecność, edycję współpracowniczą, pulpity nawigacyjne na żywo, interakcje wieloosobowe — które model request-response REST nie może zapewnić (serwer może wysyłać do klientów, nie tylko odpowiadać na żądania).

Rozumienie ich to cenna wiedza na poziomie seniora do budowania nowoczesnych aplikacji interaktywnych.

Hastawą mocną stronę jest to, że bramy pasują do znanej struktury NestJS: są dostawcami wspierającymi **iniekcję zależności** i mogą używać **strażników, rur, przechwytujących oraz filtrów** dokładnie tak jak kontrolery HTTP, więc te same wzorce i organizacja kodu dotyczą czasu rzeczywistego jak i REST.

Wiedza o obsłudze zdarzeń (`@SubscribeMessage`), rozgłaszaniu do klientów (`server.emit`), używaniu **pokoi** do ograniczenia rozgłaszania do odpowiednich podzbiorów (pokoje czatu, współpracownicy dokumentu) i zarządzaniu cyklem życia połączenia (obecność, czyszczenie) obejmuje praktyczny zestaw narzędzi czasu rzeczywistego.

Krytycznie ważna jest **kwestia skalowania**: połączenia WebSocket są stanowe i powiązane z pojedynczą instancją serwera, więc skalowanie w poziomie wymaga **adaptera Redis** do koordynacji rozgłaszania/pokoi między instancjami (typowa pułapka — jak sesje, stan czasu rzeczywistego nie może żyć w pamięci jednego procesu przy uruchamianiu wielu instancji).

To jest ważna, coraz bardziej istotna zdolność do budowania doświadczeń czasu rzeczywistego, interaktywnych, których oczekują nowoczesni użytkownicy, i czysta integracja NestJS sprawia, że jest dostępna przy jednoczesnym ponownym wykorzystaniu struktury frameworka.