feat(nestjs): Support WebSocket errors in SentryGlobalFilter (#22224)

Fixes #16067

`SentryGlobalFilter` now handles WebSocket exceptions without delegating
them to Nest's HTTP `BaseExceptionFilter`.

Unexpected gateway errors are captured with the
`auto.ws.nestjs.global_filter` mechanism and emit a generic error
response. Expected `WsException` responses are preserved without being
reported to Sentry. `WsException` is detected by shape so
`@nestjs/websockets` does not become a required dependency.

Unit and NestJS WebSocket E2E coverage was added for unexpected errors,
expected `WsException` values, and HTTP exceptions raised in a WebSocket
context.

*Root cause*: WebSocket exceptions were delegated to an HTTP exception
filter which expects an HTTP adapter and cannot correctly respond
through a WebSocket client.

Author: psh4607

dev-packages/e2e-tests/test-applications/nestjs-websockets/src/app.gateway.ts

@@ -1,13 +1,21 @@
-import { SubscribeMessage, WebSocketGateway, MessageBody } from '@nestjs/websockets';
+import { UseFilters } from '@nestjs/common';
+import { MessageBody, SubscribeMessage, WebSocketGateway, WsException } from '@nestjs/websockets';
 import * as Sentry from '@sentry/nestjs';
+import { SentryGlobalFilter } from '@sentry/nestjs/setup';
 
+@UseFilters(new SentryGlobalFilter())
 @WebSocketGateway()
 export class AppGateway {
   @SubscribeMessage('test-exception')
   handleTestException() {
     throw new Error('This is an exception in a WebSocket handler');
   }
 
+  @SubscribeMessage('test-ws-exception')
+  handleWsException() {
+    throw new WsException('Expected WebSocket exception');
+  }
+
   @SubscribeMessage('test-manual-capture')
   handleManualCapture() {
     try {

dev-packages/e2e-tests/test-applications/nestjs-websockets/tests/errors.test.ts

@@ -22,16 +22,39 @@ test('Captures manually reported error in WebSocket gateway handler', async ({ b
   socket.disconnect();
 });
 
+test('Automatically captures unexpected errors in WebSocket gateway handlers', async ({ baseURL }) => {
+  const errorPromise = waitForError('nestjs-websockets', event => {
+    return event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler';
+  });
+
+  const socket = io(baseURL!);
+  await new Promise<void>(resolve => socket.on('connect', resolve));
+
+  socket.emit('test-exception', {});
+
+  const error = await errorPromise;
+
+  expect(error.exception?.values).toHaveLength(1);
+  expect(error.exception?.values?.[0]?.type).toBe('Error');
+  expect(error.exception?.values?.[0]?.value).toBe('This is an exception in a WebSocket handler');
+  expect(error.exception?.values?.[0]?.mechanism).toEqual({
+    handled: false,
+    type: 'auto.ws.nestjs.global_filter',
+  });
+
+  socket.disconnect();
+});
+
 // There is no good mechanism to verify that an event was NOT sent to Sentry.
-// The idea here is that we first send a message that triggers an exception which won't be auto-captured,
+// The idea here is that we first send a message that triggers an expected exception which won't be auto-captured,
 // and then send a message that triggers a manually captured error which will be sent to Sentry.
 // If the manually captured error arrives, we can deduce that the first exception was not sent,
 // because Socket.IO guarantees message ordering: https://socket.io/docs/v4/delivery-guarantees
-test('Does not automatically capture exceptions in WebSocket gateway handler', async ({ baseURL }) => {
+test('Does not automatically capture expected WebSocket exceptions', async ({ baseURL }) => {
   let errorEventOccurred = false;
 
   waitForError('nestjs-websockets', event => {
-    if (!event.type && event.exception?.values?.[0]?.value === 'This is an exception in a WebSocket handler') {
+    if (!event.type && event.exception?.values?.[0]?.value === 'Expected WebSocket exception') {
       errorEventOccurred = true;
     }
 
@@ -45,7 +68,7 @@ test('Does not automatically capture exceptions in WebSocket gateway handler', a
   const socket = io(baseURL!);
   await new Promise<void>(resolve => socket.on('connect', resolve));
 
-  socket.emit('test-exception', {});
+  socket.emit('test-ws-exception', {});
   socket.emit('test-manual-capture', {});
   await manualCapturePromise;
 

packages/nestjs/src/helpers.ts

@@ -25,10 +25,24 @@ export function isExpectedError(exception: unknown): boolean {
     return true;
   }
 
-  // RpcException
-  if (typeof ex.getError === 'function' && typeof ex.initMessage === 'function') {
+  if (isWsOrRpcException(exception)) {
     return true;
   }
 
   return false;
 }
+
+/**
+ * Determines if the exception is a WsException or RpcException, which have the same shape.
+ * Both have `getError()` and `initMessage()` methods.
+ *
+ * We use duck-typing to avoid importing from `@nestjs/websockets` or `@nestjs/microservices`.
+ */
+export function isWsOrRpcException(exception: unknown): boolean {
+  if (typeof exception !== 'object' || exception === null) {
+    return false;
+  }
+
+  const ex = exception as Record<string, unknown>;
+  return typeof ex.getError === 'function' && typeof ex.initMessage === 'function';
+}

packages/nestjs/src/setup.ts

@@ -10,7 +10,7 @@ import { Catch, Global, HttpException, Injectable, Logger, Module } from '@nestj
 import { APP_INTERCEPTOR, BaseExceptionFilter } from '@nestjs/core';
 import { captureException, debug, getDefaultIsolationScope, getIsolationScope } from '@sentry/core';
 import type { Observable } from 'rxjs';
-import { isExpectedError } from './helpers';
+import { isExpectedError, isWsOrRpcException } from './helpers';
 
 // Partial extract of FastifyRequest interface
 // https://github.com/fastify/fastify/blob/87f9f20687c938828f1138f91682d568d2a31e53/types/request.d.ts#L41
@@ -152,6 +152,33 @@ class SentryGlobalFilter extends BaseExceptionFilter {
       return;
     }
 
+    if (contextType === 'ws') {
+      if (!isExpectedError(exception)) {
+        captureException(exception, {
+          mechanism: {
+            handled: false,
+            type: 'auto.ws.nestjs.global_filter',
+          },
+        });
+      }
+
+      const client = host.switchToWs().getClient<{ emit?: (event: string, data: unknown) => void }>();
+
+      if (isWsOrRpcException(exception)) {
+        const result = (exception as { getError: () => unknown }).getError();
+        const response = typeof result === 'object' && result !== null ? result : { status: 'error', message: result };
+        client.emit?.('exception', response);
+        return;
+      }
+
+      if (exception instanceof Error) {
+        this._logger.error(exception.message, exception.stack);
+      }
+
+      client.emit?.('exception', { status: 'error', message: 'Internal server error' });
+      return;
+    }
+
     // HTTP exceptions
     if (!isExpectedError(exception)) {
       captureException(exception, {

packages/nestjs/test/sentry-global-filter.test.ts

@@ -8,6 +8,7 @@ import { SentryGlobalFilter } from '../src/setup';
 
 vi.mock('../src/helpers', () => ({
   isExpectedError: vi.fn(),
+  isWsOrRpcException: vi.fn(),
 }));
 
 vi.mock('@sentry/core', () => ({
@@ -27,6 +28,7 @@ describe('SentryGlobalFilter', () => {
   let mockLoggerError: any;
   let mockLoggerWarn: any;
   let isExpectedErrorMock: any;
+  let isWsOrRpcExceptionMock: any;
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -57,6 +59,7 @@ describe('SentryGlobalFilter', () => {
     mockCaptureException = vi.spyOn(SentryCore, 'captureException').mockReturnValue('mock-event-id');
 
     isExpectedErrorMock = vi.mocked(Helpers.isExpectedError).mockImplementation(() => false);
+    isWsOrRpcExceptionMock = vi.mocked(Helpers.isWsOrRpcException).mockImplementation(() => false);
   });
 
   describe('HTTP context', () => {
@@ -237,4 +240,86 @@ describe('SentryGlobalFilter', () => {
       expect(mockCaptureException).not.toHaveBeenCalled();
     });
   });
+
+  describe('WebSocket context', () => {
+    let mockEmit: ReturnType<typeof vi.fn>;
+
+    beforeEach(() => {
+      mockEmit = vi.fn();
+      vi.mocked(mockArgumentsHost.getType).mockReturnValue('ws');
+      vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+        getClient: () => ({ emit: mockEmit }),
+        getData: vi.fn(),
+        getPattern: vi.fn(),
+      });
+    });
+
+    it('captures unexpected errors and emits a generic error response', () => {
+      const error = new Error('Test WebSocket error');
+
+      filter.catch(error, mockArgumentsHost);
+
+      expect(mockCaptureException).toHaveBeenCalledWith(error, {
+        mechanism: {
+          handled: false,
+          type: 'auto.ws.nestjs.global_filter',
+        },
+      });
+      expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+      expect(mockEmit).toHaveBeenCalledWith('exception', {
+        status: 'error',
+        message: 'Internal server error',
+      });
+    });
+
+    it('does not capture expected WebSocket exceptions and emits their response', () => {
+      isExpectedErrorMock.mockReturnValueOnce(true);
+      isWsOrRpcExceptionMock.mockReturnValueOnce(true);
+      const exception = {
+        getError: () => 'Expected WebSocket exception',
+        initMessage: vi.fn(),
+      };
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockCaptureException).not.toHaveBeenCalled();
+      expect(mockEmit).toHaveBeenCalledWith('exception', {
+        status: 'error',
+        message: 'Expected WebSocket exception',
+      });
+    });
+
+    it('does not capture HTTP exceptions and emits a generic error response', () => {
+      isExpectedErrorMock.mockReturnValueOnce(true);
+      const exception = new HttpException('Bad request', HttpStatus.BAD_REQUEST);
+
+      filter.catch(exception, mockArgumentsHost);
+
+      expect(mockCaptureException).not.toHaveBeenCalled();
+      expect(mockLoggerError).toHaveBeenCalledWith(exception.message, exception.stack);
+      expect(mockEmit).toHaveBeenCalledWith('exception', {
+        status: 'error',
+        message: 'Internal server error',
+      });
+    });
+
+    it('captures unexpected errors when the WebSocket client cannot emit', () => {
+      vi.mocked(mockArgumentsHost.switchToWs).mockReturnValue({
+        getClient: () => ({}),
+        getData: vi.fn(),
+        getPattern: vi.fn(),
+      });
+      const error = new Error('WebSocket adapter without emit');
+
+      filter.catch(error, mockArgumentsHost);
+
+      expect(mockCaptureException).toHaveBeenCalledWith(error, {
+        mechanism: {
+          handled: false,
+          type: 'auto.ws.nestjs.global_filter',
+        },
+      });
+      expect(mockLoggerError).toHaveBeenCalledWith(error.message, error.stack);
+    });
+  });
 });