WebSocket guards and pipes in NestJS

Introduction

WebSocket guards and pipes help control and process data in real-time communication. Guards check if a user can connect or send messages, while pipes clean or transform the data before use.

When you want to allow only certain users to connect to your WebSocket server.

When you need to check user permissions before processing a WebSocket message.

When you want to validate or transform incoming message data before handling it.

When you want to reject bad or incomplete data early to keep your app safe.

When you want to keep your WebSocket code clean by separating checks and data processing.

Syntax

NestJS

import { CanActivate, ExecutionContext, Injectable, PipeTransform, ArgumentMetadata } from '@nestjs/common';
import { WsException } from '@nestjs/websockets';

@Injectable()
export class MyGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const client = context.switchToWs().getClient();
    // Your logic here
    return true; // or false to block
  }
}

@Injectable()
export class MyPipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    // Your transformation or validation here
    return value; // or throw new WsException('Error message')
  }
}

Guards must return true to allow the action or false to block it.

Pipes can modify data or throw exceptions to stop processing.

Examples

This guard checks if the client sent a correct token before allowing connection.

NestJS

import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { WsException } from '@nestjs/websockets';

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const client = context.switchToWs().getClient();
    const token = client.handshake.auth.token;
    if (token === 'secret') {
      return true;
    }
    throw new WsException('Unauthorized');
  }
}

This pipe checks if the incoming message has a text property that is a string.

NestJS

import { PipeTransform, Injectable, ArgumentMetadata } from '@nestjs/common';
import { WsException } from '@nestjs/websockets';

@Injectable()
export class ValidateMessagePipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    if (!value.text || typeof value.text !== 'string') {
      throw new WsException('Invalid message format');
    }
    return value;
  }
}

Sample Program

This example shows a WebSocket gateway that uses a guard to allow only clients with the correct token. It also uses a pipe to check that incoming messages have a valid text string. If both pass, it returns a confirmation message.

NestJS

import { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket, WsException, UseGuards, UsePipes } from '@nestjs/websockets';
import { Socket } from 'socket.io';
import { Injectable, CanActivate, ExecutionContext, PipeTransform, ArgumentMetadata } from '@nestjs/common';

@Injectable()
class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const client = context.switchToWs().getClient<Socket>();
    const token = client.handshake.auth.token;
    if (token === 'secret') {
      return true;
    }
    throw new WsException('Unauthorized');
  }
}

@Injectable()
class ValidateMessagePipe implements PipeTransform {
  transform(value: any, metadata: ArgumentMetadata) {
    if (!value.text || typeof value.text !== 'string') {
      throw new WsException('Invalid message format');
    }
    return value;
  }
}

@WebSocketGateway()
export class ChatGateway {
  @UseGuards(AuthGuard)
  @UsePipes(ValidateMessagePipe)
  @SubscribeMessage('message')
  handleMessage(@MessageBody() data: { text: string }, @ConnectedSocket() client: Socket): string {
    return `Received: ${data.text}`;
  }
}

Important Notes

Always throw WsException in guards or pipes to send error messages to clients.

Use @UseGuards() and @UsePipes() decorators to apply guards and pipes on WebSocket handlers.

Guards run before pipes, so permission checks happen before data validation.

Summary

Guards control who can connect or send messages.

Pipes check and transform message data before use.

Use them together to keep your WebSocket app safe and clean.

Practice

1. What is the main purpose of a WebSocket guard in a NestJS application?

easy

A. To control access and decide if a client can connect or send messages

B. To transform incoming message data before it reaches the handler

C. To log all WebSocket messages for debugging

D. To automatically retry failed WebSocket connections

Solution

1. Step 1: Understand the role of guards

   Guards in NestJS are used to control access by allowing or denying client connections or message handling.

2. Step 2: Differentiate guards from pipes

   Pipes transform or validate data, not control access, so they do not decide connection permissions.

3. Final Answer:

   To control access and decide if a client can connect or send messages -> Option A

4. Quick Check:

   Guards control access = A [OK]

Hint: Guards control access, pipes transform data [OK]

Common Mistakes:

• Confusing guards with pipes
• Thinking guards transform data
• Assuming guards handle logging

2. Which of the following is the correct way to apply a guard to a WebSocket gateway method in NestJS?

easy

A. @UseGuards(MyGuard) on the gateway class

B. @UseGuards(MyGuard) on the gateway method

