NestJS Enterprise Backend APIs · Lezione

Gateway WebSocket con l’adapter Socket.IO

Implementi gli handler @WebSocketGateway, le room e gli hook del ciclo di vita per la comunicazione in tempo reale.

Lezione 1 di 413 passaggi

Gateway WebSocket con l’adapter Socket.IO è una lezione NestJS Enterprise Backend APIs gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento NestJS Enterprise Backend APIs, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso NestJS Enterprise Backend APIs include 4 lezioni in totale.

Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.

Why Gateways Exist

REST handles request/response, but real-time features (chat, presence, live dashboards) need a persistent, bidirectional channel. NestJS wraps this with a WebSocket Gateway.

A gateway is a provider decorated with @WebSocketGateway().
By default Nest uses the Socket.IO platform adapter (@nestjs/platform-socket.io).
Gateways are normal Nest classes: they support dependency injection, guards, pipes, and interceptors just like controllers.

Install the deps with npm i @nestjs/websockets @nestjs/platform-socket.io socket.io.

Declaring a Gateway

Decorate a class with @WebSocketGateway() and register it as a provider in a module. You can pass a port and options such as namespace and CORS config.

@SubscribeMessage('event') binds a handler to an inbound Socket.IO event.
The return value (or a WsResponse) is emitted back to the calling client.

Below, clients sending ping receive a pong reply.

import { WebSocketGateway, SubscribeMessage, MessageBody } from '@nestjs/websockets';

@WebSocketGateway({ namespace: '/chat', cors: { origin: '*' } })
export class ChatGateway {
  @SubscribeMessage('ping')
  handlePing(@MessageBody() data: string): { event: string; data: string } {
    return { event: 'pong', data: `received: ${data}` };
  }
}

Accessing the Server Instance

To broadcast to many clients you need the underlying Socket.IO Server. Inject it with the @WebSocketServer() property decorator.

server.emit('event', payload) sends to every connected client in the namespace.
This is the foundation for fan-out features like global announcements.

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

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @WebSocketServer()
  server: Server;

  @SubscribeMessage('broadcast')
  handleBroadcast(@MessageBody() message: string): void {
    this.server.emit('announcement', message);
  }
}

The Connected Socket

Each client has its own Socket. Inject it per-handler with @ConnectedSocket() to read auth data, the socket id, or to reply only to that client.

client.emit(...) targets just the sender.
client.id uniquely identifies the connection.
client.handshake exposes headers, query, and auth handed in at connect time.

import { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket } from '@nestjs/websockets';
import { Socket } from 'socket.io';

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @SubscribeMessage('whoami')
  whoAmI(@ConnectedSocket() client: Socket, @MessageBody() _: unknown): void {
    client.emit('identity', { id: client.id, token: client.handshake.auth?.token });
  }
}

Lifecycle Hooks

Gateways can implement lifecycle interfaces to react to connection events:

OnGatewayInit → afterInit(server) runs once the server is ready.
OnGatewayConnection → handleConnection(client) fires per new client.
OnGatewayDisconnect → handleDisconnect(client) fires when a client leaves.

Use these for presence tracking, auth on connect, and cleanup.

import { WebSocketGateway, OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect } from '@nestjs/websockets';
import { Server, Socket } from 'socket.io';
import { Logger } from '@nestjs/common';

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect {
  private readonly logger = new Logger(ChatGateway.name);

  afterInit(server: Server): void {
    this.logger.log('Gateway initialized');
  }

  handleConnection(client: Socket): void {
    this.logger.log(`Client connected: ${client.id}`);
  }

  handleDisconnect(client: Socket): void {
    this.logger.log(`Client disconnected: ${client.id}`);
  }
}

Rooms: Grouping Sockets

A room is a server-side label you attach to sockets so you can broadcast to a subset. A socket can belong to many rooms.

client.join('room') adds the socket to a room.
client.leave('room') removes it.
Socket.IO automatically puts each socket in a room named after its own client.id.

Rooms are how you build per-channel chat, per-tenant dashboards, or per-document collaboration.

import { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket } from '@nestjs/websockets';
import { Socket } from 'socket.io';

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @SubscribeMessage('joinRoom')
  joinRoom(@ConnectedSocket() client: Socket, @MessageBody() room: string): void {
    client.join(room);
    client.emit('joined', room);
  }
}

Broadcasting to a Room

Target a room with server.to('room').emit(...). To exclude the sender, emit from the client socket: client.to('room').emit(...) sends to everyone in the room except that client.

server.to(room).emit(...) → everyone in the room.
client.to(room).emit(...) → everyone in the room but the sender.

import { WebSocketGateway, WebSocketServer, SubscribeMessage, MessageBody, ConnectedSocket } from '@nestjs/websockets';
import { Server, Socket } from 'socket.io';

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @WebSocketServer() server: Server;

  @SubscribeMessage('sendToRoom')
  sendToRoom(
    @ConnectedSocket() client: Socket,
    @MessageBody() body: { room: string; text: string },
  ): void {
    client.to(body.room).emit('message', { from: client.id, text: body.text });
  }
}

Acknowledgements with WsResponse

Socket.IO supports request/response style acknowledgements. In Nest you can return a value, a WsResponse<T> object, or even an Observable that streams multiple emissions back.

Return { event, data } to emit a named event back to the caller.
Returning an Observable emits one message per value, useful for progress updates.

import { WebSocketGateway, SubscribeMessage, MessageBody, WsResponse } from '@nestjs/websockets';
import { from, Observable } from 'rxjs';
import { map } from 'rxjs/operators';

