@fluojs/socket.io 1.0.4 → 1.0.5

package/README.ko.md

@@ -103,11 +103,11 @@ SocketIoModule.forRoot({
 });
 ```
 
-`cors`를 생략하면 `@fluojs/socket.io`는 `{ credentials: false, origin: false }`를 기본값으로 사용하므로 cross-origin 노출은 명시적 opt-in이 필요합니다. `engine.maxHttpBufferSize`를 생략하면 어댑터가 1 MiB Engine.IO payload 상한을 적용합니다. 기본값에는 `buffer.maxPendingMessagesPerSocket: 128`, `buffer.overflowPolicy: 'drop-oldest'`, `shutdown.timeoutMs: 5000`도 포함됩니다.
+`cors`를 생략하면 `@fluojs/socket.io`는 `{ credentials: false, origin: false }`를 기본값으로 사용하므로 cross-origin 노출은 명시적 opt-in이 필요합니다. `engine.maxHttpBufferSize`를 생략하면 어댑터가 1 MiB Engine.IO payload 상한을 적용합니다. 기본값에는 `buffer.maxPendingMessagesPerSocket: 128`, `buffer.overflowPolicy: 'drop-oldest'`, `shutdown.timeoutMs: 5000`도 포함됩니다. 명시적인 `engine.maxHttpBufferSize`, `buffer.maxPendingMessagesPerSocket`, `shutdown.timeoutMs` 값은 양의 정수여야 하며, 잘못된 명시 값은 기본값으로 fallback하지 않고 모듈 등록 중 실패합니다.
 
 정적 `@WebSocketGateway({ path })` namespace는 fluo gateway discovery가 소유하며 Socket.IO dynamic child namespace로 취급하지 않습니다. 어댑터는 이러한 정적 namespace에 대해 Socket.IO의 `cleanupEmptyChildNamespaces` 동작을 비활성화합니다. 애플리케이션 코드가 raw `SOCKETIO_SERVER` 접근으로 dynamic child namespace를 만들면 해당 소유권과 cleanup 정책은 애플리케이션 수준 Socket.IO 통합이 담당합니다.
 
-애플리케이션 종료 중 Socket.IO client 정리는 Socket.IO가 소유하지만 underlying HTTP server는 이를 제공한 platform adapter 또는 shared HTTP server 통합이 계속 소유합니다. 어댑터는 `io.close(...)` 전에 해당 HTTP server 참조를 분리하므로 client cleanup은 실행되지만 Socket.IO가 adapter-owned/shared HTTP listener를 닫지는 않습니다. 동일한 managed Socket.IO instance 주변에 별도의 manual socket-disconnect 경로를 추가하지 마세요.
+애플리케이션 종료 중 Socket.IO client 정리는 Socket.IO가 소유하지만 underlying HTTP server는 이를 제공한 platform adapter 또는 shared HTTP server 통합이 계속 소유합니다. 어댑터는 `io.close(...)` 전에 해당 HTTP server 참조를 분리하므로 client cleanup은 실행되지만 Socket.IO가 adapter-owned/shared HTTP listener를 닫지는 않습니다. Graceful Socket.IO close가 `shutdown.timeoutMs`를 넘으면 어댑터는 lifecycle state를 정리하기 전에 managed Socket.IO client를 force-disconnect합니다. 해당 force cleanup도 실패하면 shutdown retry를 위해 managed server reference와 registry를 보존합니다. 동일한 managed Socket.IO instance 주변에 별도의 manual socket-disconnect 경로를 추가하지 마세요.
 
 ### Guard 계약
 
@@ -130,7 +130,7 @@ Socket.IO 등록은 소유 모듈의 import 경로에서 구성하여 namespace/
 - `SOCKETIO_ROOM_SERVICE`
 - `SocketIoRoomService`: 공유 room 계약에 Socket.IO namespace-aware `joinRoom`, `leaveRoom`, `broadcastToRoom`, `getRooms` helper를 더한 타입입니다.
 - `SocketIoLifecycleService`: server와 room-service token 뒤에서 동작하는 lifecycle 기반 구현입니다. 애플리케이션 코드는 일반적으로 `SOCKETIO_SERVER` 또는 `SOCKETIO_ROOM_SERVICE`를 주입하세요.
-- 타입: `SocketIoModuleOptions`, `SocketIoConnectionGuardContext`, `SocketIoConnectionGuard`, `SocketIoMessageGuardContext`, `SocketIoMessageGuard`, `SocketIoGuardRejection`.
+- 타입: `SocketIoModuleOptions`, `SocketIoHandshakeRequest`, `SocketIoConnectionGuardContext`, `SocketIoConnectionGuard`, `SocketIoMessageGuardContext`, `SocketIoMessageGuard`, `SocketIoGuardRejection`.
 
 `SocketIoModuleOptions`는 `global`, `auth`, `buffer`, `cors`, `engine`, `shutdown`, `transports`를 포함합니다. `global`의 기본값은 `true`이므로 `SOCKETIO_SERVER`와 `SOCKETIO_ROOM_SERVICE`가 앱 전체에서 보입니다. module-local provider visibility가 필요하면 `false`로 설정하세요. 지원되는 server-backed runtime adapter가 필요하며, unsupported/noop adapter는 bootstrap 중 빠르게 실패합니다.
 

package/README.md

@@ -105,11 +105,11 @@ SocketIoModule.forRoot({
 });
 ```
 
