@fluojs/socket.io 1.0.6 → 1.0.7

package/README.ko.md

@@ -77,6 +77,34 @@ class MyService {
 }
 ```
 
+Raw server 접근은 좁게 유지하고, 공유 room 계약이 의도적으로 감싸지 않는 Socket.IO 전용 의미론에 사용하세요. 예를 들어 native multi-room emit이나 volatile delivery는 raw server 경계에 둡니다:
+
+```ts
+@Inject(SOCKETIO_SERVER)
+class SupportBroadcasts {
+  constructor(private readonly io: Server) {}
+
+  broadcastUrgent(message: string) {
+    this.io.of('/support').to(['ticket:active', 'staff:updates']).emit('announcement', { message });
+  }
+
+  sendTyping(ticketId: string, userId: string) {
+    this.io.of('/support').volatile.to(`ticket:${ticketId}`).emit('typing', { userId });
+  }
+}
+```
+
+### Handler return value와 ACK reply
+
+Socket.IO gateway handler는 공유 `@fluojs/websockets` positional handler 모델인 `(payload, socket, request, acknowledgement)`를 사용합니다. 반환값은 오류 격리와 순서를 위해 await되지만 무시됩니다. fluo는 handler 반환값을 암묵적인 Socket.IO emit 또는 ACK reply로 변환하지 않습니다. NestJS `@SubscribeMessage()` handler가 반환값으로 ACK payload를 보내던 경우에는 `acknowledgement` callback을 명시적으로 호출하거나 `SOCKETIO_SERVER`를 주입해 raw server 경계에서 emit하도록 재작성하세요.
+
+```ts
+@OnMessage('ping')
+handlePing(payload: unknown, _socket: Socket, _request: SocketIoHandshakeRequest, ack?: (response: unknown) => void) {
+  ack?.({ event: 'pong', payload });
+}
+```
+
 ### auth guard, 안전한 CORS 기본값, bounded payload
 `SocketIoModule.forRoot(...)`로 namespace/message 인증을 명시하고, CORS를 deny-by-default로 유지하며, 인바운드 Engine.IO payload 크기를 제한할 수 있습니다.
 
@@ -124,15 +152,15 @@ Socket.IO 등록은 소유 모듈의 import 경로에서 구성하여 namespace/
 
 ## 공개 API 개요
 
-- `SocketIoModule.forRoot(options)`
+- `SocketIoModule.forRoot(options)`: Socket.IO 통합의 기본 모듈입니다.
 - `SocketIoModule.forRoot({ global, auth, cors, engine, ... })`: provider visibility, namespace/message guard, 명시적 CORS, Engine.IO payload bound를 구성합니다.
-- `SOCKETIO_SERVER`
-- `SOCKETIO_ROOM_SERVICE`
+- `SOCKETIO_SERVER`: raw Socket.IO `Server`를 주입하기 위한 토큰입니다.
+- `SOCKETIO_ROOM_SERVICE`: `SocketIoRoomService`를 주입하기 위한 토큰입니다.
 - `SocketIoRoomService`: 공유 room 계약에 Socket.IO namespace-aware `joinRoom`, `leaveRoom`, `broadcastToRoom`, `getRooms` helper를 더한 타입입니다.
 - `SocketIoLifecycleService`: server와 room-service token 뒤에서 동작하는 lifecycle 기반 구현입니다. 애플리케이션 코드는 일반적으로 `SOCKETIO_SERVER` 또는 `SOCKETIO_ROOM_SERVICE`를 주입하세요.
 - 타입: `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 중 빠르게 실패합니다.
+`SocketIoModuleOptions`는 `global`, `auth`, `buffer`, `cors`, `engine`, `shutdown`, `transports`를 포함합니다. `global`의 기본값은 `true`이므로 `SOCKETIO_SERVER`와 `SOCKETIO_ROOM_SERVICE`가 앱 전체에서 보입니다. module-local provider visibility가 필요하면 `false`로 설정하세요. 지원되는 Node.js server-backed runtime adapter 또는 공식 Bun engine host가 필요하며, unsupported/noop adapter는 bootstrap 중 빠르게 실패합니다.
 
 ## 지원 플랫폼
 
@@ -145,5 +173,6 @@ Socket.IO 등록은 소유 모듈의 import 경로에서 구성하여 namespace/
 
 ## 예제 소스
 
