@fluojs/websockets 1.0.0-beta.1

package/dist/node/node-service.js

@@ -0,0 +1,892 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { randomUUID } from 'node:crypto';
+import { createServer as createHttpServer } from 'node:http';
+import { Inject } from '@fluojs/core';
+import { APPLICATION_LOGGER, COMPILED_MODULES, HTTP_APPLICATION_ADAPTER, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { WebSocket, WebSocketServer } from 'ws';
+import { dispatchGatewayDisconnect, dispatchGatewayMessage, discoverGatewayDescriptors, isFinitePositiveInteger, normalizeGatewayPath, resolveGatewayInstance, runGatewayHandlers } from '../internal/shared.js';
+import { WEBSOCKET_OPTIONS_INTERNAL } from '../options-token.internal.js';
+function resolveHttpStatusText(status) {
+  switch (status) {
+    case 400:
+      return 'Bad Request';
+    case 401:
+      return 'Unauthorized';
+    case 403:
+      return 'Forbidden';
+    case 404:
+      return 'Not Found';
+    case 413:
+      return 'Payload Too Large';
+    case 426:
+      return 'Upgrade Required';
+    case 429:
+      return 'Too Many Requests';
+    case 500:
+      return 'Internal Server Error';
+    case 503:
+      return 'Service Unavailable';
+    default:
+      return 'Rejected';
+  }
+}
+function isUpgradeRejection(value) {
+  return typeof value === 'object' && value !== null && 'status' in value;
+}
+function isHttpExceptionLike(error) {
+  return typeof error === 'object' && error !== null && 'message' in error && 'status' in error;
+}
+function resolveMessageByteLength(data) {
+  if (typeof data === 'string') {
+    return Buffer.byteLength(data);
+  }
+  if (data instanceof ArrayBuffer) {
+    return data.byteLength;
+  }
+  if (Array.isArray(data)) {
+    return data.reduce((length, chunk) => length + chunk.byteLength, 0);
+  }
+  return data.byteLength;
+}
+const DEFAULT_WEBSOCKET_SHUTDOWN_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET = 256;
+const DEFAULT_MAX_BUFFERED_AMOUNT_BYTES = 1_048_576;
+const DEFAULT_MAX_WEBSOCKET_CONNECTIONS = 1_000;
+const DEFAULT_MAX_WEBSOCKET_PAYLOAD_BYTES = 1_048_576;
+const DEFAULT_WEBSOCKET_HEARTBEAT_INTERVAL_MS = 30_000;
+function hasNodeUpgradeServer(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const maybeServer = value;
+  return typeof maybeServer.on === 'function' && typeof maybeServer.off === 'function';
+}
+function resolveServerBackedRealtimeCapability(adapter) {
+  if (typeof adapter.getRealtimeCapability !== 'function') {
+    throw new Error('WebSocket gateway bootstrap requires an HTTP adapter with getRealtimeCapability(). Use a platform adapter that exposes a server-backed realtime capability.');
+  }
+  const capability = adapter.getRealtimeCapability();
+  if (capability.kind !== 'server-backed') {
+    throw new Error(`WebSocket gateway bootstrap requires a server-backed realtime capability. ${capability.reason}`);
+  }
+  return capability;
+}
+function rejectUpgradeRequest(socket) {
+  if (socket.destroyed || socket.writableEnded) {
+    return;
+  }
+  socket.write('HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
+  socket.destroy();
+}
+function rejectBadUpgradeRequest(socket) {
+  if (socket.destroyed || socket.writableEnded) {
+    return;
+  }
+  socket.write('HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
+  socket.destroy();
+}
+function rejectUpgradeRequestWithStatus(socket, rejection) {
+  if (socket.destroyed || socket.writableEnded) {
+    return;
+  }
+  const body = rejection.body ?? '';
+  let response = `HTTP/1.1 ${String(rejection.status)} ${resolveHttpStatusText(rejection.status)}\r\n`;
+  for (const [header, value] of Object.entries(rejection.headers ?? {})) {
+    response += `${header}: ${value}\r\n`;
+  }
+  response += `Connection: close\r\nContent-Length: ${String(Buffer.byteLength(body))}\r\n\r\n${body}`;
+  socket.write(response);
+  socket.destroy();
+}
+
+/**
+ * Lifecycle service that discovers WebSocket gateways, attaches upgrade listeners, and manages room state.
+ *
+ * @remarks
+ * This service preserves the documented runtime behavior for shared-path discovery order, optional server-backed
+ * listeners, buffered pre-ready events, heartbeat handling, and graceful shutdown.
+ */
+let _NodeWebSocketGateway;
+class NodeWebSocketGatewayLifecycleService {
+  static {
+    [_NodeWebSocketGateway, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, HTTP_APPLICATION_ADAPTER, WEBSOCKET_OPTIONS_INTERNAL)], []).c;
+  }
+  attachments = [];
+  heartbeatTimer;
+  ownedUpgradeServers = [];
+  pendingUpgradeReservations = 0;
+  pingPending = new Set();
+  pingSentAt = new Map();
+  roomSockets = new Map();
+  shutdownPromise;
+  socketRegistry = new Map();
+  socketRooms = new Map();
+  upgradeListener;
+  upgradeServer;
+  constructor(runtimeContainer, compiledModules, logger, adapter, moduleOptions) {
+    this.runtimeContainer = runtimeContainer;
+    this.compiledModules = compiledModules;
+    this.logger = logger;
+    this.adapter = adapter;
+    this.moduleOptions = moduleOptions;
+  }
+
+  /**
+   * Discovers gateway classes and attaches their WebSocket servers once per application lifecycle.
+   */
+  async onApplicationBootstrap() {
+    if (this.upgradeListener || this.ownedUpgradeServers.length > 0 || this.attachments.length > 0) {
+      return;
+    }
+    const descriptors = discoverGatewayDescriptors(this.compiledModules, this.logger, 'WebSocketGatewayLifecycleService');
+    if (descriptors.length === 0) {
+      return;
+    }
+    await this.prepareGatewayAttachments(descriptors);
+    this.startHeartbeatIfEnabled();
+  }
+
+  /**
+   * Shuts down websocket listeners and connection tracking during application shutdown.
+   */
+  async onApplicationShutdown() {
+    await this.shutdown();
+  }
+
+  /**
+   * Shuts down websocket listeners and connection tracking when the containing module is destroyed.
+   */
+  async onModuleDestroy() {
+    await this.shutdown();
+  }
+  async prepareGatewayAttachments(descriptors) {
+    const attachmentGroups = this.buildGatewayAttachmentGroups(descriptors);
+    for (const group of attachmentGroups.values()) {
+      this.attachConnectionHandlersToServers(group.attachmentsByPath);
+    }
+    await this.attachGatewayServers(attachmentGroups);
+    this.attachments = Array.from(attachmentGroups.values()).flatMap(group => Array.from(group.attachmentsByPath.values()));
+  }
+  async attachGatewayServers(attachmentGroups) {
+    for (const group of attachmentGroups.values()) {
+      if (group.target.kind === 'application-server') {
+        this.attachUpgradeServerListener(group.attachmentsByPath);
+        continue;
+      }
+      await this.attachOwnedGatewayServerListener(group);
+    }
+  }
+  attachUpgradeServerListener(attachmentsByPath) {
+    const upgradeServer = this.resolveUpgradeServer();
+    const listener = this.createUpgradeListener(upgradeServer, attachmentsByPath);
+    upgradeServer.on('upgrade', listener);
+    this.upgradeServer = upgradeServer;
+    this.upgradeListener = listener;
+  }
+  async attachOwnedGatewayServerListener(group) {
+    if (group.target.kind !== 'owned-server') {
+      return;
+    }
+    const server = createOwnedGatewayServer();
+    const listener = this.createUpgradeListener(server, group.attachmentsByPath);
+    server.on('upgrade', listener);
+    await this.listenOwnedGatewayServer(server, group.target.port);
+    this.ownedUpgradeServers.push({
+      listener,
+      port: group.target.port,
+      server
+    });
+  }
+  startHeartbeatIfEnabled() {
+    const heartbeat = this.moduleOptions.heartbeat;
+    if (heartbeat?.enabled === false) {
+      return;
+    }
+    const intervalMs = heartbeat?.intervalMs ?? DEFAULT_WEBSOCKET_HEARTBEAT_INTERVAL_MS;
+    const timeoutMs = heartbeat?.timeoutMs ?? intervalMs;
+    this.startHeartbeat(intervalMs, timeoutMs);
+  }
+  buildGatewayAttachmentGroups(descriptors) {
+    const attachmentGroups = new Map();
+    for (const descriptor of descriptors) {
+      const bindingTarget = this.resolveBindingTarget(descriptor);
+      const group = attachmentGroups.get(bindingTarget.key) ?? this.createAttachmentGroup(bindingTarget);
+      const current = group.attachmentsByPath.get(descriptor.path);
+      if (current) {
+        current.descriptors.push(descriptor);
+        attachmentGroups.set(bindingTarget.key, group);
+        continue;
+      }
+      group.attachmentsByPath.set(descriptor.path, {
+        bindingTarget,
+        descriptors: [descriptor],
+        path: descriptor.path,
+        server: new WebSocketServer({
+          maxPayload: this.resolveMaxPayloadBytes(),
+          noServer: true
+        })
+      });
+      attachmentGroups.set(bindingTarget.key, group);
+    }
+    return attachmentGroups;
+  }
+  createAttachmentGroup(target) {
+    return {
+      attachmentsByPath: new Map(),
+      target
+    };
+  }
+  resolveBindingTarget(descriptor) {
+    const serverBacked = descriptor.serverBacked;
+    if (!serverBacked) {
+      return {
+        key: 'application-server',
+        kind: 'application-server'
+      };
+    }
+    const port = this.resolveServerBackedPort(descriptor.path, serverBacked);
+    return {
+      key: `owned-server:${String(port)}`,
+      kind: 'owned-server',
+      port
+    };
+  }
+  resolveServerBackedPort(path, options) {
+    if (!isFinitePositiveInteger(options.port)) {
+      throw new Error(`WebSocket gateway serverBacked.port for path ${path} must be a finite positive integer.`);
+    }
+    return options.port;
+  }
+  attachConnectionHandlersToServers(attachmentsByPath) {
+    for (const attachment of attachmentsByPath.values()) {
+      attachment.server.on('connection', (socket, request) => {
+        void this.bindConnectionHandlers(attachment.descriptors, socket, request);
+      });
+    }
+  }
+  createUpgradeListener(upgradeServer, attachmentsByPath) {
+    return (request, socket, head) => {
+      socket.pause();
+      void this.handleUpgradeRequest(upgradeServer, attachmentsByPath, request, socket, head).catch(error => {
+        this.logger.error('WebSocket upgrade admission failed.', error, 'WebSocketGatewayLifecycleService');
+        rejectUpgradeRequestWithStatus(socket, {
+          body: 'Internal server error',
+          status: 500
+        });
+      }).finally(() => {
+        if (!socket.destroyed) {
+          socket.resume();
+        }
+      });
+    };
+  }
+  async handleUpgradeRequest(upgradeServer, attachmentsByPath, request, socket, head) {
+    let attachment;
+    let targetPath;
+    try {
+      const url = new URL(request.url ?? '/', 'http://localhost');
+      targetPath = normalizeGatewayPath(url.pathname);
+      attachment = attachmentsByPath.get(targetPath);
+    } catch {
+      rejectBadUpgradeRequest(socket);
+      return;
+    }
+    if (!attachment) {
+      if (upgradeServer.listenerCount('upgrade') === 1) {
+        rejectUpgradeRequest(socket);
+      }
+      return;
+    }
+    const rejection = await this.resolveUpgradeRejection(request, targetPath);
+    if (rejection) {
+      rejectUpgradeRequestWithStatus(socket, rejection);
+      return;
+    }
+    try {
+      attachment.server.handleUpgrade(request, socket, head, websocket => {
+        attachment.server.emit('connection', websocket, request);
+      });
+    } catch (error) {
+      this.releaseUpgradeReservation();
+      throw error;
+    }
+  }
+  resolveUpgradeServer() {
+    const capability = resolveServerBackedRealtimeCapability(this.adapter);
+    const server = capability.server;
+    if (!hasNodeUpgradeServer(server)) {
+      throw new Error('WebSocket gateway bootstrap requires the selected realtime capability to expose a Node HTTP/S server that supports upgrade listeners.');
+    }
+    return server;
+  }
+  async bindConnectionHandlers(descriptors, socket, request) {
+    const state = this.createConnectionHandlerState();
+    this.registerSocketConnection(state, socket);
+    this.attachConnectionListeners(state, socket, request);
+    await this.resolveConnectionGateways(descriptors, state);
+    await this.runConnectHandlers(state, socket, request);
+    await this.finalizeConnectionBinding(state, socket, request);
+  }
+  registerSocketConnection(state, socket) {
+    this.releaseUpgradeReservation();
+    this.socketRegistry.set(state.socketId, socket);
+  }
+  async finalizeConnectionBinding(state, socket, request) {
+    state.handlersReady = true;
+    this.replayBufferedConnectionEvents(state, socket, request);
+    await state.handlerQueue;
+  }
+  createConnectionHandlerState() {
+    return {
+      bufferedDisconnect: undefined,
+      bufferedMessages: [],
+      bufferedMessagesStartIndex: 0,
+      enqueuedMessageCount: 0,
+      handlerQueue: Promise.resolve(),
+      handlersReady: false,
+      processingMessageQueue: false,
+      queuedMessages: [],
+      queuedMessagesStartIndex: 0,
+      resolved: [],
+      socketId: randomUUID()
+    };
+  }
+  getBufferedMessageCount(state) {
+    return state.bufferedMessages.length - (state.bufferedMessagesStartIndex ?? 0);
+  }
+  getQueuedMessageCount(state) {
+    return state.queuedMessages.length - (state.queuedMessagesStartIndex ?? 0);
+  }
+  maybeCompactBufferedMessages(state) {
+    const startIndex = state.bufferedMessagesStartIndex ?? 0;
+    if (startIndex === 0 || startIndex < state.bufferedMessages.length / 2) {
+      return;
+    }
+    state.bufferedMessages = state.bufferedMessages.slice(startIndex);
+    state.bufferedMessagesStartIndex = 0;
+  }
+  clearBufferedMessages(state) {
+    state.bufferedMessages = [];
+    state.bufferedMessagesStartIndex = 0;
+  }
+  maybeCompactQueuedMessages(state) {
+    const startIndex = state.queuedMessagesStartIndex ?? 0;
+    if (startIndex === 0 || startIndex < state.queuedMessages.length / 2) {
+      return;
+    }
+    state.queuedMessages = state.queuedMessages.slice(startIndex);
+    state.queuedMessagesStartIndex = 0;
+  }
+  clearQueuedMessages(state) {
+    state.queuedMessages = [];
+    state.queuedMessagesStartIndex = 0;
+    state.enqueuedMessageCount = 0;
+  }
+  enqueueMessageDispatch(state, socket, request, data) {
+    const limit = isFinitePositiveInteger(this.moduleOptions.buffer?.maxPendingMessagesPerSocket) ? this.moduleOptions.buffer.maxPendingMessagesPerSocket : DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET;
+    const policy = this.moduleOptions.buffer?.overflowPolicy ?? 'drop-oldest';
+    if (this.getQueuedMessageCount(state) >= limit) {
+      if (policy === 'close') {
+        socket.terminate();
+        this.clearQueuedMessages(state);
+        this.unregisterSocket(state.socketId);
+        this.logger.warn(`WebSocket connection ${state.socketId} exceeded ready-state message queue limit (${String(limit)}). Connection terminated.`, 'WebSocketGatewayLifecycleService');
+        return;
+      }
+      if (policy === 'drop-oldest') {
+        state.queuedMessagesStartIndex = (state.queuedMessagesStartIndex ?? 0) + 1;
+        this.maybeCompactQueuedMessages(state);
+        this.logger.warn(`WebSocket connection ${state.socketId} dropped the oldest ready-state message because queue limit (${String(limit)}) was reached.`, 'WebSocketGatewayLifecycleService');
+      } else {
+        this.logger.warn(`WebSocket connection ${state.socketId} dropped a ready-state message because queue limit (${String(limit)}) was reached.`, 'WebSocketGatewayLifecycleService');
+        return;
+      }
+    }
+    state.queuedMessages.push(data);
+    state.enqueuedMessageCount = this.getQueuedMessageCount(state);
+    if (state.processingMessageQueue) {
+      return;
+    }
+    state.processingMessageQueue = true;
+    state.handlerQueue = this.drainMessageQueue(state, socket, request).finally(() => {
+      state.processingMessageQueue = false;
+      state.enqueuedMessageCount = this.getQueuedMessageCount(state);
+    }).catch(error => {
+      this.logger.error('WebSocket gateway message dispatch failed.', error, 'WebSocketGatewayLifecycleService');
+    });
+  }
+  async drainMessageQueue(state, socket, request) {
+    while ((state.queuedMessagesStartIndex ?? 0) < state.queuedMessages.length) {
+      const nextMessage = state.queuedMessages[state.queuedMessagesStartIndex ?? 0];
+      state.queuedMessagesStartIndex = (state.queuedMessagesStartIndex ?? 0) + 1;
+      state.enqueuedMessageCount = this.getQueuedMessageCount(state);
+      if (nextMessage === undefined) {
+        continue;
+      }
+      await this.handleMessage(state.resolved, socket, request, nextMessage);
+    }
+    this.clearQueuedMessages(state);
+  }
+  async handleMessage(resolved, socket, request, data) {
+    await dispatchGatewayMessage(resolved, socket, request, data, this.logger, 'WebSocketGatewayLifecycleService');
+  }
+  enqueueDisconnectDispatch(state, socket, disconnectEvent) {
+    state.handlerQueue = state.handlerQueue.then(async () => {
+      await this.handleDisconnect(state.resolved, socket, disconnectEvent.code, disconnectEvent.reason, state.socketId);
+    }).catch(error => {
+      this.logger.error('WebSocket gateway disconnect dispatch failed.', error, 'WebSocketGatewayLifecycleService');
+    });
+  }
+  attachConnectionListeners(state, socket, request) {
+    socket.on('message', data => {
+      if (this.closeOversizedPayload(state.socketId, socket, data)) {
+        return;
+      }
+      if (!state.handlersReady) {
+        this.bufferIncomingMessage(state, socket, data);
+        return;
+      }
+      this.enqueueMessageDispatch(state, socket, request, data);
+    });
+    socket.on('pong', () => {
+      this.pingPending.delete(state.socketId);
+      this.pingSentAt.delete(state.socketId);
+    });
+    socket.on('error', error => {
+      this.unregisterSocket(state.socketId);
+      this.logger.error('WebSocket gateway socket emitted an error.', error, 'WebSocketGatewayLifecycleService');
+    });
+    socket.on('close', (code, reason) => {
+      this.unregisterSocket(state.socketId);
+      const disconnectEvent = {
+        code,
+        reason
+      };
+      if (!state.handlersReady) {
+        state.bufferedDisconnect = disconnectEvent;
+        return;
+      }
+      this.enqueueDisconnectDispatch(state, socket, disconnectEvent);
+    });
+  }
+  bufferIncomingMessage(state, socket, data) {
+    const limit = isFinitePositiveInteger(this.moduleOptions.buffer?.maxPendingMessagesPerSocket) ? this.moduleOptions.buffer.maxPendingMessagesPerSocket : DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET;
+    const policy = this.moduleOptions.buffer?.overflowPolicy ?? 'drop-oldest';
+    if (this.getBufferedMessageCount(state) < limit) {
+      state.bufferedMessages.push(data);
+      return;
+    }
+    if (policy === 'close') {
+      socket.terminate();
+      this.clearBufferedMessages(state);
+      this.logger.warn(`WebSocket connection ${state.socketId} exceeded pending message buffer limit (${String(limit)}). Connection terminated.`, 'WebSocketGatewayLifecycleService');
+      return;
+    }
+    if (policy === 'drop-newest') {
+      this.logger.warn(`WebSocket connection ${state.socketId} dropped an incoming message due to pending buffer limit (${String(limit)}).`, 'WebSocketGatewayLifecycleService');
+      return;
+    }
+    state.bufferedMessagesStartIndex = (state.bufferedMessagesStartIndex ?? 0) + 1;
+    this.maybeCompactBufferedMessages(state);
+    state.bufferedMessages.push(data);
+    this.logger.warn(`WebSocket connection ${state.socketId} dropped the oldest pending message due to buffer limit (${String(limit)}).`, 'WebSocketGatewayLifecycleService');
+  }
+  async resolveConnectionGateways(descriptors, state) {
+    for (const descriptor of descriptors) {
+      const instance = await resolveGatewayInstance(this.runtimeContainer, descriptor, this.logger, 'WebSocketGatewayLifecycleService');
+      if (instance !== undefined) {
+        state.resolved.push({
+          descriptor,
+          instance
+        });
+      }
+    }
+  }
+  async runConnectHandlers(state, socket, request) {
+    for (const {
+      descriptor,
+      instance
+    } of state.resolved) {
+      await runGatewayHandlers(instance, descriptor, 'connect', [socket, request, state.socketId], this.logger, 'WebSocketGatewayLifecycleService');
+    }
+  }
+  replayBufferedConnectionEvents(state, socket, request) {
+    for (let index = state.bufferedMessagesStartIndex ?? 0; index < state.bufferedMessages.length; index += 1) {
+      const message = state.bufferedMessages[index];
+      this.enqueueMessageDispatch(state, socket, request, message);
+    }
+    if (state.bufferedDisconnect) {
+      this.enqueueDisconnectDispatch(state, socket, state.bufferedDisconnect);
+      state.bufferedDisconnect = undefined;
+      this.clearBufferedMessages(state);
+      return;
+    }
+    this.clearBufferedMessages(state);
+    if (socket.readyState !== WebSocket.OPEN && socket.readyState !== WebSocket.CONNECTING) {
+      this.unregisterSocket(state.socketId);
+    }
+  }
+  async handleDisconnect(resolved, socket, code, reason, socketId) {
+    await dispatchGatewayDisconnect(resolved, socket, code, reason.toString('utf8'), socketId, this.logger, 'WebSocketGatewayLifecycleService');
+  }
+  async resolveUpgradeRejection(request, path) {
+    if (!this.tryReserveUpgradeSlot()) {
+      return {
+        body: 'WebSocket connection limit exceeded.',
+        status: 429
+      };
+    }
+    const guard = this.moduleOptions.upgrade?.guard;
+    if (!guard) {
+      return undefined;
+    }
+    try {
+      const result = await guard(request, {
+        activeConnectionCount: this.resolveReservedConnectionCount() - 1,
+        path
+      });
+      if (result === false) {
+        this.releaseUpgradeReservation();
+        return {
+          body: 'WebSocket upgrade rejected.',
+          status: 403
+        };
+      }
+      if (isUpgradeRejection(result)) {
+        this.releaseUpgradeReservation();
+        return result;
+      }
+      return undefined;
+    } catch (error) {
+      this.releaseUpgradeReservation();
+      if (isHttpExceptionLike(error)) {
+        return {
+          body: error.message,
+          status: error.status
+        };
+      }
+      throw error;
+    }
+  }
+  closeOversizedPayload(socketId, socket, data) {
+    const maxPayloadBytes = this.resolveMaxPayloadBytes();
+    if (resolveMessageByteLength(data) <= maxPayloadBytes) {
+      return false;
+    }
+    socket.close(1009, 'Payload too large');
+    this.logger.warn(`WebSocket connection ${socketId} exceeded payload limit (${String(maxPayloadBytes)} bytes). Connection closed.`, 'WebSocketGatewayLifecycleService');
+    return true;
+  }
+  resolveMaxConnectionCount() {
+    const configured = this.moduleOptions.limits?.maxConnections;
+    if (!isFinitePositiveInteger(configured)) {
+      return DEFAULT_MAX_WEBSOCKET_CONNECTIONS;
+    }
+    return configured;
+  }
+  resolveReservedConnectionCount() {
+    return this.socketRegistry.size + this.pendingUpgradeReservations;
+  }
+  tryReserveUpgradeSlot() {
+    if (this.resolveReservedConnectionCount() >= this.resolveMaxConnectionCount()) {
+      return false;
+    }
+    this.pendingUpgradeReservations += 1;
+    return true;
+  }
+  releaseUpgradeReservation() {
+    if (this.pendingUpgradeReservations > 0) {
+      this.pendingUpgradeReservations -= 1;
+    }
+  }
+  resolveMaxPayloadBytes() {
+    const configured = this.moduleOptions.limits?.maxPayloadBytes;
+    if (!isFinitePositiveInteger(configured)) {
+      return DEFAULT_MAX_WEBSOCKET_PAYLOAD_BYTES;
+    }
+    return configured;
+  }
+  resolveShutdownTimeoutMs() {
+    const configured = this.moduleOptions.shutdown?.timeoutMs;
+    if (typeof configured !== 'number' || !Number.isFinite(configured) || configured <= 0) {
+      return DEFAULT_WEBSOCKET_SHUTDOWN_TIMEOUT_MS;
+    }
+    return Math.floor(configured);
+  }
+  closeServerWithTimeout(attachment, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const timeout = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        reject(new Error(`Timed out while closing websocket server for path "${attachment.path}" after ${String(timeoutMs)}ms.`));
+      }, timeoutMs);
+      attachment.server.close(error => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+  async shutdown() {
+    if (this.shutdownPromise) {
+      await this.shutdownPromise;
+      return;
+    }
+    this.shutdownPromise = this.runShutdownLifecycle();
+    await this.shutdownPromise;
+  }
+  async runShutdownLifecycle() {
+    this.stopHeartbeat();
+    this.detachUpgradeServerListener();
+    const attachments = this.attachments.splice(0);
+    const ownedUpgradeServers = this.ownedUpgradeServers.splice(0);
+    const shutdownTimeoutMs = this.resolveShutdownTimeoutMs();
+    await this.closeGatewayAttachments(attachments, shutdownTimeoutMs);
+    await this.closeOwnedUpgradeServers(ownedUpgradeServers, shutdownTimeoutMs);
+    this.clearConnectionTrackingState();
+  }
+  stopHeartbeat() {
+    if (!this.heartbeatTimer) {
+      return;
+    }
+    clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = undefined;
+  }
+  detachUpgradeServerListener() {
+    if (this.upgradeServer && this.upgradeListener) {
+      this.upgradeServer.off('upgrade', this.upgradeListener);
+    }
+    for (const registration of this.ownedUpgradeServers) {
+      registration.server.off('upgrade', registration.listener);
+    }
+    this.upgradeServer = undefined;
+    this.upgradeListener = undefined;
+  }
+  async closeOwnedUpgradeServers(registrations, shutdownTimeoutMs) {
+    await Promise.all(registrations.map(async registration => {
+      try {
+        await this.closeOwnedUpgradeServerWithTimeout(registration, shutdownTimeoutMs);
+      } catch (error) {
+        this.logger.error(`Failed to close owned websocket listener on port ${String(registration.port)} within ${String(shutdownTimeoutMs)}ms.`, error, 'WebSocketGatewayLifecycleService');
+      }
+    }));
+  }
+  closeOwnedUpgradeServerWithTimeout(registration, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const timeout = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        reject(new Error(`Timed out while closing owned websocket listener on port ${String(registration.port)} after ${String(timeoutMs)}ms.`));
+      }, timeoutMs);
+      registration.server.close(error => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+  listenOwnedGatewayServer(server, port) {
+    return new Promise((resolve, reject) => {
+      const httpServer = server;
+      const onError = error => {
+        reject(error);
+      };
+      httpServer.once('error', onError);
+      server.listen(port, () => {
+        httpServer.off('error', onError);
+        resolve();
+      });
+    });
+  }
+  async closeGatewayAttachments(attachments, shutdownTimeoutMs) {
+    await Promise.all(attachments.map(async attachment => {
+      this.terminateAttachmentClients(attachment);
+      await this.closeGatewayAttachment(attachment, shutdownTimeoutMs);
+    }));
+  }
+  terminateAttachmentClients(attachment) {
+    for (const client of attachment.server.clients) {
+      client.terminate();
+    }
+  }
+  async closeGatewayAttachment(attachment, shutdownTimeoutMs) {
+    try {
+      await this.closeServerWithTimeout(attachment, shutdownTimeoutMs);
+    } catch (error) {
+      this.logger.error(`Failed to close websocket server for path ${attachment.path} within ${String(shutdownTimeoutMs)}ms.`, error, 'WebSocketGatewayLifecycleService');
+    }
+  }
+  clearConnectionTrackingState() {
+    this.socketRegistry.clear();
+    this.socketRooms.clear();
+    this.roomSockets.clear();
+    this.pingPending.clear();
+    this.pingSentAt.clear();
+    this.pendingUpgradeReservations = 0;
+  }
+
+  /**
+   * Adds one socket to an in-memory room membership set.
+   *
+   * @param socketId Socket identifier to add.
+   * @param room Room identifier to join.
+   */
+  joinRoom(socketId, room) {
+    let rooms = this.socketRooms.get(socketId);
+    if (!rooms) {
+      rooms = new Set();
+      this.socketRooms.set(socketId, rooms);
+    }
+    rooms.add(room);
+    let sockets = this.roomSockets.get(room);
+    if (!sockets) {
+      sockets = new Set();
+      this.roomSockets.set(room, sockets);
+    }
+    sockets.add(socketId);
+  }
+
+  /**
+   * Removes one socket from an in-memory room membership set.
+   *
+   * @param socketId Socket identifier to remove.
+   * @param room Room identifier to leave.
+   */
+  leaveRoom(socketId, room) {
+    const rooms = this.socketRooms.get(socketId);
+    rooms?.delete(room);
+    if (rooms && rooms.size === 0) {
+      this.socketRooms.delete(socketId);
+    }
+    const sockets = this.roomSockets.get(room);
+    sockets?.delete(socketId);
+    if (sockets && sockets.size === 0) {
+      this.roomSockets.delete(room);
+    }
+  }
+
+  /**
+   * Broadcasts one JSON-encoded event frame to every open socket currently joined to a room.
+   *
+   * @param room Room identifier that should receive the event.
+   * @param event Event name delivered to room members.
+   * @param data Payload delivered with the event.
+   */
+  broadcastToRoom(room, event, data) {
+    const socketIds = this.roomSockets.get(room);
+    if (!socketIds) {
+      return;
+    }
+    const message = JSON.stringify({
+      data,
+      event
+    });
+    const maxBufferedAmountBytes = isFinitePositiveInteger(this.moduleOptions.backpressure?.maxBufferedAmountBytes) ? this.moduleOptions.backpressure.maxBufferedAmountBytes : DEFAULT_MAX_BUFFERED_AMOUNT_BYTES;
+    const backpressurePolicy = this.moduleOptions.backpressure?.policy ?? 'drop';
+    for (const socketId of socketIds) {
+      const socket = this.socketRegistry.get(socketId);
+      if (socket && socket.readyState === WebSocket.OPEN) {
+        if (socket.bufferedAmount > maxBufferedAmountBytes) {
+          if (backpressurePolicy === 'close') {
+            socket.terminate();
+            this.unregisterSocket(socketId);
+            this.logger.warn(`WebSocket connection ${socketId} exceeded bufferedAmount threshold (${String(maxBufferedAmountBytes)} bytes). Connection terminated.`, 'WebSocketGatewayLifecycleService');
+            continue;
+          }
+          this.logger.warn(`WebSocket connection ${socketId} exceeded bufferedAmount threshold (${String(maxBufferedAmountBytes)} bytes). Broadcast frame dropped.`, 'WebSocketGatewayLifecycleService');
+          continue;
+        }
+        socket.send(message);
+      }
+    }
+  }
+
+  /**
+   * Returns the current in-memory room snapshot for one socket.
+   *
+   * @param socketId Socket identifier to inspect.
+   * @returns The room set currently tracked for that socket.
+   */
+  getRooms(socketId) {
+    const rooms = this.socketRooms.get(socketId);
+    if (!rooms) {
+      return new Set();
+    }
+    return new Set(rooms);
+  }
+  startHeartbeat(intervalMs, timeoutMs) {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+    }
+    this.heartbeatTimer = setInterval(() => {
+      const now = Date.now();
+      for (const [socketId, socket] of this.socketRegistry) {
+        if (this.pingPending.has(socketId)) {
+          const pingAt = this.pingSentAt.get(socketId);
+          const elapsed = pingAt === undefined ? timeoutMs : now - pingAt;
+          if (elapsed >= timeoutMs) {
+            socket.terminate();
+            this.unregisterSocket(socketId);
+          }
+          continue;
+        }
+        if (socket.readyState === WebSocket.OPEN) {
+          this.pingPending.add(socketId);
+          this.pingSentAt.set(socketId, now);
+          socket.ping();
+        }
+      }
+    }, intervalMs);
+  }
+  unregisterSocket(socketId) {
+    this.socketRegistry.delete(socketId);
+    this.pingPending.delete(socketId);
+    this.pingSentAt.delete(socketId);
+    const rooms = this.socketRooms.get(socketId);
+    if (rooms) {
+      for (const room of rooms) {
+        const sockets = this.roomSockets.get(room);
+        sockets?.delete(socketId);
+        if (sockets && sockets.size === 0) {
+          this.roomSockets.delete(room);
+        }
+      }
+      this.socketRooms.delete(socketId);
+    }
+  }
+  static {
+    _initClass();
+  }
+}
+export { _NodeWebSocketGateway as NodeWebSocketGatewayLifecycleService };
+function createOwnedGatewayServer() {
+  return createHttpServer((_request, response) => {
+    response.statusCode = 404;
+    response.end();
+  });
+}