-When `cors` is omitted, `@fluojs/socket.io` defaults to `{ credentials: false, origin: false }` so cross-origin exposure stays opt-in. When `engine.maxHttpBufferSize` is omitted, the adapter applies a bounded 1 MiB Engine.IO payload limit. Defaults also include `buffer.maxPendingMessagesPerSocket: 128`, `buffer.overflowPolicy: 'drop-oldest'`, and `shutdown.timeoutMs: 5000`.
+When `cors` is omitted, `@fluojs/socket.io` defaults to `{ credentials: false, origin: false }` so cross-origin exposure stays opt-in. When `engine.maxHttpBufferSize` is omitted, the adapter applies a bounded 1 MiB Engine.IO payload limit. Defaults also include `buffer.maxPendingMessagesPerSocket: 128`, `buffer.overflowPolicy: 'drop-oldest'`, and `shutdown.timeoutMs: 5000`. Explicit `engine.maxHttpBufferSize`, `buffer.maxPendingMessagesPerSocket`, and `shutdown.timeoutMs` values must be positive integers; invalid explicit values fail during module registration instead of falling back to defaults.
 
 Static `@WebSocketGateway({ path })` namespaces are owned by fluo's gateway discovery and are not treated as Socket.IO dynamic child namespaces. The adapter keeps Socket.IO's `cleanupEmptyChildNamespaces` behavior disabled for those static namespaces. If application code creates dynamic child namespaces through raw `SOCKETIO_SERVER` access, that ownership and cleanup policy stays with the application-level Socket.IO integration.
 
-During application shutdown, Socket.IO owns cleanup for connected Socket.IO clients, but the underlying HTTP server remains owned by the platform adapter or shared HTTP server integration that supplied it. The adapter detaches that HTTP server reference before `io.close(...)`, so client cleanup still runs while Socket.IO does not close adapter-owned/shared HTTP listeners. Do not add a second manual socket-disconnect path around the same managed Socket.IO instance.
+During application shutdown, Socket.IO owns cleanup for connected Socket.IO clients, but the underlying HTTP server remains owned by the platform adapter or shared HTTP server integration that supplied it. The adapter detaches that HTTP server reference before `io.close(...)`, so client cleanup still runs while Socket.IO does not close adapter-owned/shared HTTP listeners. If graceful Socket.IO close exceeds `shutdown.timeoutMs`, the adapter force-disconnects managed Socket.IO clients before clearing lifecycle state; if that force cleanup fails, the managed server reference and registries are retained for shutdown retry. Do not add a second manual socket-disconnect path around the same managed Socket.IO instance.
 
 ### Guard contracts
 