@WebSocketGateway({ namespace: '/jobs' })
export class JobsGateway {
  @SubscribeMessage('countdown')
  countdown(@MessageBody() n: number): Observable<WsResponse<number>> {
    const ticks = Array.from({ length: n }, (_, i) => n - i);
    return from(ticks).pipe(map((value) => ({ event: 'tick', data: value })));
  }
}

Validation with Pipes

Gateways reuse Nest's ValidationPipe, but errors are thrown as WsException rather than HTTP exceptions. Apply the pipe at the handler or gateway level and validate a DTO via @MessageBody().

Set transform: true so plain payloads become class instances.
A WsException is serialized to an exception event on the client.

import { WebSocketGateway, SubscribeMessage, MessageBody } from '@nestjs/websockets';
import { UsePipes, ValidationPipe } from '@nestjs/common';
import { IsString, MinLength } from 'class-validator';

class SendMessageDto {
  @IsString() @MinLength(1)
  text: string;
}

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway {
  @UsePipes(new ValidationPipe({ transform: true }))
  @SubscribeMessage('send')
  send(@MessageBody() dto: SendMessageDto): { event: string; data: string } {
    return { event: 'sent', data: dto.text };
  }
}

Authenticating on Connect

Authenticate clients during handleConnection by reading the token from the handshake and disconnecting unauthorized sockets early. Storing the user on client.data makes it available to every later handler.

Token usually arrives via handshake.auth.token or an Authorization header.
Call client.disconnect() to reject bad clients before they join rooms.

import { WebSocketGateway, OnGatewayConnection } from '@nestjs/websockets';
import { Socket } from 'socket.io';
import { JwtService } from '@nestjs/jwt';

@WebSocketGateway({ namespace: '/chat' })
export class ChatGateway implements OnGatewayConnection {
  constructor(private readonly jwt: JwtService) {}

  async handleConnection(client: Socket): Promise<void> {
    try {
      const token = client.handshake.auth?.token as string;
      client.data.user = await this.jwt.verifyAsync(token);
    } catch {
      client.emit('error', 'Unauthorized');
      client.disconnect();
    }
  }
}

Swapping the Adapter for Scale

Out of the box, Socket.IO state lives in a single process. To run multiple Nest instances behind a load balancer you must share room/emit state. Use a custom adapter with the Redis adapter so broadcasts reach clients on other nodes.

Subclass IoAdapter and attach @socket.io/redis-adapter in createIOServer.
Register it via app.useWebSocketAdapter(new RedisIoAdapter(app)) in main.ts.

import { IoAdapter } from '@nestjs/platform-socket.io';
import { ServerOptions } from 'socket.io';
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

export class RedisIoAdapter extends IoAdapter {
  private adapterConstructor: ReturnType<typeof createAdapter>;

  async connectToRedis(): Promise<void> {
    const pub = createClient({ url: 'redis://localhost:6379' });
    const sub = pub.duplicate();
    await Promise.all([pub.connect(), sub.connect()]);
    this.adapterConstructor = createAdapter(pub, sub);
  }

  createIOServer(port: number, options?: ServerOptions): any {
    const server = super.createIOServer(port, options);
    server.adapter(this.adapterConstructor);
    return server;
  }
}

Quick Check

Test your understanding of room broadcasting semantics.

Rispondi nella lezione interattiva

Recap

You built a real-time layer with NestJS WebSocket gateways on the Socket.IO adapter:

Gateway basics: @WebSocketGateway() providers with @SubscribeMessage handlers; inject the server via @WebSocketServer() and the per-client socket via @ConnectedSocket().
Lifecycle hooks: afterInit, handleConnection, and handleDisconnect for init, presence, and cleanup.
Rooms: client.join/leave, then server.to(room) for everyone or client.to(room) to exclude the sender.
Robustness: validate payloads with ValidationPipe (errors become WsException), authenticate in handleConnection, and use acknowledgements/Observables for replies.
Scale: swap in a Redis-backed IoAdapter so broadcasts work across multiple instances.

Gratis per iniziare

Impara TypeScript con un tutor IA — gratis

Scrivi ed esegui vero codice nel tuo browser, ricevi aiuto istantaneo da un tutor IA disponibile 24/7, e riprendi da dove hai lasciato sul web o nell'app.

Corsi: 20
Lezioni: 76

Inizia a imparare gratis Visualizza il corso completo

Domande Frequenti

La lezione «Gateway WebSocket con l’adapter Socket.IO» è gratuita?

Sì — il testo completo di «Gateway WebSocket con l’adapter Socket.IO» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso NestJS Enterprise Backend APIs, passa a CoddyKit PRO. Il corso NestJS Enterprise Backend APIs include 4 lezioni in totale.

Cosa imparerò in «Gateway WebSocket con l’adapter Socket.IO»?

Implementi gli handler @WebSocketGateway, le room e gli hook del ciclo di vita per la comunicazione in tempo reale. Eserciti NestJS Enterprise Backend APIs con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare NestJS Enterprise Backend APIs?

Non è richiesta alcuna esperienza precedente. NestJS Enterprise Backend APIs su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Gateway WebSocket con l’adapter Socket.IO»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione NestJS Enterprise Backend APIs?

Sì. Ogni lezione NestJS Enterprise Backend APIs include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

Gateway WebSocket con l’adapter Socket.IO
Autenticare e proteggere le connessioni Socket
Server-Sent Events per il push unidirezionale
Scalare il realtime con un adapter Redis Pub/Sub

← Torna a NestJS Enterprise Backend APIs