+- `packages/socket.io/src/config.internal.test.ts`
 - `packages/socket.io/src/module.test.ts`
 - `packages/socket.io/src/public-surface.test.ts`

package/README.md

@@ -79,6 +79,34 @@ class MyService {
 }
 ```
 
+Keep raw server access narrow and use it for Socket.IO-specific semantics that the shared room contract intentionally does not wrap, such as multi-room native emits or volatile delivery:
+
+```typescript
+@Inject(SOCKETIO_SERVER)
+class SupportBroadcasts {
+  constructor(private readonly io: Server) {}
+
+  broadcastUrgent(message: string) {
+    this.io.of('/support').to(['ticket:active', 'staff:updates']).emit('announcement', { message });
+  }
+
+  sendTyping(ticketId: string, userId: string) {
+    this.io.of('/support').volatile.to(`ticket:${ticketId}`).emit('typing', { userId });
+  }
+}
+```
+
+### Handler return values and ACK replies
+
+Socket.IO gateway handlers use the shared `@fluojs/websockets` positional handler model: `(payload, socket, request, acknowledgement)`. Return values are awaited for error containment and ordering, but they are ignored; fluo does not convert a returned value into an implicit Socket.IO emit or ACK reply. When a migrated NestJS `@SubscribeMessage()` handler previously returned an ACK payload, rewrite it to call the `acknowledgement` callback explicitly or inject `SOCKETIO_SERVER` and emit through the raw server boundary.
+
+```typescript
+@OnMessage('ping')
+handlePing(payload: unknown, _socket: Socket, _request: SocketIoHandshakeRequest, ack?: (response: unknown) => void) {
+  ack?.({ event: 'pong', payload });
+}
+```
+
 ### Auth guards, safe CORS defaults, and bounded payloads
 Use `SocketIoModule.forRoot(...)` to require explicit namespace/message auth, keep CORS in a deny-by-default posture, and cap inbound Engine.IO payload size.
 
@@ -134,7 +162,7 @@ Register Socket.IO through module imports in the owning module so namespace/mess
 - `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`, `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.
