@nestjs/websockets 12.1.2 → 12.1.3

package/errors/ws-exception.js

@@ -15,9 +15,9 @@ export class WsException extends Error {
             this.message = this.error.message;
         }
         else if (this.constructor) {
-            this.message = this.constructor.name
-                .match(/[A-Z][a-z]+|[0-9]+/g)
-                .join(' ');
+            this.message =
+                this.constructor.name.match(/[A-Z][a-z]+|[0-9]+/g)?.join(' ') ??
+                    'Error';
         }
     }
     getError() {

package/exceptions/base-ws-exception-filter.js

@@ -10,9 +10,11 @@ export class BaseWsExceptionFilter {
     static logger = new Logger('WsExceptionsHandler');
     constructor(options = {}) {
         this.options = options;
-        this.options.includeCause = this.options.includeCause ?? true;
-        this.options.causeFactory =
-            this.options.causeFactory ?? ((pattern, data) => ({ pattern, data }));
+        this.options = {
+            ...this.options,
+            includeCause: this.options.includeCause ?? true,
+            causeFactory: this.options.causeFactory ?? ((pattern, data) => ({ pattern, data })),
+        };
     }
     catch(exception, host) {
         const client = host.switchToWs().getClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/websockets",
-  "version": "12.1.2",
+  "version": "12.1.3",
   "description": "Nest - modern, fast, powerful node.js web framework (@websockets)",
   "author": "Kamil Mysliwiec",
   "license": "MIT",
@@ -26,8 +26,8 @@
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@nestjs/common": "12.1.2",
-    "@nestjs/core": "12.1.2"
+    "@nestjs/common": "12.1.3",
+    "@nestjs/core": "12.1.3"
   },
   "peerDependencies": {
     "@nestjs/common": "^12.0.0",
@@ -41,5 +41,5 @@
       "optional": true
     }
   },
-  "gitHead": "8ab60aa1b2927fbe0e23135ffc65d610c623236a"
+  "gitHead": "4514623279f6087808e3c8f08fbf9f37d3c17482"
 }

package/web-sockets-controller.d.ts