@@ -132,7 +132,7 @@ Register Socket.IO through module imports in the owning module so namespace/mess
 - `SOCKETIO_ROOM_SERVICE`: Token to inject the `SocketIoRoomService`.
 - `SocketIoRoomService`: Shared room contract plus Socket.IO namespace-aware `joinRoom`, `leaveRoom`, `broadcastToRoom`, and `getRooms` helpers.
 - `SocketIoLifecycleService`: Lifecycle-backed implementation behind the server and room-service tokens; application code should usually inject `SOCKETIO_SERVER` or `SOCKETIO_ROOM_SERVICE` instead.
-- Types: `SocketIoModuleOptions`, `SocketIoConnectionGuardContext`, `SocketIoConnectionGuard`, `SocketIoMessageGuardContext`, `SocketIoMessageGuard`, `SocketIoGuardRejection`.
+- Types: `SocketIoModuleOptions`, `SocketIoHandshakeRequest`, `SocketIoConnectionGuardContext`, `SocketIoConnectionGuard`, `SocketIoMessageGuardContext`, `SocketIoMessageGuard`, `SocketIoGuardRejection`.
 
 `SocketIoModuleOptions` covers `global`, `auth`, `buffer`, `cors`, `engine`, `shutdown`, and `transports`. `global` defaults to `true`, which keeps `SOCKETIO_SERVER` and `SOCKETIO_ROOM_SERVICE` visible across the app; set it to `false` when you want module-local provider visibility. A supported server-backed runtime adapter is required; unsupported/noop adapters fail fast during bootstrap.
 

package/dist/adapter.d.ts

@@ -32,6 +32,7 @@ export declare class SocketIoLifecycleService implements OnApplicationBootstrap,
      * @throws {Error} When the selected realtime capability cannot expose the server contract Socket.IO requires.
      */
     getServer(): Server;
+    getServerAsync(): Promise<Server>;
     /**
      * Discovers gateway classes and binds their handlers to the resolved namespaces once per application lifecycle.
      */
@@ -77,6 +78,7 @@ export declare class SocketIoLifecycleService implements OnApplicationBootstrap,
      */
     getRooms(socketId: string): ReadonlySet<string>;
     private createServerOptions;
+    private createNodeServer;
     private createBunEngineOptions;
     private resolveCorsOptions;
     private resolveMaxHttpBufferSize;
@@ -117,5 +119,6 @@ export declare class SocketIoLifecycleService implements OnApplicationBootstrap,
     private shutdown;
     private runShutdownLifecycle;
     private closeServerWithTimeout;
+    private clearManagedState;
 }
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter.js

@@ -7,17 +7,14 @@ function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side
 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;
+import { DEFAULT_SOCKETIO_ENGINE_PATH, resolveSocketIoMaxHttpBufferSize, resolveSocketIoMaxPendingMessagesPerSocket, resolveSocketIoShutdownTimeoutMs } from './config.internal.js';
+import { closeSocketIoServerWithTimeout } from './shutdown.internal.js';
+async function loadBunEngineServer() {
+  return (await import('@socket.io/bun-engine')).Server;
 }
 function normalizeGuardRejection(result, defaultMessage) {
   if (result === undefined || result === true) {
@@ -195,15 +192,25 @@ class SocketIoLifecycleService {
     }
     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());
+      this.io = this.createNodeServer(runtime);
+      return this.io;
+    }
+    throw new Error('Socket.IO Bun engine bootstrap is asynchronous. Use getServerAsync() for Bun-style adapters.');
+  }
+  async getServerAsync() {
+    if (this.shutdownStarted) {
+      throw new Error('Socket.IO server access is unavailable after application shutdown has started.');
+    }
+    if (this.io) {
+      return this.io;
+    }
+    const runtime = resolveSocketIoBootstrapRuntime(this.adapter);
+    if (runtime.kind === 'server-backed') {
+      this.io = this.createNodeServer(runtime);
       return this.io;
     }
     this.io = new Server(this.createServerOptions());
-    this.installBunSocketIoBinding(runtime, this.io);
+    await this.installBunSocketIoBinding(runtime, this.io);
     return this.io;
   }
 
