WebSocket guards and pipes in NestJS - Step-by-Step Execution

Concept Flow - WebSocket guards and pipes

Client sends WebSocket message

↓

WebSocket Gateway receives message

↓

Apply Guards

↓

Reject connection or message

↓

Stop

↓

Send response or event

When a WebSocket message arrives, guards check if it is allowed. If yes, pipes transform or validate the data before the handler runs.

Execution Sample

NestJS

import { WebSocketGateway, SubscribeMessage, MessageBody, UseGuards, UsePipes } from '@nestjs/websockets';
import { ValidationPipe } from '@nestjs/common';
import { IsString, IsNotEmpty } from 'class-validator';
import { WsGuard } from './ws.guard';

class MessageDto {
  @IsString()
  @IsNotEmpty()
  text: string;
}

@WebSocketGateway()
export class ChatGateway {
  @UseGuards(WsGuard)
  @SubscribeMessage('message')
  @UsePipes(new ValidationPipe())
  handleMessage(@MessageBody() data: MessageDto) {
    return { event: 'message', data };
  }
}

This code uses a guard to check access and a pipe to validate incoming WebSocket messages before handling them.

Execution Table

Step	Action	Guard Result	Pipe Result	Handler Called	Response Sent
1	Client sends 'message' event with data {text: 'Hi'}	Guard checks token: valid	Pipe validates data: valid	Yes	Sends {event: 'message', data: {text: 'Hi'}}
2	Client sends 'message' event with data {text: ''}	Guard checks token: valid	Pipe validates data: invalid (empty text)	No	Sends error response
3	Client sends 'message' event with no token	Guard checks token: invalid	Pipe skipped	No	Sends error response

💡 Execution stops when guard denies access or pipe validation fails.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3
guardResult	undefined	valid	valid	invalid
pipeResult	undefined	valid	invalid	skipped
handlerCalled	false	true	false	false
response	none	{event: 'message', data}	error response	error response

Key Moments - 2 Insights

Why does the handler not run when the guard fails?

Because the guard blocks unauthorized messages early, as shown in execution_table step 3 where guardResult is 'invalid' and handlerCalled is 'No'.

What happens if the pipe validation fails?

The handler is not called and an error response is sent, as in execution_table step 2 where pipeResult is 'invalid' and handlerCalled is 'No'.

Visual Quiz - 3 Questions

Look at the execution table, what is the guardResult at step 2?

A skipped

B valid

C invalid

D unknown

💡 Hint

Check the 'Guard Result' column in row for step 2.

At which step does the handler get called?

A Step 1

B Step 2

C Step 3

D None

💡 Hint

Look at the 'Handler Called' column in the execution table.

If the guard always returns valid and the pipe always passes, what changes in the execution table?

A Guard result changes to invalid

B Pipe validation skipped

C Handler called in all steps

D No response sent

💡 Hint

Refer to the 'Guard Result' and 'Handler Called' columns across steps.

Concept Snapshot

WebSocket Guards and Pipes in NestJS:
- Guards check if a message is allowed before processing.
- Pipes transform or validate message data.
- Guards run first; if they fail, processing stops.
- Pipes run next; if validation fails, handler is not called.
- Use @UseGuards() and @UsePipes() decorators on gateways or handlers.

Full Transcript

When a client sends a WebSocket message, the NestJS gateway first applies guards to check if the message is allowed. If the guard returns valid, the message data passes to pipes which validate or transform it. If the pipe validation succeeds, the message handler runs and sends a response. If either guard or pipe fails, the handler is skipped and an error response is sent. This flow ensures only authorized and valid messages are processed.

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