@@ -22,6 +22,7 @@ export declare class WebSocketsController {
     private readonly logger;
     private readonly metadataExplorer;
     private readonly exceptionFiltersCache;
+    private readonly pendingDisconnects;
     constructor(socketServerProvider: SocketServerProvider, config: ApplicationConfig, contextCreator: WsContextCreator, container: NestContainer, injector: Injector, exceptionFiltersContext: ExceptionFiltersContext, graphInspector: GraphInspector, appOptions?: NestApplicationContextOptions);
     connectGatewayToServer(instanceWrapper: InstanceWrapper<NestGateway>, moduleKey: string): void;
     connectGatewayToServer(instance: NestGateway, metatype: Type<unknown> | Function, moduleKey: string, instanceWrapperId: string): void;
@@ -37,6 +38,15 @@ export declare class WebSocketsController {
     inspectEntrypointDefinitions(instance: NestGateway, port: number, messageHandlers: MessageMappingProperties[], instanceWrapperId: string): void;
     createRequestScopedHandler(instanceWrapper: InstanceWrapper<NestGateway>, moduleRef: Module, moduleKey: string, methodName: string): (...args: unknown[]) => Promise<void>;
     createRequestScopedEventHandler(instanceWrapper: InstanceWrapper<NestGateway>, moduleRef: Module, moduleKey: string, methodName: 'handleConnection' | 'handleDisconnect', server: object): (...args: unknown[]) => Promise<unknown>;
+    private areGlobalScopedEnhancersDurable;
+    /**
+     * Runs a lifecycle hook of a default-scoped gateway and passes the errors it
+     * throws or rejects with to the gateway's exception filters, as for message
+     * handlers. The hook still runs synchronously.
+     */
+    createStaticEventHandler(instance: NestGateway, moduleKey: string, methodName: 'handleConnection' | 'handleDisconnect'): ((...args: unknown[]) => unknown) | undefined;
+    private handleLifecycleHookError;
+    private getGlobalScopedEnhancers;
     getContextId<T extends Record<any, unknown> = any>(request: T, isTreeDurable: boolean): ContextId;
     private cleanupRequestScopedContext;
     private assignServerToProperties;

package/web-sockets-controller.js

@@ -1,9 +1,10 @@
 import { from as fromPromise, isObservable, of, } from 'rxjs';
 import { distinctUntilChanged, mergeAll } from 'rxjs/operators';
-import { GATEWAY_OPTIONS, PORT_METADATA } from './constants.js';
+import { GATEWAY_OPTIONS, MESSAGE_METADATA, PORT_METADATA, } from './constants.js';
 import { InvalidSocketPortException } from './errors/invalid-socket-port.exception.js';
 import { GatewayMetadataExplorer, } from './gateway-metadata-explorer.js';
 import { compareElementAt } from './utils/compare-element.util.js';
+import { isFunction } from '@nestjs/common/internal';
 import { Logger } from '@nestjs/common';
 import { ContextIdFactory, MetadataScanner, } from '@nestjs/core';
 import { ExecutionContextHost, REQUEST_CONTEXT_ID, STATIC_CONTEXT, } from '@nestjs/core/internal';
@@ -21,6 +22,7 @@ export class WebSocketsController {
     });
     metadataExplorer = new GatewayMetadataExplorer(new MetadataScanner());
     exceptionFiltersCache = new WeakMap();
+    pendingDisconnects = new WeakMap();
     constructor(socketServerProvider, config, contextCreator, container, injector, exceptionFiltersContext, graphInspector, appOptions = {}) {
         this.socketServerProvider = socketServerProvider;
         this.config = config;
@@ -54,6 +56,7 @@ export class WebSocketsController {
                 id: targetInstanceWrapperId,
                 isDependencyTreeStatic: () => true,
                 isDependencyTreeDurable: () => false,
+                getEnhancersMetadata: () => [],
             };
         const gatewayMetatype = metatype ?? instance.constructor;
         const options = Reflect.getMetadata(GATEWAY_OPTIONS, gatewayMetatype) || {};
@@ -72,15 +75,17 @@ export class WebSocketsController {
                 id: instanceWrapperId,
                 isDependencyTreeStatic: () => true,
                 isDependencyTreeDurable: () => false,
+                getEnhancersMetadata: () => [],
             };
         const { instance } = instanceWrapper;
         const nativeMessageHandlers = this.metadataExplorer.explore(instance);
         const isStatic = instanceWrapper.isDependencyTreeStatic();
+        const hasGlobalScopedEnhancers = this.getGlobalScopedEnhancers().length > 0;
         const moduleRef = this.container.getModuleByKey(moduleKey);
         const messageHandlers = nativeMessageHandlers.map(({ callback, isAckHandledManually, message, methodName }) => ({
             message,
             methodName,
-            callback: isStatic
+            callback: isStatic && !hasGlobalScopedEnhancers
                 ? this.contextCreator.create(instance, callback, moduleKey, methodName, STATIC_CONTEXT)
                 : this.createRequestScopedHandler(instanceWrapper, moduleRef, moduleKey, methodName),
             isAckHandledManually,
@@ -92,9 +97,9 @@ export class WebSocketsController {
         const observableServer = this.socketServerProvider.scanForSocketServer(options, port);
         this.assignServerToProperties(instance, observableServer.server);
         this.subscribeEvents(instanceWrapper, messageHandlers, observableServer, isStatic
-            ? instance.handleConnection?.bind(instance)
-            : this.createRequestScopedEventHandler(instanceWrapper, moduleRef, moduleKey, 'handleConnection', observableServer.server), isStatic
-            ? instance.handleDisconnect?.bind(instance)
+            ? this.createStaticEventHandler(instance, moduleKey, 'handleConnection')
+            : this.createRequestScopedEventHandler(instanceWrapper, moduleRef, moduleKey, 'handleConnection', observableServer.server), isStatic && !hasGlobalScopedEnhancers
+            ? this.createStaticEventHandler(instance, moduleKey, 'handleDisconnect')
             : this.createRequestScopedEventHandler(instanceWrapper, moduleRef, moduleKey, 'handleDisconnect', observableServer.server));
     }
     subscribeEvents(instanceWrapper, subscribersMap, observableServer, connectionHandler, disconnectHandler) {
@@ -193,12 +198,25 @@ export class WebSocketsController {
     createRequestScopedHandler(instanceWrapper, moduleRef, moduleKey, methodName) {
         const { instance } = instanceWrapper;
         const collection = moduleRef.providers;
-        const isTreeDurable = instanceWrapper.isDependencyTreeDurable();
+        const isStatic = instanceWrapper.isDependencyTreeStatic();
+        const isTreeDurable = isStatic
+            ? this.areGlobalScopedEnhancersDurable()
+            : instanceWrapper.isDependencyTreeDurable();
+        const scopedEnhancers = [
+            ...(isStatic ? instanceWrapper.getEnhancersMetadata() || [] : []),
+            ...this.getGlobalScopedEnhancers(),
+        ];
+        const pattern = Reflect.getMetadata(MESSAGE_METADATA, instance[methodName]) ?? 'unknown';
         return async (...args) => {
             const [client] = args;
             try {
                 const contextId = this.getContextId(client, isTreeDurable);
-                const contextInstance = await this.injector.loadPerContext(instance, moduleRef, collection, contextId);
+                const contextInstance = isStatic
+                    ? instance
+                    : await this.injector.loadPerContext(instance, moduleRef, collection, contextId);
+                // Resolve global enhancers without adding them to the gateway's dependency
+                // tree, so a singleton gateway keeps its state and lifecycle hooks.
+                await this.injector.loadEnhancersPerContext(instanceWrapper, contextId, instanceWrapper, scopedEnhancers);
                 return this.contextCreator.create(contextInstance, contextInstance[methodName], moduleKey, methodName, contextId, instanceWrapper.id)(...args);
             }
             catch (err) {
@@ -207,7 +225,9 @@ export class WebSocketsController {
                     exceptionFilter = this.exceptionFiltersContext.create(instance, instance[methodName], moduleKey);
                     this.exceptionFiltersCache.set(instance[methodName], exceptionFilter);
                 }
-                const host = new ExecutionContextHost(args);
+                // The context failed to resolve before `WsProxy` could append the
+                // pattern, so add it here the same way.
+                const host = new ExecutionContextHost([...args, pattern]);
                 host.setType('ws');
                 exceptionFilter.handle(err, host);
             }
@@ -216,30 +236,37 @@ export class WebSocketsController {
     createRequestScopedEventHandler(instanceWrapper, moduleRef, moduleKey, methodName, server) {
         const { instance } = instanceWrapper;
         const collection = moduleRef.providers;
-        const isTreeDurable = instanceWrapper.isDependencyTreeDurable();
+        const isStatic = instanceWrapper.isDependencyTreeStatic();
+        const isTreeDurable = isStatic
+            ? this.areGlobalScopedEnhancersDurable()
+            : instanceWrapper.isDependencyTreeDurable();
         const targetCallback = instance[methodName];
         return async (...args) => {
             const [client] = args;
             let contextId;
             try {
                 contextId = this.getContextId(client, isTreeDurable);
-                const contextInstance = await this.injector.loadPerContext(instance, moduleRef, collection, contextId);
-                this.assignServerToProperties(contextInstance, server);
+                if (methodName === 'handleDisconnect') {
+                    this.pendingDisconnects.set(contextId, (this.pendingDisconnects.get(contextId) ?? 0) + 1);
+                }
+                const contextInstance = isStatic
+                    ? instance
+                    : await this.injector.loadPerContext(instance, moduleRef, collection, contextId);
+                if (!isStatic) {
+                    this.assignServerToProperties(contextInstance, server);
+                }
                 const scopedMethod = contextInstance[methodName];
                 return await scopedMethod?.apply(contextInstance, args);
             }
             catch (err) {
                 if (!targetCallback) {
-                    throw err;
-                }
-                let exceptionFilter = this.exceptionFiltersCache.get(targetCallback);
-                if (!exceptionFilter) {
-                    exceptionFilter = this.exceptionFiltersContext.create(instance, targetCallback, moduleKey);
-                    this.exceptionFiltersCache.set(targetCallback, exceptionFilter);
+                    // The gateway failed to resolve and has no hook whose exception
+                    // filters could handle the error. Nothing awaits this handler, so
+                    // rethrowing would end as an unhandled rejection.
+                    this.logger.error(`Failed to resolve ${instance.constructor.name} on client ${methodName === 'handleConnection' ? 'connection' : 'disconnection'}`, err?.stack);
+                    return;
                 }
-                const host = new ExecutionContextHost(args);
-                host.setType('ws');
-                exceptionFilter.handle(err, host);
+                this.handleLifecycleHookError(instance, moduleKey, methodName, args, err);
             }
             finally {
                 if (methodName === 'handleDisconnect' && contextId) {
@@ -248,6 +275,63 @@ export class WebSocketsController {
             }
         };
     }
+    // A default-scoped gateway is resolved per connection only for its global
+    // scoped enhancers, so their trees decide whether the context is durable
+    // (mirrors InstanceWrapper#isDependencyTreeDurable).
+    areGlobalScopedEnhancersDurable() {
+        const scopedEnhancers = this.getGlobalScopedEnhancers().filter(wrapper => !wrapper.isDependencyTreeStatic());
+        return (scopedEnhancers.length > 0 &&
+            scopedEnhancers.every(wrapper => wrapper.isDependencyTreeDurable()));
+    }
+    /**
+     * Runs a lifecycle hook of a default-scoped gateway and passes the errors it
+     * throws or rejects with to the gateway's exception filters, as for message
+     * handlers. The hook still runs synchronously.
+     */
+    createStaticEventHandler(instance, moduleKey, methodName) {
+        const hook = instance[methodName];
+        if (!hook) {
+            return undefined;
+        }
+        return (...args) => {
+            const handleError = (err) => this.handleLifecycleHookError(instance, moduleKey, methodName, args, err);
+            try {
+                const result = hook.apply(instance, args);
+                return isFunction(result?.then)
+                    ? result.catch(handleError)
+                    : result;
+            }
+            catch (err) {
+                handleError(err);
+            }
+        };
+    }
+    handleLifecycleHookError(instance, moduleKey, methodName, args, err) {
+        // Only called for gateways that implement the hook
+        const targetCallback = instance[methodName];
+        let exceptionFilter = this.exceptionFiltersCache.get(targetCallback);
+        if (!exceptionFilter) {
+            exceptionFilter = this.exceptionFiltersContext.create(instance, targetCallback, moduleKey);
+            this.exceptionFiltersCache.set(targetCallback, exceptionFilter);
+        }
+        const [client, disconnectReason] = args;
+        // Client first, data second and the pattern last, as for message handlers.
+        // With the raw hook arguments, the filter would send the last one (the
+        // socket itself with socket.io, the upgrade request with ws) back to the
+        // client as the pattern. The disconnect reason is safe to pass as data,
+        // as nothing is sent to a client that has already disconnected.
+        const data = methodName === 'handleDisconnect' ? disconnectReason : undefined;
+        const host = new ExecutionContextHost([client, data, methodName]);
+        host.setType('ws');
+        exceptionFilter.handle(err, host);
+    }
+    getGlobalScopedEnhancers() {
+        return [
+            ...this.config.getGlobalRequestGuards(),
+            ...this.config.getGlobalRequestPipes(),
+            ...this.config.getGlobalRequestInterceptors(),
+        ];
+    }
     getContextId(request, isTreeDurable) {
         const contextId = ContextIdFactory.getByRequest(request);
         if (!request[REQUEST_CONTEXT_ID]) {
@@ -264,8 +348,18 @@ export class WebSocketsController {
         }
         return contextId;
     }
-    cleanupRequestScopedContext(_instanceWrapper, _contextId, request) {
-        Reflect.deleteProperty(request, REQUEST_CONTEXT_ID);
+    cleanupRequestScopedContext(_instanceWrapper, contextId, request) {
+        const remaining = (this.pendingDisconnects.get(contextId) ?? 1) - 1;
+        if (remaining > 0) {
+            this.pendingDisconnects.set(contextId, remaining);
+            return;
+        }
+        this.pendingDisconnects.delete(contextId);
+        // Other gateways can still be executing their asynchronous disconnect hooks.
+        // A finished cycle must also never remove a newer context on the same client.
+        if (request[REQUEST_CONTEXT_ID] === contextId) {
+            Reflect.deleteProperty(request, REQUEST_CONTEXT_ID);
+        }
     }
     assignServerToProperties(instance, server) {
         for (const propertyKey of this.metadataExplorer.scanForServerHooks(instance)) {