@@ -216,11 +223,11 @@ class SocketIoLifecycleService {
     }
     const descriptors = this.discoverGatewayDescriptors();
     if (descriptors.length === 0) {
-      this.ensureBunRealtimeBindingForRawServerAccess();
+      await this.ensureBunRealtimeBindingForRawServerAccess();
       return;
     }
     this.assertNoServerBackedGatewayOptIn(descriptors);
-    const io = this.getServer();
+    const io = await this.getServerAsync();
     const attachments = this.prepareNamespaceAttachments(io, descriptors);
     for (const attachment of attachments) {
       this.bindNamespaceHandlers(attachment);
@@ -317,6 +324,13 @@ class SocketIoLifecycleService {
     }
     return options;
   }
+  createNodeServer(runtime) {
+    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.');
+    }
+    return new Server(httpServer, this.createServerOptions());
+  }
   createBunEngineOptions() {
     const options = {
       path: DEFAULT_SOCKETIO_ENGINE_PATH
@@ -332,16 +346,13 @@ class SocketIoLifecycleService {
     };
   }
   resolveMaxHttpBufferSize() {
-    const configured = this.moduleOptions.engine?.maxHttpBufferSize;
-    if (!isFinitePositiveInteger(configured)) {
-      return DEFAULT_SOCKETIO_MAX_HTTP_BUFFER_SIZE;
-    }
-    return configured;
+    return resolveSocketIoMaxHttpBufferSize(this.moduleOptions);
   }
-  installBunSocketIoBinding(runtime, io) {
+  async installBunSocketIoBinding(runtime, io) {
     if (this.bunEngine) {
       return;
     }
+    const BunEngineServer = await loadBunEngineServer();
     const engine = new BunEngineServer(this.createBunEngineOptions());
     io.bind(engine);
     runtime.bindingHost.configureRealtimeBinding(this.createBunSocketIoBinding(engine));
@@ -378,11 +389,11 @@ class SocketIoLifecycleService {
   matchesSocketIoEnginePath(pathname) {
     return pathname === '/socket.io' || pathname === DEFAULT_SOCKETIO_ENGINE_PATH;
   }
-  ensureBunRealtimeBindingForRawServerAccess() {
+  async ensureBunRealtimeBindingForRawServerAccess() {
     if (!hasBunRealtimeBindingHost(this.adapter)) {
       return;
     }
-    this.getServer();
+    await this.getServerAsync();
   }
   assertNoServerBackedGatewayOptIn(descriptors) {
     const runtime = resolveSocketIoBootstrapRuntime(this.adapter);
@@ -506,7 +517,7 @@ class SocketIoLifecycleService {
     };
   }
   maxPendingMessagesPerSocket() {
-    return isFinitePositiveInteger(this.moduleOptions.buffer?.maxPendingMessagesPerSocket) ? this.moduleOptions.buffer.maxPendingMessagesPerSocket : DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET;
+    return resolveSocketIoMaxPendingMessagesPerSocket(this.moduleOptions);
   }
   attachConnectionListeners(state, resolved, socket, request) {
     socket.onAny((event, ...args) => {
@@ -710,13 +721,19 @@ class SocketIoLifecycleService {
   createGatewayDescriptor(candidate, path) {
     const metadata = getWebSocketGatewayMetadata(candidate.targetType);
     const entries = getWebSocketHandlerMetadataEntries(candidate.targetType.prototype);
+    const handlers = entries.map(entry => ({
+      event: entry.metadata.event,
+      methodKey: entry.propertyKey,
+      methodName: methodKeyToName(entry.propertyKey),
+      type: entry.metadata.type
+    }));
+    const handlerIndex = createGatewayHandlerIndex(handlers);
     return {
-      handlers: entries.map(entry => ({
-        event: entry.metadata.event,
-        methodKey: entry.propertyKey,
-        methodName: methodKeyToName(entry.propertyKey),
-        type: entry.metadata.type
-      })),
+      connectHandlers: handlerIndex.connectHandlers,
+      disconnectHandlers: handlerIndex.disconnectHandlers,
+      handlers,
+      messageHandlersByEvent: handlerIndex.messageHandlersByEvent,
+      wildcardMessageHandlers: handlerIndex.wildcardMessageHandlers,
       moduleName: candidate.moduleName,
       path: normalizeGatewayPath(path),
       serverBacked: metadata?.serverBacked,
@@ -758,11 +775,7 @@ class SocketIoLifecycleService {
     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);
+    return resolveSocketIoShutdownTimeoutMs(this.moduleOptions);
   }
   async shutdown() {
     if (this.shutdownPromise) {
@@ -779,51 +792,70 @@ class SocketIoLifecycleService {
   }
   async runShutdownLifecycle() {
     const io = this.io;
-    this.wired = false;
     if (!io) {
-      this.attachments = [];
-      this.socketRegistry.clear();
+      this.clearManagedState();
       return;
     }
+    let shouldClearManagedState = false;
+    const timeoutMs = this.resolveShutdownTimeoutMs();
     try {
-      await this.closeServerWithTimeout(io, this.resolveShutdownTimeoutMs());
+      const result = await this.closeServerWithTimeout(io, timeoutMs);
+      shouldClearManagedState = true;
+      if (result.kind === 'forced') {
+        this.logger.error(`Failed to close Socket.IO server within ${String(timeoutMs)}ms; force-disconnected managed Socket.IO clients before clearing lifecycle state.`, result.timeoutError, 'SocketIoLifecycleService');
+      }
     } catch (error) {
-      this.logger.error(`Failed to close Socket.IO server within ${String(this.resolveShutdownTimeoutMs())}ms.`, error, 'SocketIoLifecycleService');
+      this.logger.error(`Failed to close Socket.IO server within ${String(timeoutMs)}ms; retaining managed Socket.IO state for shutdown retry.`, error, 'SocketIoLifecycleService');
     } finally {
-      this.io = undefined;
-      this.bunEngine = undefined;
-      this.attachments = [];
-      if (hasBunRealtimeBindingHost(this.adapter)) {
-        this.adapter.configureRealtimeBinding(undefined);
+      if (shouldClearManagedState) {
+        this.clearManagedState();
       }
-      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);
-
-      // Socket.IO owns client cleanup; the shared HTTP server remains owned by the platform adapter.
-      io.httpServer = undefined;
-      io.close(() => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        clearTimeout(timeout);
-        resolve();
-      });
-    });
+    return closeSocketIoServerWithTimeout(io, timeoutMs);
+  }
+  clearManagedState() {
+    this.wired = false;
+    this.io = undefined;
+    this.bunEngine = undefined;
+    this.attachments = [];
+    if (hasBunRealtimeBindingHost(this.adapter)) {
+      this.adapter.configureRealtimeBinding(undefined);
+    }
+    this.socketRegistry.clear();
   }
   static {
     _initClass();
   }
 }
-export { _SocketIoLifecycleSer as SocketIoLifecycleService };
+export { _SocketIoLifecycleSer as SocketIoLifecycleService };
+function createGatewayHandlerIndex(handlers) {
+  const connectHandlers = [];
+  const disconnectHandlers = [];
+  const messageHandlersByEvent = new Map();
+  const wildcardMessageHandlers = [];
+  for (const handler of handlers) {
+    if (handler.type === 'connect') {
+      connectHandlers.push(handler);
+      continue;
+    }
+    if (handler.type === 'disconnect') {
+      disconnectHandlers.push(handler);
+      continue;
+    }
+    if (handler.event === undefined) {
+      wildcardMessageHandlers.push(handler);
+      continue;
+    }
+    const eventHandlers = messageHandlersByEvent.get(handler.event) ?? [];
+    eventHandlers.push(handler);
+    messageHandlersByEvent.set(handler.event, eventHandlers);
+  }
+  return {
+    connectHandlers,
+    disconnectHandlers,
+    messageHandlersByEvent,
+    wildcardMessageHandlers
+  };
+}

package/dist/config.internal.d.ts

@@ -0,0 +1,37 @@
+import type { SocketIoModuleOptions } from './types.js';
+/** Default number of pre-connect Socket.IO messages buffered per socket. */
+export declare const DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET = 128;
+/** Default Engine.IO request path used by Socket.IO transports. */
+export declare const DEFAULT_SOCKETIO_ENGINE_PATH = "/socket.io/";
+/** Default maximum inbound Engine.IO payload size in bytes. */
+export declare const DEFAULT_SOCKETIO_MAX_HTTP_BUFFER_SIZE = 1048576;
+/** Default graceful Socket.IO shutdown timeout in milliseconds. */
+export declare const DEFAULT_SOCKETIO_SHUTDOWN_TIMEOUT_MS = 5000;
+/**
+ * Assert that explicit Socket.IO numeric options are positive integers.
+ *
+ * @param options Module options supplied to `SocketIoModule.forRoot(...)`.
+ */
+export declare function assertValidSocketIoModuleOptions(options: SocketIoModuleOptions): void;
+/**
+ * Resolve the effective Socket.IO Engine.IO payload bound.
+ *
+ * @param options Module options supplied to `SocketIoModule.forRoot(...)`.
+ * @returns The explicit payload bound or the package default.
+ */
+export declare function resolveSocketIoMaxHttpBufferSize(options: SocketIoModuleOptions): number;
+/**
+ * Resolve the effective pending-message buffer limit.
+ *
+ * @param options Module options supplied to `SocketIoModule.forRoot(...)`.
+ * @returns The explicit per-socket buffer limit or the package default.
+ */
+export declare function resolveSocketIoMaxPendingMessagesPerSocket(options: SocketIoModuleOptions): number;
+/**
+ * Resolve the effective Socket.IO shutdown timeout.
+ *
+ * @param options Module options supplied to `SocketIoModule.forRoot(...)`.
+ * @returns The explicit shutdown timeout or the package default.
+ */
+export declare function resolveSocketIoShutdownTimeoutMs(options: SocketIoModuleOptions): number;
+//# sourceMappingURL=config.internal.d.ts.map

package/dist/config.internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.internal.d.ts","sourceRoot":"","sources":["../src/config.internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,4EAA4E;AAC5E,eAAO,MAAM,uCAAuC,MAAM,CAAC;AAE3D,mEAAmE;AACnE,eAAO,MAAM,4BAA4B,gBAAgB,CAAC;AAE1D,+DAA+D;AAC/D,eAAO,MAAM,qCAAqC,UAAY,CAAC;AAE/D,mEAAmE;AACnE,eAAO,MAAM,oCAAoC,OAAQ,CAAC;AAmB1D;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAIrF;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAEvF;AAED;;;;;GAKG;AACH,wBAAgB,0CAA0C,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAEjG;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAEvF"}

package/dist/config.internal.js

@@ -0,0 +1,61 @@
+/** Default number of pre-connect Socket.IO messages buffered per socket. */
+export const DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET = 128;
+
+/** Default Engine.IO request path used by Socket.IO transports. */
+export const DEFAULT_SOCKETIO_ENGINE_PATH = '/socket.io/';
+
+/** Default maximum inbound Engine.IO payload size in bytes. */
+export const DEFAULT_SOCKETIO_MAX_HTTP_BUFFER_SIZE = 1_048_576;
+
+/** Default graceful Socket.IO shutdown timeout in milliseconds. */
+export const DEFAULT_SOCKETIO_SHUTDOWN_TIMEOUT_MS = 5_000;
+function isPositiveInteger(value) {
+  return typeof value === 'number' && Number.isInteger(value) && Number.isFinite(value) && value > 0;
+}
+function assertOptionalPositiveInteger(value, path) {
+  if (value === undefined || isPositiveInteger(value)) {
+    return;
+  }
+  throw new Error(`Socket.IO configuration ${path} must be a positive integer when provided.`);
+}
+
+/**
+ * Assert that explicit Socket.IO numeric options are positive integers.
+ *
+ * @param options Module options supplied to `SocketIoModule.forRoot(...)`.
+ */
+export function assertValidSocketIoModuleOptions(options) {
+  assertOptionalPositiveInteger(options.engine?.maxHttpBufferSize, 'engine.maxHttpBufferSize');
+  assertOptionalPositiveInteger(options.buffer?.maxPendingMessagesPerSocket, 'buffer.maxPendingMessagesPerSocket');
+  assertOptionalPositiveInteger(options.shutdown?.timeoutMs, 'shutdown.timeoutMs');
+}
+
+/**
+ * Resolve the effective Socket.IO Engine.IO payload bound.
+ *
+ * @param options Module options supplied to `SocketIoModule.forRoot(...)`.
+ * @returns The explicit payload bound or the package default.
+ */
+export function resolveSocketIoMaxHttpBufferSize(options) {
+  return options.engine?.maxHttpBufferSize ?? DEFAULT_SOCKETIO_MAX_HTTP_BUFFER_SIZE;
+}
+
+/**
+ * Resolve the effective pending-message buffer limit.
+ *
+ * @param options Module options supplied to `SocketIoModule.forRoot(...)`.
+ * @returns The explicit per-socket buffer limit or the package default.
+ */
+export function resolveSocketIoMaxPendingMessagesPerSocket(options) {
+  return options.buffer?.maxPendingMessagesPerSocket ?? DEFAULT_MAX_PENDING_MESSAGES_PER_SOCKET;
+}
+
+/**
+ * Resolve the effective Socket.IO shutdown timeout.
+ *
+ * @param options Module options supplied to `SocketIoModule.forRoot(...)`.
+ * @returns The explicit shutdown timeout or the package default.
+ */
+export function resolveSocketIoShutdownTimeoutMs(options) {
+  return options.shutdown?.timeoutMs ?? DEFAULT_SOCKETIO_SHUTDOWN_TIMEOUT_MS;
+}

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAQhE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAwBxD;;GAEG;AACH,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAShE"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAShE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAwBxD;;GAEG;AACH,qBAAa,cAAc;IACzB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU;CAWhE"}

package/dist/module.js

@@ -1,4 +1,5 @@
 import { defineModule } from '@fluojs/runtime';
+import { assertValidSocketIoModuleOptions } from './config.internal.js';
 import { SOCKETIO_OPTIONS_INTERNAL } from './options-token.internal.js';
 import { SocketIoLifecycleService } from './adapter.js';
 import { SOCKETIO_ROOM_SERVICE, SOCKETIO_SERVER } from './tokens.js';
@@ -11,7 +12,7 @@ function createSocketIoProviderSet(options = {}) {
     useClass: SocketIoLifecycleService
   }, {
     provide: SOCKETIO_SERVER,
-    useFactory: service => service.getServer(),
+    useFactory: async service => await service.getServerAsync(),
     inject: [SocketIoLifecycleService]
   }, {
     provide: SOCKETIO_ROOM_SERVICE,
@@ -41,6 +42,7 @@ export class SocketIoModule {
    * ```
    */
   static forRoot(options = {}) {
+    assertValidSocketIoModuleOptions(options);
     class SocketIoRuntimeModule extends SocketIoModule {}
     return defineModule(SocketIoRuntimeModule, {
       exports: [SOCKETIO_ROOM_SERVICE, SOCKETIO_SERVER],

package/dist/shutdown.internal.d.ts

@@ -0,0 +1,25 @@
+/** Result of a bounded Socket.IO close attempt. */
+export interface SocketIoCloseResult {
+    readonly kind: 'closed' | 'forced';
+    readonly timeoutError?: SocketIoShutdownTimeoutError;
+}
+/** Minimal Socket.IO server surface required for lifecycle shutdown. */
+export interface SocketIoCloseTarget {
+    close(callback?: () => void): unknown;
+    disconnectSockets?: (close?: boolean) => unknown;
+    httpServer?: unknown;
+}
+/** Error retained when Socket.IO shutdown exceeds the configured timeout. */
+export declare class SocketIoShutdownTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Close a Socket.IO server while bounding graceful cleanup time.
+ *
+ * @param io Socket.IO close target managed by the lifecycle service.
+ * @param timeoutMs Maximum graceful close duration before managed clients are force-disconnected.
+ * @returns A close result that identifies graceful completion or forced client cleanup.
+ */
+export declare function closeSocketIoServerWithTimeout(io: SocketIoCloseTarget, timeoutMs: number): Promise<SocketIoCloseResult>;
+//# sourceMappingURL=shutdown.internal.d.ts.map

package/dist/shutdown.internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.internal.d.ts","sourceRoot":"","sources":["../src/shutdown.internal.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,4BAA4B,CAAC;CACtD;AAED,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;IACtC,iBAAiB,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,6EAA6E;AAC7E,qBAAa,4BAA6B,SAAQ,KAAK;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAIvC;AAUD;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,EAAE,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwCvH"}

package/dist/shutdown.internal.js

@@ -0,0 +1,66 @@
+/** Result of a bounded Socket.IO close attempt. */
+
+/** Minimal Socket.IO server surface required for lifecycle shutdown. */
+
+/** Error retained when Socket.IO shutdown exceeds the configured timeout. */
+export class SocketIoShutdownTimeoutError extends Error {
+  constructor(timeoutMs) {
+    super(`Timed out while closing Socket.IO server after ${String(timeoutMs)}ms.`);
+    this.timeoutMs = timeoutMs;
+    this.name = 'SocketIoShutdownTimeoutError';
+  }
+}
+function detachAdapterOwnedHttpServer(io) {
+  io.httpServer = undefined;
+}
+function forceDisconnectManagedClients(io) {
+  io.disconnectSockets?.(true);
+}
+
+/**
+ * Close a Socket.IO server while bounding graceful cleanup time.
+ *
+ * @param io Socket.IO close target managed by the lifecycle service.
+ * @param timeoutMs Maximum graceful close duration before managed clients are force-disconnected.
+ * @returns A close result that identifies graceful completion or forced client cleanup.
+ */
+export function closeSocketIoServerWithTimeout(io, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      const timeoutError = new SocketIoShutdownTimeoutError(timeoutMs);
+      try {
+        forceDisconnectManagedClients(io);
+      } catch (error) {
+        settled = true;
+        reject(error);
+        return;
+      }
+      settled = true;
+      resolve({
+        kind: 'forced',
+        timeoutError
+      });
+    }, timeoutMs);
+    detachAdapterOwnedHttpServer(io);
+    try {
+      io.close(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timeout);
+        resolve({
+          kind: 'closed'
+        });
+      });
+    } catch (error) {
+      settled = true;
+      clearTimeout(timeout);
+      reject(error);
+    }
+  });
+}

package/package.json

@@ -9,7 +9,7 @@
     "realtime",
     "platform"
   ],
-  "version": "1.0.4",
+  "version": "1.0.5",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -38,10 +38,10 @@
   "dependencies": {
     "@socket.io/bun-engine": "^0.1.0",
     "@fluojs/core": "^1.0.3",
-    "@fluojs/di": "^1.0.3",
+    "@fluojs/di": "^1.1.0",
     "@fluojs/http": "^1.1.0",
-    "@fluojs/runtime": "^1.1.2",
-    "@fluojs/websockets": "^1.0.4"
+    "@fluojs/runtime": "^1.1.6",
+    "@fluojs/websockets": "^1.0.5"
   },
   "peerDependencies": {
     "socket.io": "^4.0.0"
@@ -50,9 +50,9 @@
     "socket.io": "^4.8.1",
     "socket.io-client": "^4.8.1",
     "vitest": "^3.2.4",
-    "@fluojs/platform-express": "^1.0.3",
-    "@fluojs/platform-fastify": "^1.0.4",
-    "@fluojs/platform-nodejs": "^1.0.3"
+    "@fluojs/platform-express": "^1.0.5",
+    "@fluojs/platform-fastify": "^1.0.6",
+    "@fluojs/platform-nodejs": "^1.0.5"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",