C. @UsePipes(MyGuard) on the gateway method

D. @UseFilters(MyGuard) on the gateway class

Solution

1. Step 1: Recall decorator usage for guards

   Guards are applied using @UseGuards decorator either on the class or method. Applying on method is valid and common.

2. Step 2: Identify correct decorator and target

   @UseGuards is correct for guards; @UsePipes is for pipes, and @UseFilters is for exception filters.

3. Final Answer:

   @UseGuards(MyGuard) on the gateway method -> Option B

4. Quick Check:

   @UseGuards on method = A [OK]

Hint: Use @UseGuards for guards, not pipes or filters [OK]

Common Mistakes:

• Using @UsePipes instead of @UseGuards for guards
• Applying filters instead of guards
• Applying decorators on wrong targets

3. Given this WebSocket gateway method with a pipe, what will happen if the incoming message payload is invalid?

@SubscribeMessage('msg')
@UsePipes(new ValidationPipe())
handleMessage(@MessageBody() data: CreateDto) {
  return 'Received';
}

medium

A. The server crashes due to invalid data

B. The message is accepted without validation

C. The message is rejected and an error is sent back to the client

D. The message is transformed but still processed

Solution

1. Step 1: Understand ValidationPipe behavior

   ValidationPipe checks incoming data and rejects it if invalid, sending an error response.

2. Step 2: Analyze the method setup

   The method uses @UsePipes with ValidationPipe, so invalid data triggers rejection, not acceptance or crash.

3. Final Answer:

   The message is rejected and an error is sent back to the client -> Option C

4. Quick Check:

   ValidationPipe rejects invalid data = C [OK]

Hint: ValidationPipe rejects invalid data automatically [OK]

Common Mistakes:

• Assuming invalid data is accepted
• Thinking server crashes on invalid data
• Confusing transformation with acceptance

4. Identify the error in this WebSocket gateway code snippet:

@SubscribeMessage('chat')
@UseGuards(AuthGuard)
@UsePipes(new ParseIntPipe())
handleChat(@MessageBody() data: string) {
  return data;
}

medium

A. handleChat method must return a Promise

B. AuthGuard cannot be used with WebSocket gateways

C. @UsePipes must be placed before @UseGuards

D. ParseIntPipe cannot parse a string directly without conversion

Solution

1. Step 1: Check pipe compatibility with data type

   ParseIntPipe expects a value that can be parsed to integer, but data is a string that may not convert properly.

2. Step 2: Validate other decorator usage

   AuthGuard is valid for WebSocket guards, and decorator order does not cause error here. Returning Promise is optional.

3. Final Answer:

   ParseIntPipe cannot parse a string directly without conversion -> Option D

4. Quick Check:

   ParseIntPipe needs numeric input = D [OK]

Hint: Pipes must match expected input types [OK]

Common Mistakes:

• Assuming guards can't be used on WebSocket
• Thinking decorator order always matters
• Believing return type must be Promise

5. You want to ensure only authenticated users can send messages and that the message payload is a valid JSON object with a 'text' property. Which combination of guard and pipe setup is best in a NestJS WebSocket gateway?

hard

A. Use @UseGuards(AuthGuard) to check authentication and @UsePipes(ValidationPipe) with a DTO validating 'text' property

B. Use @UsePipes(AuthGuard) to check authentication and @UseGuards(ValidationPipe) for payload validation

C. Use @UseGuards(AuthGuard) only, and validate payload manually inside the handler

D. Use @UsePipes(ValidationPipe) only, assuming it checks authentication too

Solution

1. Step 1: Assign correct roles to guard and pipe

   Guards handle authentication and authorization, so AuthGuard should be used as a guard.

2. Step 2: Use ValidationPipe with DTO for payload validation

   ValidationPipe validates and transforms incoming data using a DTO that checks the 'text' property.

3. Step 3: Evaluate other options

   Swapping guards and pipes misuses decorators; using guards only requires manual payload validation lacking automation; using pipes only misses authentication checks.

4. Final Answer:

   Use @UseGuards(AuthGuard) to check authentication and @UsePipes(ValidationPipe) with a DTO validating 'text' property -> Option A

5. Quick Check:

   Guard for auth + Pipe for validation = B [OK]

Hint: Guards for auth, pipes for data validation [OK]

Common Mistakes:

• Swapping guards and pipes roles
• Skipping automatic validation
• Assuming pipes handle authentication