@fluojs/socket.io 1.0.0-beta.1

package/dist/adapter.js

@@ -0,0 +1,780 @@
+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 { AsyncLocalStorage } from 'node:async_hooks';
+import { Inject } from '@fluojs/core';
+import { getClassDiMetadata } from '@fluojs/core/internal';
+import { Server as BunEngineServer } from '@socket.io/bun-engine';
+import { APPLICATION_LOGGER, COMPILED_MODULES, HTTP_APPLICATION_ADAPTER, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { getWebSocketGatewayMetadata, getWebSocketHandlerMetadataEntries } from '@fluojs/websockets';
+import { Server } from 'socket.io';
+import { SOCKETIO_OPTIONS_INTERNAL } from './options-token.internal.js';
+const DEFAULT_SOCKETIO_SHUTDOWN_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET = 128;
+const DEFAULT_SOCKETIO_ENGINE_PATH = '/socket.io/';
+const DEFAULT_SOCKETIO_MAX_HTTP_BUFFER_SIZE = 1_048_576;
+function isFinitePositiveInteger(value) {
+  return typeof value === 'number' && Number.isInteger(value) && Number.isFinite(value) && value > 0;
+}
+function normalizeGuardRejection(result, defaultMessage) {
+  if (result === undefined || result === true) {
+    return undefined;
+  }
+  if (result === false) {
+    return {
+      message: defaultMessage
+    };
+  }
+  return result;
+}
+function createGuardError(rejection, defaultMessage) {
+  const error = new Error(rejection.message ?? defaultMessage);
+  if (rejection.data !== undefined) {
+    error.data = rejection.data;
+  }
+  return error;
+}
+function normalizeRejectedGuardError(error, defaultMessage) {
+  if (error instanceof Error) {
+    return {
+      data: error.data,
+      message: error.message || defaultMessage
+    };
+  }
+  if (typeof error === 'object' && error !== null) {
+    const candidate = error;
+    return {
+      data: candidate.data,
+      disconnect: candidate.disconnect,
+      message: candidate.message ?? defaultMessage
+    };
+  }
+  return {
+    message: defaultMessage
+  };
+}
+function scopeFromProvider(provider) {
+  if (typeof provider === 'function') {
+    return getClassDiMetadata(provider)?.scope ?? 'singleton';
+  }
+  if ('useClass' in provider) {
+    const classProvider = provider;
+    return classProvider.scope ?? getClassDiMetadata(classProvider.useClass)?.scope ?? 'singleton';
+  }
+  return 'scope' in provider ? provider.scope ?? 'singleton' : 'singleton';
+}
+function methodKeyToName(methodKey) {
+  return typeof methodKey === 'symbol' ? methodKey.toString() : methodKey;
+}
+function isClassProvider(provider) {
+  return typeof provider === 'object' && provider !== null && 'useClass' in provider;
+}
+function normalizeGatewayPath(path) {
+  if (path === '/') {
+    return '/';
+  }
+  const normalized = `/${path.replace(/^\/+/, '').replace(/\/+$/, '')}`;
+  return normalized === '' ? '/' : normalized;
+}
+function isNodeHttpServerLike(value) {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.close === 'function' && typeof candidate.emit === 'function' && typeof candidate.listeners === 'function' && typeof candidate.on === 'function' && typeof candidate.removeAllListeners === 'function';
+}
+function normalizeCorsForBunEngine(cors) {
+  if (cors === undefined) {
+    return undefined;
+  }
+  if (typeof cors === 'function') {
+    throw new Error('Socket.IO Bun bootstrap does not support CORS delegate functions. Use static CORS options with @fluojs/platform-bun.');
+  }
+  const origin = cors.origin;
+  if (typeof origin === 'function') {
+    throw new Error('Socket.IO Bun bootstrap does not support function-based cors.origin handlers. Use static origin values with @fluojs/platform-bun.');
+  }
+  if (Array.isArray(origin) && origin.some(value => typeof value === 'boolean')) {
+    throw new Error('Socket.IO Bun bootstrap does not support boolean entries inside cors.origin arrays. Use string or RegExp origins with @fluojs/platform-bun.');
+  }
+  return {
+    allowedHeaders: cors.allowedHeaders,
+    credentials: cors.credentials,
+    exposedHeaders: cors.exposedHeaders,
+    maxAge: cors.maxAge,
+    methods: cors.methods,
+    origin: Array.isArray(origin) ? origin.filter(value => typeof value === 'string' || value instanceof RegExp) : origin
+  };
+}
+function hasBunRealtimeBindingHost(adapter) {
+  return 'configureRealtimeBinding' in adapter && typeof adapter.configureRealtimeBinding === 'function';
+}
+function isFetchStyleRealtimeCapability(capability) {
+  return capability.kind === 'fetch-style' && capability.contract === 'raw-websocket-expansion';
+}
+function resolveSocketIoBootstrapRuntime(adapter) {
+  if (typeof adapter.getRealtimeCapability !== 'function') {
+    throw new Error('Socket.IO bootstrap requires an HTTP adapter with getRealtimeCapability(). Use a platform adapter that exposes a server-backed realtime capability or @fluojs/platform-bun for the official Bun engine path.');
+  }
+  const capability = adapter.getRealtimeCapability();
+  if (capability.kind === 'server-backed') {
+    return {
+      capability,
+      kind: 'server-backed'
+    };
+  }
+  if (!isFetchStyleRealtimeCapability(capability)) {
+    throw new Error(`Socket.IO bootstrap requires a server-backed realtime capability. ${capability.reason}`);
+  }
+  if (capability.support !== 'supported') {
+    throw new Error(`Socket.IO Bun bootstrap requires supported fetch-style websocket hosting. ${capability.reason}`);
+  }
+  if (!hasBunRealtimeBindingHost(adapter)) {
+    throw new Error('Socket.IO Bun bootstrap requires the selected adapter to expose Bun realtime binding configuration. Use @fluojs/platform-bun for the official Bun engine path.');
+  }
+  return {
+    bindingHost: adapter,
+    capability,
+    kind: 'bun'
+  };
+}
+function extractPayload(args) {
+  if (args.length === 0) {
+    return undefined;
+  }
+  const effectiveArgs = typeof args.at(-1) === 'function' ? args.slice(0, -1) : args;
+  if (effectiveArgs.length === 0) {
+    return undefined;
+  }
+  return effectiveArgs.length === 1 ? effectiveArgs[0] : effectiveArgs;
+}
+
+/**
+ * Lifecycle service that boots Socket.IO gateways, exposes the raw server, and implements room helpers.
+ *
+ * @remarks
+ * This service preserves the README-level gateway contracts for namespace discovery, buffered pre-ready events,
+ * Bun engine hosting, and graceful shutdown behavior.
+ */
+let _SocketIoLifecycleSer;
+class SocketIoLifecycleService {
+  static {
+    [_SocketIoLifecycleSer, _initClass] = _applyDecs(this, [Inject(RUNTIME_CONTAINER, COMPILED_MODULES, APPLICATION_LOGGER, HTTP_APPLICATION_ADAPTER, SOCKETIO_OPTIONS_INTERNAL)], []).c;
+  }
+  attachments = [];
+  bunEngine;
+  io;
+  namespaceContext = new AsyncLocalStorage();
+  socketRegistry = new Map();
+  shutdownPromise;
+  wired = false;
+  constructor(runtimeContainer, compiledModules, logger, adapter, moduleOptions) {
+    this.runtimeContainer = runtimeContainer;
+    this.compiledModules = compiledModules;
+    this.logger = logger;
+    this.adapter = adapter;
+    this.moduleOptions = moduleOptions;
+  }
+
+  /**
+   * Returns the managed Socket.IO server instance, creating and binding it on first access.
+   *
+   * @returns The shared Socket.IO `Server` used by this adapter instance.
+   * @throws {Error} When the selected realtime capability cannot expose the server contract Socket.IO requires.
+   */
+  getServer() {
+    if (this.io) {
+      return this.io;
+    }
+    const runtime = resolveSocketIoBootstrapRuntime(this.adapter);
+    if (runtime.kind === 'server-backed') {
+      const httpServer = runtime.capability.server;
+      if (!isNodeHttpServerLike(httpServer)) {
+        throw new Error('Socket.IO bootstrap requires the selected realtime capability to expose a Node HTTP/S server instance.');
+      }
+      this.io = new Server(httpServer, this.createServerOptions());
+      return this.io;
+    }
+    this.io = new Server(this.createServerOptions());
+    this.installBunSocketIoBinding(runtime, this.io);
+    return this.io;
+  }
+
+  /**
+   * Discovers gateway classes and binds their handlers to the resolved namespaces once per application lifecycle.
+   */
+  async onApplicationBootstrap() {
+    if (this.wired) {
+      return;
+    }
+    const descriptors = this.discoverGatewayDescriptors();
+    if (descriptors.length === 0) {
+      return;
+    }
+    this.assertNoServerBackedGatewayOptIn(descriptors);
+    const io = this.getServer();
+    const attachments = this.prepareNamespaceAttachments(io, descriptors);
+    for (const attachment of attachments) {
+      this.bindNamespaceHandlers(attachment);
+    }
+    this.attachments = attachments;
+    this.wired = true;
+  }
+
+  /**
+   * Shuts down Socket.IO resources during application shutdown.
+   */
+  async onApplicationShutdown() {
+    await this.shutdown();
+  }
+
+  /**
+   * Shuts down Socket.IO resources when the containing module is destroyed.
+   */
+  async onModuleDestroy() {
+    await this.shutdown();
+  }
+
+  /**
+   * Adds a socket to one room, using the current gateway namespace or an explicit namespace override.
+   *
+   * @param socketId Socket identifier to move into the room.
+   * @param room Room identifier to join.
+   * @param namespacePath Optional namespace path required when the helper runs outside gateway handler context.
+   */
+  joinRoom(socketId, room, namespacePath) {
+    const socket = this.resolveSocket(socketId);
+    if (socket) {
+      void socket.join(room);
+      return;
+    }
+    this.resolveRequiredNamespace(namespacePath).in(socketId).socketsJoin(room);
+  }
+
+  /**
+   * Removes a socket from one room, using the current gateway namespace or an explicit namespace override.
+   *
+   * @param socketId Socket identifier to remove from the room.
+   * @param room Room identifier to leave.
+   * @param namespacePath Optional namespace path required when the helper runs outside gateway handler context.
+   */
+  leaveRoom(socketId, room, namespacePath) {
+    const socket = this.resolveSocket(socketId);
+    if (socket) {
+      void socket.leave(room);
+      return;
+    }
+    this.resolveRequiredNamespace(namespacePath).in(socketId).socketsLeave(room);
+  }
+
+  /**
+   * Emits one event payload to every socket currently joined to a room.
+   *
+   * @param room Room identifier that should receive the event.
+   * @param event Socket.IO event name emitted to the room.
+   * @param data Payload delivered with the event.
+   * @param namespacePath Optional namespace path required when the helper runs outside gateway handler context.
+   */
+  broadcastToRoom(room, event, data, namespacePath) {
+    this.resolveRequiredNamespace(namespacePath).to(room).emit(event, data);
+  }
+
+  /**
+   * Returns the current room set tracked for one connected socket.
+   *
+   * @param socketId Socket identifier to inspect.
+   * @returns A snapshot of the rooms currently joined by that socket.
+   */
+  getRooms(socketId) {
+    const socket = this.socketRegistry.get(socketId);
+    if (!socket) {
+      return new Set();
+    }
+    return new Set(socket.rooms);
+  }
+  createServerOptions() {
+    const options = {};
+    options.cors = this.resolveCorsOptions();
+    options.maxHttpBufferSize = this.resolveMaxHttpBufferSize();
+    if (this.moduleOptions.transports !== undefined) {
+      options.transports = this.moduleOptions.transports;
+    }
+    return options;
+  }
+  createBunEngineOptions() {
+    const options = {
+      path: DEFAULT_SOCKETIO_ENGINE_PATH
+    };
+    options.cors = normalizeCorsForBunEngine(this.resolveCorsOptions());
+    return options;
+  }
+  resolveCorsOptions() {
+    return this.moduleOptions.cors ?? {
+      credentials: false,
+      origin: false
+    };
+  }
+  resolveMaxHttpBufferSize() {
+    const configured = this.moduleOptions.engine?.maxHttpBufferSize;
+    if (!isFinitePositiveInteger(configured)) {
+      return DEFAULT_SOCKETIO_MAX_HTTP_BUFFER_SIZE;
+    }
+    return configured;
+  }
+  installBunSocketIoBinding(runtime, io) {
+    if (this.bunEngine) {
+      return;
+    }
+    const engine = new BunEngineServer(this.createBunEngineOptions());
+    io.bind(engine);
+    runtime.bindingHost.configureRealtimeBinding(this.createBunSocketIoBinding(engine));
+    this.bunEngine = engine;
+  }
+  createBunSocketIoBinding(engine) {
+    const handler = engine.handler();
+    return {
+      fetch: async (request, server) => {
+        const pathname = this.tryResolvePathname(request.url);
+        if (!this.matchesSocketIoEnginePath(pathname)) {
+          return undefined;
+        }
+        return await engine.handleRequest(request, server);
+      },
+      idleTimeout: handler.idleTimeout,
+      maxRequestBodySize: handler.maxRequestBodySize,
+      websocket: {
+        close: handler.websocket.close,
+        maxPayloadLength: handler.websocket.maxPayloadLength,
+        message: handler.websocket.message,
+        open: handler.websocket.open
+      }
+    };
+  }
+  tryResolvePathname(url) {
+    try {
+      return new URL(url).pathname;
+    } catch {
+      return undefined;
+    }
+  }
+  matchesSocketIoEnginePath(pathname) {
+    return pathname === '/socket.io' || pathname === DEFAULT_SOCKETIO_ENGINE_PATH;
+  }
+  assertNoServerBackedGatewayOptIn(descriptors) {
+    const runtime = resolveSocketIoBootstrapRuntime(this.adapter);
+    if (runtime.kind !== 'bun') {
+      return;
+    }
+    const descriptor = descriptors.find(entry => entry.serverBacked !== undefined);
+    if (!descriptor) {
+      return;
+    }
+    throw new Error(`@WebSocketGateway({ serverBacked }) is not supported on @fluojs/socket.io when using @fluojs/platform-bun. Gateway path ${descriptor.path} must use the official Bun engine host instead.`);
+  }
+  prepareNamespaceAttachments(io, descriptors) {
+    const attachmentsByPath = new Map();
+    for (const descriptor of descriptors) {
+      const current = attachmentsByPath.get(descriptor.path);
+      if (current) {
+        current.descriptors.push(descriptor);
+        continue;
+      }
+      attachmentsByPath.set(descriptor.path, {
+        descriptors: [descriptor],
+        namespace: descriptor.path === '/' ? io.of('/') : io.of(descriptor.path),
+        path: descriptor.path
+      });
+    }
+    return Array.from(attachmentsByPath.values());
+  }
+  resolveNamespace(path) {
+    return this.attachments.find(attachment => attachment.path === path)?.namespace;
+  }
+  resolveContextNamespace() {
+    const namespaceName = this.namespaceContext.getStore();
+    if (!namespaceName) {
+      return undefined;
+    }
+    return this.resolveNamespace(namespaceName);
+  }
+  resolveRequiredNamespace(namespacePath) {
+    const namespace = namespacePath ? this.resolveNamespace(normalizeGatewayPath(namespacePath)) : this.resolveContextNamespace();
+    if (!namespace) {
+      throw new Error('Socket.IO room helpers require an explicit namespace outside gateway handler context.');
+    }
+    return namespace;
+  }
+  resolveSocket(socketId) {
+    const registered = this.socketRegistry.get(socketId);
+    if (registered) {
+      return registered;
+    }
+    for (const attachment of this.attachments) {
+      const socket = attachment.namespace.sockets.get(socketId);
+      if (socket) {
+        this.socketRegistry.set(socketId, socket);
+        return socket;
+      }
+    }
+    return undefined;
+  }
+  bindNamespaceHandlers(attachment) {
+    if (this.moduleOptions.auth?.connection) {
+      attachment.namespace.use((socket, next) => {
+        void this.runConnectionGuard(attachment.path, socket).then(() => next()).catch(error => {
+          next(error instanceof Error ? error : new Error('Socket.IO connection rejected.'));
+        });
+      });
+    }
+    attachment.namespace.on('connection', socket => {
+      void this.bindConnectionHandlers(attachment.descriptors, socket);
+    });
+  }
+  async runConnectionGuard(path, socket) {
+    const guard = this.moduleOptions.auth?.connection;
+    if (!guard) {
+      return;
+    }
+    const rejection = normalizeGuardRejection(await guard({
+      activeConnectionCount: this.socketRegistry.size,
+      namespacePath: path,
+      request: socket.request,
+      socket
+    }), 'Socket.IO connection rejected.');
+    if (rejection) {
+      throw createGuardError(rejection, 'Socket.IO connection rejected.');
+    }
+  }
+  async bindConnectionHandlers(descriptors, socket) {
+    const request = socket.request;
+    const resolved = await this.resolveConnectionGateways(descriptors);
+    const state = this.createConnectionHandlerState();
+    this.socketRegistry.set(socket.id, socket);
+    this.attachConnectionListeners(state, resolved, socket, request);
+    await this.runConnectHandlers(resolved, socket, request);
+    state.handlersReady = true;
+    await this.replayBufferedConnectionEvents(state, resolved, socket, request);
+  }
+  createConnectionHandlerState() {
+    return {
+      bufferedDisconnect: undefined,
+      bufferedMessages: [],
+      handlersReady: false
+    };
+  }
+  maxPendingMessagesPerSocket() {
+    return isFinitePositiveInteger(this.moduleOptions.buffer?.maxPendingMessagesPerSocket) ? this.moduleOptions.buffer.maxPendingMessagesPerSocket : DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET;
+  }
+  attachConnectionListeners(state, resolved, socket, request) {
+    socket.onAny((event, ...args) => {
+      const ack = typeof args.at(-1) === 'function' ? args.at(-1) : undefined;
+      if (!state.handlersReady) {
+        const limit = this.maxPendingMessagesPerSocket();
+        const policy = this.moduleOptions.buffer?.overflowPolicy ?? 'drop-oldest';
+        if (state.bufferedMessages.length >= limit) {
+          if (policy === 'close') {
+            socket.disconnect(true);
+            state.bufferedMessages = [];
+            this.socketRegistry.delete(socket.id);
+            this.logger.warn(`Socket.IO connection ${socket.id} exceeded pending message buffer limit (${String(limit)}). Connection terminated.`, 'SocketIoLifecycleService');
+            return;
+          }
+          if (policy === 'drop-newest') {
+            this.logger.warn(`Socket.IO connection ${socket.id} dropped an incoming message due to pending buffer limit (${String(limit)}).`, 'SocketIoLifecycleService');
+            return;
+          }
+          state.bufferedMessages.shift();
+          this.logger.warn(`Socket.IO connection ${socket.id} dropped the oldest pending message because buffer limit (${String(limit)}) was reached.`, 'SocketIoLifecycleService');
+        }
+        state.bufferedMessages.push({
+          acknowledgement: ack,
+          event,
+          payload: extractPayload(args)
+        });
+        return;
+      }
+      void this.handleMessage(resolved, socket, request, event, extractPayload(args), ack);
+    });
+    socket.on('error', error => {
+      this.socketRegistry.delete(socket.id);
+      this.logger.error('Socket.IO gateway socket emitted an error.', error, 'SocketIoLifecycleService');
+    });
+    socket.on('disconnect', (reason, description) => {
+      if (!state.handlersReady) {
+        state.bufferedDisconnect = {
+          description,
+          reason
+        };
+        return;
+      }
+      void this.handleDisconnect(resolved, socket, reason, description).finally(() => {
+        this.socketRegistry.delete(socket.id);
+      });
+    });
+  }
+  async replayBufferedConnectionEvents(state, resolved, socket, request) {
+    for (const message of state.bufferedMessages) {
+      await this.handleMessage(resolved, socket, request, message.event, message.payload, message.acknowledgement);
+    }
+    state.bufferedMessages = [];
+    if (state.bufferedDisconnect) {
+      const disconnectEvent = state.bufferedDisconnect;
+      state.bufferedDisconnect = undefined;
+      await this.handleDisconnect(resolved, socket, disconnectEvent.reason, disconnectEvent.description);
+      this.socketRegistry.delete(socket.id);
+      return;
+    }
+    if (socket.disconnected) {
+      this.socketRegistry.delete(socket.id);
+    }
+  }
+  async resolveConnectionGateways(descriptors) {
+    const resolved = [];
+    for (const descriptor of descriptors) {
+      const instance = await this.resolveGatewayInstance(descriptor);
+      if (instance !== undefined) {
+        resolved.push({
+          descriptor,
+          instance
+        });
+      }
+    }
+    return resolved;
+  }
+  async runConnectHandlers(resolved, socket, request) {
+    for (const {
+      descriptor,
+      instance
+    } of resolved) {
+      await this.runHandlers(instance, descriptor, 'connect', socket, request);
+    }
+  }
+  async handleMessage(resolved, socket, request, event, payload, acknowledgement) {
+    const hasMatchingHandlers = resolved.some(({
+      descriptor
+    }) => this.selectMessageHandlers(descriptor, event).length > 0);
+    if (!hasMatchingHandlers) {
+      return;
+    }
+    let rejection;
+    try {
+      rejection = await this.resolveMessageGuardRejection(socket, request, event, payload);
+    } catch (error) {
+      this.logger.error(`Socket.IO message guard for event ${event} on socket ${socket.id} rejected unexpectedly.`, error, 'SocketIoLifecycleService');
+      rejection = normalizeRejectedGuardError(error, 'Socket.IO message rejected.');
+    }
+    if (rejection) {
+      this.reportRejectedMessage(socket, event, acknowledgement, rejection);
+      return;
+    }
+    for (const {
+      descriptor,
+      instance
+    } of resolved) {
+      const handlers = this.selectMessageHandlers(descriptor, event);
+      for (const handler of handlers) {
+        await this.invokeGatewayMethod(instance, descriptor, handler, [payload, socket, request, acknowledgement]);
+      }
+    }
+  }
+  async resolveMessageGuardRejection(socket, request, event, payload) {
+    const guard = this.moduleOptions.auth?.message;
+    if (!guard) {
+      return undefined;
+    }
+    const rejection = normalizeGuardRejection(await guard({
+      activeConnectionCount: this.socketRegistry.size,
+      event,
+      namespacePath: socket.nsp.name,
+      payload,
+      request,
+      socket
+    }), 'Socket.IO message rejected.');
+    return rejection;
+  }
+  reportRejectedMessage(socket, event, acknowledgement, rejection) {
+    this.logger.warn(`Socket.IO message ${event} for socket ${socket.id} was rejected before handler dispatch.`, 'SocketIoLifecycleService');
+    if (acknowledgement) {
+      acknowledgement({
+        data: rejection.data,
+        error: rejection.message ?? 'Socket.IO message rejected.'
+      });
+    }
+    if (rejection.disconnect === true) {
+      socket.disconnect(true);
+    }
+  }
+  selectMessageHandlers(descriptor, event) {
+    return descriptor.handlers.filter(handler => handler.type === 'message' && (handler.event === undefined || handler.event === event));
+  }
+  async handleDisconnect(resolved, socket, reason, description) {
+    for (const {
+      descriptor,
+      instance
+    } of resolved) {
+      await this.runHandlers(instance, descriptor, 'disconnect', socket, reason, description);
+    }
+  }
+  async runHandlers(instance, descriptor, type, ...args) {
+    const handlers = descriptor.handlers.filter(handler => handler.type === type);
+    for (const handler of handlers) {
+      await this.invokeGatewayMethod(instance, descriptor, handler, args);
+    }
+  }
+  async invokeGatewayMethod(instance, descriptor, handler, args) {
+    const value = instance[handler.methodKey];
+    if (typeof value !== 'function') {
+      this.logger.warn(`Socket.IO gateway handler ${descriptor.targetName}.${handler.methodName} is not callable and was skipped.`, 'SocketIoLifecycleService');
+      return;
+    }
+    try {
+      await this.namespaceContext.run(descriptor.path, async () => await Promise.resolve(value.call(instance, ...args)));
+    } catch (error) {
+      this.logger.error(`Socket.IO gateway handler ${descriptor.targetName}.${handler.methodName} failed.`, error, 'SocketIoLifecycleService');
+    }
+  }
+  async resolveGatewayInstance(descriptor) {
+    try {
+      return await this.runtimeContainer.resolve(descriptor.token);
+    } catch (error) {
+      this.logger.error(`Failed to resolve Socket.IO gateway ${descriptor.targetName} from module ${descriptor.moduleName}.`, error, 'SocketIoLifecycleService');
+      return undefined;
+    }
+  }
+  discoverGatewayDescriptors() {
+    const seenTargets = new Set();
+    const descriptors = [];
+    for (const candidate of this.discoveryCandidates()) {
+      const gatewayMetadata = getWebSocketGatewayMetadata(candidate.targetType);
+      if (!gatewayMetadata) {
+        continue;
+      }
+      if (this.shouldSkipGatewayCandidate(candidate, seenTargets)) {
+        continue;
+      }
+      seenTargets.add(candidate.targetType);
+      descriptors.push(this.createGatewayDescriptor(candidate, gatewayMetadata.path));
+    }
+    return descriptors;
+  }
+  shouldSkipGatewayCandidate(candidate, seenTargets) {
+    if (candidate.scope !== 'singleton') {
+      this.logger.warn(`${candidate.targetType.name} in module ${candidate.moduleName} declares @WebSocketGateway() but is registered with ${candidate.scope} scope. Socket.IO gateways are registered only for singleton providers.`, 'SocketIoLifecycleService');
+      return true;
+    }
+    return seenTargets.has(candidate.targetType);
+  }
+  createGatewayDescriptor(candidate, path) {
+    const metadata = getWebSocketGatewayMetadata(candidate.targetType);
+    const entries = getWebSocketHandlerMetadataEntries(candidate.targetType.prototype);
+    return {
+      handlers: entries.map(entry => ({
+        event: entry.metadata.event,
+        methodKey: entry.propertyKey,
+        methodName: methodKeyToName(entry.propertyKey),
+        type: entry.metadata.type
+      })),
+      moduleName: candidate.moduleName,
+      path: normalizeGatewayPath(path),
+      serverBacked: metadata?.serverBacked,
+      targetName: candidate.targetType.name,
+      token: candidate.token
+    };
+  }
+  discoveryCandidates() {
+    const candidates = [];
+    for (const compiledModule of this.compiledModules) {
+      for (const provider of compiledModule.definition.providers ?? []) {
+        if (typeof provider === 'function') {
+          candidates.push({
+            moduleName: compiledModule.type.name,
+            scope: scopeFromProvider(provider),
+            targetType: provider,
+            token: provider
+          });
+          continue;
+        }
+        if (isClassProvider(provider)) {
+          candidates.push({
+            moduleName: compiledModule.type.name,
+            scope: scopeFromProvider(provider),
+            targetType: provider.useClass,
+            token: provider.provide
+          });
+        }
+      }
+      for (const controller of compiledModule.definition.controllers ?? []) {
+        candidates.push({
+          moduleName: compiledModule.type.name,
+          scope: scopeFromProvider(controller),
+          targetType: controller,
+          token: controller
+        });
+      }
+    }
+    return candidates;
+  }
+  resolveShutdownTimeoutMs() {
+    const configured = this.moduleOptions.shutdown?.timeoutMs;
+    if (typeof configured !== 'number' || !Number.isFinite(configured) || configured <= 0) {
+      return DEFAULT_SOCKETIO_SHUTDOWN_TIMEOUT_MS;
+    }
+    return Math.floor(configured);
+  }
+  async shutdown() {
+    if (this.shutdownPromise) {
+      await this.shutdownPromise;
+      return;
+    }
+    this.shutdownPromise = this.runShutdownLifecycle();
+    await this.shutdownPromise;
+  }
+  async runShutdownLifecycle() {
+    const io = this.io;
+    this.attachments = [];
+    this.wired = false;
+    if (!io) {
+      this.socketRegistry.clear();
+      return;
+    }
+    try {
+      await this.closeServerWithTimeout(io, this.resolveShutdownTimeoutMs());
+    } catch (error) {
+      this.logger.error(`Failed to close Socket.IO server within ${String(this.resolveShutdownTimeoutMs())}ms.`, error, 'SocketIoLifecycleService');
+    } finally {
+      this.io = undefined;
+      this.bunEngine = undefined;
+      if (hasBunRealtimeBindingHost(this.adapter)) {
+        this.adapter.configureRealtimeBinding(undefined);
+      }
+      this.socketRegistry.clear();
+    }
+  }
+  closeServerWithTimeout(io, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const timeout = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        reject(new Error(`Timed out while closing Socket.IO server after ${String(timeoutMs)}ms.`));
+      }, timeoutMs);
+      io.close(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        resolve();
+      });
+    });
+  }
+  static {
+    _initClass();
+  }
+}
+export { _SocketIoLifecycleSer as SocketIoLifecycleService };