+`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 Node.js server-backed runtime adapter or the official Bun engine host is required; unsupported/noop adapters fail fast during bootstrap.
 
 ## Supported Platforms
 
@@ -147,5 +175,6 @@ Register Socket.IO through module imports in the owning module so namespace/mess
 
 ## Example Sources
 
+- `packages/socket.io/src/config.internal.test.ts`
 - `packages/socket.io/src/module.test.ts`
 - `packages/socket.io/src/public-surface.test.ts`

package/dist/adapter.d.ts

@@ -19,7 +19,8 @@ export declare class SocketIoLifecycleService implements OnApplicationBootstrap,
     private attachments;
     private bunEngine;
     private io;
-    private readonly namespaceContext;
+    private namespaceContext;
+    private namespaceContextPromise;
     private readonly socketRegistry;
     private shutdownPromise;
     private shutdownStarted;
@@ -110,6 +111,7 @@ export declare class SocketIoLifecycleService implements OnApplicationBootstrap,
     private handleDisconnect;
     private runHandlers;
     private invokeGatewayMethod;
+    private resolveNamespaceContext;
     private resolveGatewayInstance;
     private discoverGatewayDescriptors;
     private shouldSkipGatewayCandidate;

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

@@ -4,14 +4,12 @@ function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol"
 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 { APPLICATION_LOGGER, COMPILED_MODULES, HTTP_APPLICATION_ADAPTER, RUNTIME_CONTAINER } from '@fluojs/runtime/internal';
+import { APPLICATION_LOGGER, COMPILED_MODULES, getRuntimeClassDiMetadata, 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';
 import { DEFAULT_SOCKETIO_ENGINE_PATH, resolveSocketIoMaxHttpBufferSize, resolveSocketIoMaxPendingMessagesPerSocket, resolveSocketIoShutdownTimeoutMs } from './config.internal.js';
+import { SOCKETIO_OPTIONS_INTERNAL } from './options-token.internal.js';
 import { closeSocketIoServerWithTimeout } from './shutdown.internal.js';
 async function loadBunEngineServer() {
   return (await import('@socket.io/bun-engine')).Server;
@@ -55,11 +53,11 @@ function normalizeRejectedGuardError(error, defaultMessage) {
 }
 function scopeFromProvider(provider) {
   if (typeof provider === 'function') {
-    return getClassDiMetadata(provider)?.scope ?? 'singleton';
+    return getRuntimeClassDiMetadata(provider)?.scope ?? 'singleton';
   }
   if ('useClass' in provider) {
     const classProvider = provider;
-    return classProvider.scope ?? getClassDiMetadata(classProvider.useClass)?.scope ?? 'singleton';
+    return classProvider.scope ?? getRuntimeClassDiMetadata(classProvider.useClass)?.scope ?? 'singleton';
   }
   return 'scope' in provider ? provider.scope ?? 'singleton' : 'singleton';
 }
@@ -164,7 +162,8 @@ class SocketIoLifecycleService {
   attachments = [];
   bunEngine;
   io;
-  namespaceContext = new AsyncLocalStorage();
+  namespaceContext;
+  namespaceContextPromise;
   socketRegistry = new Map();
   shutdownPromise;
   shutdownStarted = false;
@@ -427,7 +426,7 @@ class SocketIoLifecycleService {
     return this.attachments.find(attachment => attachment.path === path)?.namespace;
   }
   resolveContextNamespace() {
-    const namespaceName = this.namespaceContext.getStore();
+    const namespaceName = this.namespaceContext?.getStore();
     if (!namespaceName) {
       return undefined;
     }
@@ -683,11 +682,27 @@ class SocketIoLifecycleService {
       return;
     }
     try {
-      await this.namespaceContext.run(descriptor.path, async () => await Promise.resolve(value.call(instance, ...args)));
+      const namespaceContext = await this.resolveNamespaceContext();
+      await 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 resolveNamespaceContext() {
+    if (this.namespaceContext) {
+      return this.namespaceContext;
+    }
+    this.namespaceContextPromise ??= import('node:async_hooks').then(({
+      AsyncLocalStorage
+    }) => {
+      this.namespaceContext = new AsyncLocalStorage();
+      return this.namespaceContext;
+    }).catch(error => {
+      this.namespaceContextPromise = undefined;
+      throw error;
+    });
+    return this.namespaceContextPromise;
+  }
   async resolveGatewayInstance(descriptor) {
     try {
       return await this.runtimeContainer.resolve(descriptor.token);

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage } from 'node:http';
-import type { ServerOptions, Socket } from 'socket.io';
 import type { WebSocketRoomService } from '@fluojs/websockets';
+import type { ServerOptions, Socket } from 'socket.io';
 /** Runtime-specific Socket.IO handshake request surfaced to guard callbacks. */
 export type SocketIoHandshakeRequest = IncomingMessage | Request;
 /**
@@ -34,6 +34,13 @@ export interface SocketIoRoomService extends WebSocketRoomService {
      * @param namespacePath Optional namespace path when targeting a non-default namespace.
      */
     leaveRoom(socketId: string, room: string, namespacePath?: string): void;
+    /**
+     * Returns a snapshot of rooms currently joined by one connected socket.
+     *
+     * @param socketId Socket identifier to inspect.
+     * @returns Current room names for the socket, or an empty set when the socket is not registered.
+     */
+    getRooms(socketId: string): ReadonlySet<string>;
 }
 /**
  * Rejection details returned by Socket.IO auth guards when a connection or message should be blocked.

package/dist/types.d.ts.map

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

package/package.json

@@ -9,7 +9,7 @@
     "realtime",
     "platform"
   ],
-  "version": "1.0.6",
+  "version": "1.0.7",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -39,9 +39,9 @@
     "@socket.io/bun-engine": "^0.1.0",
     "@fluojs/core": "^1.0.3",
     "@fluojs/di": "^1.1.0",
-    "@fluojs/http": "^1.1.1",
-    "@fluojs/runtime": "^1.1.7",
-    "@fluojs/websockets": "^1.0.6"
+    "@fluojs/http": "^1.1.2",
+    "@fluojs/runtime": "^1.1.8",
+    "@fluojs/websockets": "^1.0.7"
   },
   "peerDependencies": {
     "socket.io": "^4.0.0"
@@ -51,7 +51,7 @@
     "socket.io-client": "^4.8.1",
     "vitest": "^3.2.4",
     "@fluojs/platform-express": "^1.0.6",
-    "@fluojs/platform-fastify": "^1.0.7",
+    "@fluojs/platform-fastify": "^1.0.8",
     "@fluojs/platform-nodejs": "^1.0.5"
   },
   "scripts": {