The commit message follows our guidelines:https://github.com/nestjs/nest/blob/master/CONTRIBUTING.md
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

Bugfix
Feature
Code style update (formatting, local variables)
Refactoring (no functional changes, no api changes)
Build related changes
CI related changes
Other... Please describe:

What is the current behavior?

Currently, when a WebSocket client disconnects, the handleDisconnect
method only receives the client object without any information about why
the disconnection occurred. This makes it difficult for developers to
implement different handling logic based on the disconnect reason (e.g.,
client-initiated vs. network error vs. timeout).

Issue Number:#15437

What is the new behavior?

This PR enhances the WebSocket disconnect handling by providing the
disconnect reason as an optional second parameter to the handleDisconnect
method.

Changes:

OnGatewayDisconnect Interface: Added optional reason?: string parameter
to handleDisconnect method
NestGateway Interface: Updated to support the new disconnect reason
parameter
WebSocketsController: Modified to capture and forward disconnect reason
from events
IoAdapter: Enhanced to extract disconnect reason from Socket.IO
disconnect events

Usage:

Before(stillworks):  @WebSocketGateway()exportclassChatGatewayimplementsOnGatewayDisconnect{handleDisconnect(client:Socket){console.log('Client disconnected:',client.id);}}

After (new feature):

  @WebSocketGateway()exportclassChatGatewayimplementsOnGatewayDisconnect{handleDisconnect(client:Socket,reason?:string){console.log('Client disconnected:',client.id,'Reason:',reason);// Handle different disconnect scenariosswitch(reason){case'client namespace disconnect':// Client explicitly disconnectedbreak;case'transport close':// Connection lost due to network issuesbreak;case'ping timeout':// Client didn't respond to pingbreak;}}}

Common Disconnect Reasons:

'client namespace disconnect' - Client explicitly called disconnect()
'server namespace disconnect'- Server forced disconnection
'transport close'- Underlying transport was closed
'transport error' - Transport encountered an error
'ping timeout' - Client didn't respond to ping in time

Does this PR introduce a breaking change?

Other information

Implementation Details:

The implementation modifies the following core components:

Interface Updates: Both OnGatewayDisconnect and NestGateway interfaces
now support the optional reason parameter
Event Flow: The disconnect reason flows from Socket.IO → IoAdapter →
WebSocketsController → Gateway
Backward Compatibility: The implementation checks for data format and
handles both old and new formats seamlessly
Fix Applied: Corrected distinctUntilChanged() operator behavior to
properly handle both old format (just client) and new format ({ client, reason }) for disconnect events

Copy link

coveralls commentedJul 24, 2025•
edited
Loading

Pull Request Test Coverage Report forBuild ccc32411-c048-48b5-946a-1ddf86b11307

Details

3 of7(42.86%) changed or added relevant lines in1 file are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-0.03%) to88.885%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
packages/websockets/web-sockets-controller.ts	3	7	42.86%

Totals
Change from baseBuild a2f4d25f-1d25-415f-b2c5-967298b635ae:	-0.03%
Covered Lines:	7285
Relevant Lines:	8196

💛 -Coveralls

snowykte0426 mentioned this pull request

Jul 24, 2025

support disconnect reason tohandleDisconnect args#15437

Closed

1 task

snowykte0426 force-pushed themaster branch from315c653 to7262309Compare

July 24, 2025 13:37

feat(websockets): add disconnect reason parameter

834a4bf

This change enhances the WebSocket disconnect handling by providingthe disconnect reason as an optional second parameter to thehandleDisconnect method.Changes:- Add optional reason parameter to OnGatewayDisconnect interface- Update NestGateway interface to support disconnect reason- Modify WebSocketsController to capture and forward disconnect reason- Enhance IoAdapter to extract reason from Socket.IO disconnect events- Maintain full backward compatibility with existing implementations- Add comprehensive unit and integration testsThe disconnect reason helps developers understand why clients disconnect,enabling better error handling and debugging. Common reasons include'client namespace disconnect', 'transport close', 'ping timeout', etc.This change is fully backward compatible - existing code continues towork without modification while new code can optionally access thedisconnect reason.Closesnestjs#15437Signed-off-by: snowykte0426 <snowykte0426@naver.com>

snowykte0426 force-pushed themaster branch from7262309 to834a4bfCompare

July 24, 2025 14:13

kamilmysliwiec reviewed

Jul 25, 2025

View reviewed changes

packages/microservices/exceptions/rpc-exceptions-handler.ts Outdated

Comment on lines 38 to 43

		constfilters=this.filters.filter(
		filter=>filter.exceptionMetatypes?.length===0,
		);
		if(filters.length>0){
		returnfilters[0].func(exception,host);
		}

Copy link

Member

kamilmysliwiecJul 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

why(?)

Copy link

Author

snowykte0426Jul 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

This change prioritizes global exception filters (i.e., filters with empty exceptionMetatypes) over more specific ones. Previously, global filters that were intended to catch all exceptions could be skipped because they were processed after specific filters.

The updated logic ensures that if a filter is designed to handle all exception types (as indicated by an empty exceptionMetatypes array), it is invoked first, preserving the intended filter hierarchy and behavior.

Please let me know if I’ve misunderstood any part of this change.

Copy link

Member

kamilmysliwiecJul 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Previously, global filters that were intended to catch all exceptions could be skipped because they were processed after specific filters.

That's the expected behavior.

Copy link

Author

snowykte0426Jul 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Thanks for the clarification! I've removed the exception filter changes
in commit6cf7ad5 since the current behavior is indeed the intended
behavior.

kamilmysliwiec reviewed

Jul 25, 2025

View reviewed changes

packages/websockets/web-sockets-controller.ts Outdated

		event
		.pipe(distinctUntilChanged())
		.subscribe(instance.handleDisconnect.bind(instance));
		event.pipe(distinctUntilChanged()).subscribe((data:any)=>{

Copy link

Member

kamilmysliwiecJul 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

dont thinkdistinctUntilChanged will work as expected now

Copy link

Author

snowykte0426Jul 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

You’re right — thank you for pointing that out.
Since we’re now emitting objects like{ client, reason } instead of just the client,distinctUntilChanged() was comparing object references, which caused the deduplication to fail.

I’ve updated the code to include a custom comparison function fordistinctUntilChanged(). This handles both the previous format (just client) and the new one ({ client, reason }) by extracting and comparing the actual client values.

Really appreciate you catching this.

be6b50c

snowykte0426 added2 commits

July 25, 2025 17:52

fix(websockets): Correct distinctUntilChanged for disconnect events

be6b50c

Fix the distinctUntilChanged operator in subscribeDisconnectEvent to properlycompare client objects when using the new { client, reason } format. Theprevious implementation would not deduplicate correctly as it compared objectreferences instead of the actual client instances.This ensures backward compatibility while properly handling both the oldformat (just client) and new format ({ client, reason }) for disconnect events.Signed-off-by: snowykte0426 <snowykte0426@naver.com>

fix(microservices): Remove unnecessary exception filter priority changes

6cf7ad5

Remove the changes to exception filter handling in RPC exceptions handleras the current behavior is the intended behavior according to maintainerfeedback.Signed-off-by: snowykte0426 <snowykte0426@naver.com>

kamilmysliwiec added type: enhancement 🐺 scope: websockets status: blocked 🚫 labels

Sep 16, 2025

Labels

scope: websockets status: blocked 🚫type: enhancement 🐺

Movatterモバイル変換

Uh oh!

feat(websockets): add disconnect reason parameter to OnGatewayDisconnect#15451

Are you sure you want to change the base?

feat(websockets): add disconnect reason parameter to OnGatewayDisconnect#15451

Uh oh!

Conversation

snowykte0426 commentedJul 24, 2025• edited by kamilmysliwiecLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

PR Checklist

PR Type

What is the current behavior?

What is the new behavior?

Changes:

Usage:

Common Disconnect Reasons:

Does this PR introduce a breaking change?

Other information

Implementation Details:

Uh oh!

coveralls commentedJul 24, 2025• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Pull Request Test Coverage Report forBuild ccc32411-c048-48b5-946a-1ddf86b11307

Details

💛 -Coveralls

Uh oh!

kamilmysliwiecJul 25, 2025

Choose a reason for hiding this comment

Uh oh!

snowykte0426Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

kamilmysliwiecJul 25, 2025

Choose a reason for hiding this comment

Uh oh!

snowykte0426Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

kamilmysliwiecJul 25, 2025

Choose a reason for hiding this comment

Uh oh!

snowykte0426Jul 25, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

snowykte0426 commentedJul 24, 2025•
edited by kamilmysliwiec
Loading

coveralls commentedJul 24, 2025•
edited
Loading