@nestjs/websockets 12.1.3 → 12.2.0

package/constants.d.ts

@@ -10,3 +10,4 @@ export declare const CONNECTION_EVENT = "connection";
 export declare const DISCONNECT_EVENT = "disconnect";
 export declare const CLOSE_EVENT = "close";
 export declare const ERROR_EVENT = "error";
+export declare const DEFAULT_MAX_CONCURRENT_MESSAGES = 1000;

package/constants.js

@@ -11,3 +11,5 @@ export const CONNECTION_EVENT = 'connection';
 export const DISCONNECT_EVENT = 'disconnect';
 export const CLOSE_EVENT = 'close';
 export const ERROR_EVENT = 'error';
+// How many messages of a client an adapter handles at the same time
+export const DEFAULT_MAX_CONCURRENT_MESSAGES = 1000;

package/exceptions/base-ws-exception-filter.d.ts

@@ -62,6 +62,13 @@ export declare class BaseWsExceptionFilter<TError = any> implements WsExceptionF
         emit?: Function;
         send?: Function;
     }>(client: TClient, event: string, payload: unknown): void;
+    /**
+     * Sends the error payload, and sends it again without the "cause" when that
+     * fails. The cause echoes the client's message, which `JSON.parse` accepts
+     * at any depth, while `JSON.stringify` and the Socket.IO encoder overflow
+     * the stack on it.
+     */
+    private emitErrorPayload;
     /**
      * Determines whether the given client is a native WebSocket (e.g. from the
      * `ws` package) as opposed to a Socket.IO socket. Native WebSocket objects

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

@@ -41,7 +41,7 @@ export class BaseWsExceptionFilter {
         if (this.options?.includeCause && cause) {
             payload.cause = this.options.causeFactory(cause.pattern, cause.data);
         }
-        this.emitMessage(client, 'exception', payload);
+        this.emitErrorPayload(client, payload);
     }
     handleUnknownError(exception, client, data) {
         const status = 'error';
@@ -52,11 +52,12 @@ export class BaseWsExceptionFilter {
         if (this.options?.includeCause && data) {
             payload.cause = this.options.causeFactory(data.pattern, data.data);
         }
-        this.emitMessage(client, 'exception', payload);
+        // Logged first, so that a reply that cannot be sent never hides it
         if (!(exception instanceof IntrinsicException)) {
             const logger = BaseWsExceptionFilter.logger;
             logger.error(exception);
         }
+        this.emitErrorPayload(client, payload);
     }
     isExceptionObject(err) {
         return isObject(err) && !!err.message;
@@ -82,6 +83,27 @@ export class BaseWsExceptionFilter {
             client.emit(event, payload);
         }
     }
+    /**
+     * Sends the error payload, and sends it again without the "cause" when that
+     * fails. The cause echoes the client's message, which `JSON.parse` accepts
+     * at any depth, while `JSON.stringify` and the Socket.IO encoder overflow
+     * the stack on it.
+     */
+    emitErrorPayload(client, payload) {
+        try {
+            this.emitMessage(client, 'exception', payload);
+        }
+        catch (err) {
+            // Without a cause, the payload holds nothing the client sent
+            if (!('cause' in payload)) {
+                throw err;
+            }
+            this.emitMessage(client, 'exception', {
+                status: payload.status,
+                message: payload.message,
+            });
+        }
+    }
     /**
      * Determines whether the given client is a native WebSocket (e.g. from the
      * `ws` package) as opposed to a Socket.IO socket. Native WebSocket objects

package/factories/ws-params-factory.js

@@ -1,5 +1,20 @@
 import { WsParamtype } from '../enums/ws-paramtype.enum.js';
-import { isFunction } from '@nestjs/common/internal';
+import { isFunction, isNil, isObject } from '@nestjs/common/internal';
+/**
+ * A key picks a property of an object payload. Of an array, a Buffer or a
+ * primitive the client sent instead, it picks only an own property (an
+ * element, a length), not a prototype member: `Buffer#parent` exposes memory
+ * shared with other requests, and a built-in function such as
+ * `Array.prototype.values` passes for a DTO without required properties.
+ * Objects keep resolving inherited properties, as a custom message parser may
+ * build class instances.
+ */
+const getPayloadProperty = (payload, key) => (isObject(payload) &&
+    !Array.isArray(payload) &&
+    !ArrayBuffer.isView(payload)) ||
+    (!isNil(payload) && Object.hasOwn(Object(payload), key))
+    ? payload[key]
+    : undefined;
 export class WsParamsFactory {
     exchangeKeyForValue(type, data, args) {
         if (!args) {
@@ -9,7 +24,7 @@ export class WsParamsFactory {
             case WsParamtype.SOCKET:
                 return args[0];
             case WsParamtype.PAYLOAD:
-                return data ? args[1]?.[data] : args[1];
+                return data ? getPayloadProperty(args[1], data) : args[1];
             case WsParamtype.ACK: {
                 return args.find(arg => isFunction(arg));
             }

package/interfaces/hooks/on-gateway-connection.interface.d.ts

@@ -1,4 +1,16 @@
 /**
+ * Interface defining the method called for each client that connects to the
+ * gateway.
+ *
+ * The hook doesn't hold back the client's messages: they are handled as they
+ * arrive, even while an async `handleConnection()` is still pending. Use
+ * guards to check each message, or connection-level middleware to reject a
+ * client before any of its messages is handled: socket.io's `server.use()` in
+ * `afterInit()`, or, with `WsAdapter`, a `verifyClient` function in the
+ * `@WebSocketGateway()` options.
+ *
+ * @see [Lifecycle hooks](https://docs.nestjs.com/websockets/gateways#lifecycle-hooks)
+ *
  * @publicApi
  */
 export interface OnGatewayConnection<T = any> {

package/internal.d.ts

@@ -6,3 +6,4 @@
  * @module
  */
 export * from './constants.js';
+export * from './utils/merge-map-bounded.util.js';

package/internal.js

@@ -6,3 +6,4 @@
  * @module
  */
 export * from './constants.js';
+export * from './utils/merge-map-bounded.util.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs/websockets",
-  "version": "12.1.3",
+  "version": "12.2.0",
   "description": "Nest - modern, fast, powerful node.js web framework (@websockets)",
   "author": "Kamil Mysliwiec",
   "license": "MIT",
@@ -8,6 +8,7 @@
   "main": "./index.js",
   "exports": {
     ".": "./index.js",
+    "./package.json": "./package.json",
     "./internal": "./internal.js",
     "./*.js": "./*.js",
     "./*": "./*.js"
@@ -26,8 +27,8 @@
     "tslib": "2.8.1"
   },
   "devDependencies": {
-    "@nestjs/common": "12.1.3",
-    "@nestjs/core": "12.1.3"
+    "@nestjs/common": "12.2.0",
+    "@nestjs/core": "12.2.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^12.0.0",
@@ -41,5 +42,5 @@
       "optional": true
     }
   },
-  "gitHead": "4514623279f6087808e3c8f08fbf9f37d3c17482"
+  "gitHead": "af37111368de7fd2dfab0bdec2f530c7845510c2"
 }

package/utils/merge-map-bounded.util.d.ts

@@ -0,0 +1,12 @@
+import { type ObservableInput, type OperatorFunction } from 'rxjs';
+/**
+ * `mergeMap(project, concurrent)` for the messages of a client, which decides
+ * how many arrive before the first one has been handled. `mergeMap()` removes
+ * each completed inner subscription from an array of all the active ones, and
+ * `shift()`s each waiting value off an array of all the waiting ones, so a
+ * burst costs time quadratic in its size. Here at most `concurrent` inner
+ * subscriptions are active, and the values that wait for their turn are kept
+ * in a linked list. `onBacklog` is told when values start and stop waiting,
+ * e.g. to stop reading from the client in the meantime.
+ */
+export declare function mergeMapBounded<T, R>(project: (value: T) => ObservableInput<R>, concurrent: number, onBacklog?: (isBacklogged: boolean) => void): OperatorFunction<T, R>;

package/utils/merge-map-bounded.util.js

@@ -0,0 +1,62 @@
+import { defer, Observable, } from 'rxjs';
+/**
+ * `mergeMap(project, concurrent)` for the messages of a client, which decides
+ * how many arrive before the first one has been handled. `mergeMap()` removes
+ * each completed inner subscription from an array of all the active ones, and
+ * `shift()`s each waiting value off an array of all the waiting ones, so a
+ * burst costs time quadratic in its size. Here at most `concurrent` inner
+ * subscriptions are active, and the values that wait for their turn are kept
+ * in a linked list. `onBacklog` is told when values start and stop waiting,
+ * e.g. to stop reading from the client in the meantime.
+ */
+export function mergeMapBounded(project, concurrent, onBacklog) {
+    return source => new Observable(subscriber => {
+        let head;
+        let tail;
+        let active = 0;
+        let isDraining = false;
+        let isSourceComplete = false;
+        let isBacklogged = false;
+        // A loop, not recursion: an inner observable may complete synchronously,
+        // and how many values wait is up to the client.
+        const drain = () => {
+            if (isDraining) {
+                return;
+            }
+            isDraining = true;
+            while (head && active < concurrent && !subscriber.closed) {
+                const { value } = head;
+                head = head.next;
+                active++;
+                subscriber.add(defer(() => project(value)).subscribe({
+                    next: result => subscriber.next(result),
+                    error: err => subscriber.error(err),
+                    complete: () => {
+                        active--;
+                        drain();
+                    },
+                }));
+            }
+            isDraining = false;
+            if (onBacklog && isBacklogged !== !!head) {
+                isBacklogged = !!head;
+                onBacklog(isBacklogged);
+            }
+            if (isSourceComplete && !head && active === 0) {
+                subscriber.complete();
+            }
+        };
+        subscriber.add(source.subscribe({
+            next: value => {
+                const waiting = { value };
+                tail = head ? (tail.next = waiting) : (head = waiting);
+                drain();
+            },
+            error: err => subscriber.error(err),
+            complete: () => {
+                isSourceComplete = true;
+                drain();
+            },
+        }));
+    });
+}

package/web-sockets-controller.d.ts

@@ -21,7 +21,6 @@ export declare class WebSocketsController {
     private readonly appOptions;
     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;
@@ -38,6 +37,7 @@ 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 logResolutionError;
     private areGlobalScopedEnhancersDurable;
     /**
      * Runs a lifecycle hook of a default-scoped gateway and passes the errors it

package/web-sockets-controller.js

@@ -21,7 +21,6 @@ export class WebSocketsController {
         timestamp: true,
     });
     metadataExplorer = new GatewayMetadataExplorer(new MetadataScanner());
-    exceptionFiltersCache = new WeakMap();
     pendingDisconnects = new WeakMap();
     constructor(socketServerProvider, config, contextCreator, container, injector, exceptionFiltersContext, graphInspector, appOptions = {}) {
         this.socketServerProvider = socketServerProvider;
@@ -86,7 +85,7 @@ export class WebSocketsController {
             message,
             methodName,
             callback: isStatic && !hasGlobalScopedEnhancers
-                ? this.contextCreator.create(instance, callback, moduleKey, methodName, STATIC_CONTEXT)
+                ? this.contextCreator.create(instance, callback, moduleKey, methodName, STATIC_CONTEXT, instanceWrapper.id)
                 : this.createRequestScopedHandler(instanceWrapper, moduleRef, moduleKey, methodName),
             isAckHandledManually,
         }));
@@ -207,6 +206,9 @@ export class WebSocketsController {
             ...this.getGlobalScopedEnhancers(),
         ];
         const pattern = Reflect.getMetadata(MESSAGE_METADATA, instance[methodName]) ?? 'unknown';
+        // Kept per gateway, not per handler function: gateways that inherit the
+        // handler from a base class can declare different filters
+        let exceptionFilter;
         return async (...args) => {
             const [client] = args;
             try {
@@ -217,14 +219,11 @@ export class WebSocketsController {
                 // 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);
+                await this.injector.waitForDeferredLoads(contextId);
                 return this.contextCreator.create(contextInstance, contextInstance[methodName], moduleKey, methodName, contextId, instanceWrapper.id)(...args);
             }
             catch (err) {
-                let exceptionFilter = this.exceptionFiltersCache.get(instance[methodName]);
-                if (!exceptionFilter) {
-                    exceptionFilter = this.exceptionFiltersContext.create(instance, instance[methodName], moduleKey);
-                    this.exceptionFiltersCache.set(instance[methodName], exceptionFilter);
-                }
+                exceptionFilter ??= this.exceptionFiltersContext.create(instance, instance[methodName], moduleKey);
                 // The context failed to resolve before `WsProxy` could append the
                 // pattern, so add it here the same way.
                 const host = new ExecutionContextHost([...args, pattern]);
@@ -244,6 +243,7 @@ export class WebSocketsController {
         return async (...args) => {
             const [client] = args;
             let contextId;
+            let isResolved = false;
             try {
                 contextId = this.getContextId(client, isTreeDurable);
                 if (methodName === 'handleDisconnect') {
@@ -252,6 +252,7 @@ export class WebSocketsController {
                 const contextInstance = isStatic
                     ? instance
                     : await this.injector.loadPerContext(instance, moduleRef, collection, contextId);
+                isResolved = true;
                 if (!isStatic) {
                     this.assignServerToProperties(contextInstance, server);
                 }
@@ -263,10 +264,26 @@ export class WebSocketsController {
                     // 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);
+                    this.logResolutionError(instance, methodName, err);
                     return;
                 }
-                this.handleLifecycleHookError(instance, moduleKey, methodName, args, err);
+                if (!isResolved && contextId) {
+                    // The gateway's enhancers are created in the context of the
+                    // connection along with it, so when it failed to resolve, its
+                    // filters have to be created here.
+                    try {
+                        await this.injector.loadEnhancersPerContext(instanceWrapper, contextId, instanceWrapper);
+                    }
+                    catch {
+                        this.logResolutionError(instance, methodName, err);
+                        return;
+                    }
+                }
+                // Built for each connection: a request-scoped filter is only
+                // constructed in the context of the connection, and the static one
+                // holds an empty placeholder
+                const exceptionFilter = this.exceptionFiltersContext.create(instance, targetCallback, moduleKey, contextId, instanceWrapper.id);
+                this.handleLifecycleHookError(exceptionFilter, methodName, args, err);
             }
             finally {
                 if (methodName === 'handleDisconnect' && contextId) {
@@ -275,6 +292,9 @@ export class WebSocketsController {
             }
         };
     }
+    logResolutionError(instance, methodName, err) {
+        this.logger.error(`Failed to resolve ${instance.constructor.name} on client ${methodName === 'handleConnection' ? 'connection' : 'disconnection'}`, err?.stack);
+    }
     // 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).
@@ -293,8 +313,14 @@ export class WebSocketsController {
         if (!hook) {
             return undefined;
         }
+        // Kept per gateway, not per hook function: gateways that inherit the
+        // hook from a base class can declare different filters
+        let exceptionFilter;
         return (...args) => {
-            const handleError = (err) => this.handleLifecycleHookError(instance, moduleKey, methodName, args, err);
+            const handleError = (err) => {
+                exceptionFilter ??= this.exceptionFiltersContext.create(instance, hook, moduleKey);
+                this.handleLifecycleHookError(exceptionFilter, methodName, args, err);
+            };
             try {
                 const result = hook.apply(instance, args);
                 return isFunction(result?.then)
@@ -306,14 +332,7 @@ export class WebSocketsController {
             }
         };
     }
-    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);
-        }
+    handleLifecycleHookError(exceptionFilter, methodName, args, err) {
         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