@fluojs/socket.io 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,124 @@
+# @fluojs/socket.io
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo 런타임용 Socket.IO v4 게이트웨이 어댑터입니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 패턴](#주요-패턴)
+- [공개 API 개요](#공개-api-개요)
+- [지원 플랫폼](#지원-플랫폼)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/core @fluojs/socket.io @fluojs/websockets socket.io
+```
+
+## 사용 시점
+
+Socket.IO가 제공하는 room, namespace, broadcast, 자동 재연결 같은 고수준 실시간 기능이 필요할 때 사용합니다. 이 패키지는 raw websocket 대신 Socket.IO v4 서버를 fluo의 `@WebSocketGateway` 기반 모델에 연결합니다.
+
+## 빠른 시작
+
+```ts
+import { Inject, Module } from '@fluojs/core';
+import { SOCKETIO_ROOM_SERVICE, SocketIoModule, type SocketIoRoomService } from '@fluojs/socket.io';
+import { OnMessage, WebSocketGateway } from '@fluojs/websockets';
+
+@Inject(SOCKETIO_ROOM_SERVICE)
+@WebSocketGateway({ path: '/chat' })
+class ChatGateway {
+  constructor(private readonly rooms: SocketIoRoomService) {}
+
+  @OnMessage('ping')
+  handlePing(payload: unknown) {
+    this.rooms.broadcastToRoom('chat:lobby', 'pong', payload);
+  }
+}
+
+@Module({
+  imports: [SocketIoModule.forRoot()],
+  providers: [ChatGateway],
+})
+export class AppModule {}
+```
+
+## 주요 패턴
+
+### Room 관리
+
+```ts
+this.rooms.joinRoom(socket.id, 'room:123');
+this.rooms.broadcastToRoom('room:123', 'event', data);
+```
+
+### Raw Socket.IO 서버 접근
+
+```ts
+import { SOCKETIO_SERVER } from '@fluojs/socket.io';
+import type { Server } from 'socket.io';
+
+@Inject(SOCKETIO_SERVER)
+class MyService {
+  constructor(private readonly io: Server) {}
+}
+```
+
+### auth guard, 안전한 CORS 기본값, bounded payload
+`SocketIoModule.forRoot(...)`로 namespace/message 인증을 명시하고, CORS를 deny-by-default로 유지하며, 인바운드 Engine.IO payload 크기를 제한할 수 있습니다.
+
+```ts
+SocketIoModule.forRoot({
+  auth: {
+    connection({ socket }) {
+      return socket.handshake.auth.token === 'demo-token'
+        ? true
+        : { message: 'Authentication required.' };
+    },
+    message({ payload }) {
+      return payload === 'allowed'
+        ? true
+        : { message: 'Forbidden event.' };
+    },
+  },
+  cors: {
+    origin: ['https://app.example.com'],
+  },
+  engine: {
+    maxHttpBufferSize: 65_536,
+  },
+});
+```
+
+이제 `cors`를 생략하면 `@fluojs/socket.io`는 `origin: false`를 기본값으로 사용하므로 cross-origin 노출은 명시적 opt-in이 필요합니다. `engine.maxHttpBufferSize`를 생략하면 어댑터가 1 MiB Engine.IO payload 상한을 적용합니다.
+
+### 모듈 등록
+`SocketIoModule.forRoot(...)`로 Socket.IO를 등록합니다.
+
+Socket.IO 등록은 소유 모듈의 import 경로에서 구성하여 namespace/message guard, CORS, Engine.IO 옵션을 한 곳에서 관리합니다.
+
+## 공개 API 개요
+
+- `SocketIoModule.forRoot(options)`
+- `SocketIoModule.forRoot({ auth, cors, engine, ... })`
+- `SOCKETIO_SERVER`
+- `SOCKETIO_ROOM_SERVICE`
+
+## 지원 플랫폼
+
+| 플랫폼 | 지원 여부 | 비고 |
+| --- | --- | --- |
+| Node.js (Raw/Express/Fastify) | ✅ 전체 지원 | server-backed mode |
+| Bun | ✅ 전체 지원 | `@socket.io/bun-engine` 기반 |
+| Deno | ❌ 미지원 | 현재 지원하지 않음 |
+| Workers | ❌ 미지원 | 현재 지원하지 않음 |
+
+## 예제 소스
+
+- `packages/socket.io/src/module.test.ts`

package/README.md

@@ -0,0 +1,126 @@
+# @fluojs/socket.io
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Socket.IO v4 gateway adapter for the fluo runtime.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API Overview](#public-api-overview)
+- [Supported Platforms](#supported-platforms)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/core @fluojs/socket.io @fluojs/websockets socket.io
+```
+
+## When to Use
+
+Use this package when you need advanced real-time features like rooms, namespaces, broadcasting, and automatic reconnection provided by [Socket.IO](https://socket.io/). This adapter integrates Socket.IO v4 into fluo's decorator-based architecture, sharing the same `@WebSocketGateway` core as raw websockets.
+
+## Quick Start
+
+```typescript
+import { SocketIoModule, SOCKETIO_ROOM_SERVICE, type SocketIoRoomService } from '@fluojs/socket.io';
+import { WebSocketGateway, OnMessage } from '@fluojs/websockets';
+import { Inject, Module } from '@fluojs/core';
+
+@Inject(SOCKETIO_ROOM_SERVICE)
+@WebSocketGateway({ path: '/chat' })
+class ChatGateway {
+  constructor(private readonly rooms: SocketIoRoomService) {}
+
+  @OnMessage('ping')
+  handlePing(payload: unknown) {
+    this.rooms.broadcastToRoom('chat:lobby', 'pong', payload);
+  }
+}
+
+@Module({
+  imports: [SocketIoModule.forRoot()],
+  providers: [ChatGateway],
+})
+export class AppModule {}
+```
+
+## Common Patterns
+
+### Room Management
+The `SocketIoRoomService` provides a high-level API for managing client rooms and broadcasting.
+
+```typescript
+this.rooms.joinRoom(socket.id, 'room:123');
+this.rooms.broadcastToRoom('room:123', 'event', data);
+```
+
+### Accessing the Raw Server
+You can inject the underlying Socket.IO `Server` instance for low-level control.
+
+```typescript
+import { SOCKETIO_SERVER } from '@fluojs/socket.io';
+import type { Server } from 'socket.io';
+
+@Inject(SOCKETIO_SERVER)
+class MyService {
+  constructor(private readonly io: Server) {}
+}
+```
+
+### 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.
+
+```typescript
+SocketIoModule.forRoot({
+  auth: {
+    connection({ socket }) {
+      return socket.handshake.auth.token === 'demo-token'
+        ? true
+        : { message: 'Authentication required.' };
+    },
+    message({ payload }) {
+      return payload === 'allowed'
+        ? true
+        : { message: 'Forbidden event.' };
+    },
+  },
+  cors: {
+    origin: ['https://app.example.com'],
+  },
+  engine: {
+    maxHttpBufferSize: 65_536,
+  },
+});
+```
+
+When `cors` is omitted, `@fluojs/socket.io` now defaults to `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.
+
+### Module registration
+Register Socket.IO with `SocketIoModule.forRoot(...)`.
+
+Register Socket.IO through module imports in the owning module so namespace/message guards, CORS, and Engine.IO options stay configured in one place.
+
+## Public API Overview
+
+- `SocketIoModule.forRoot(options)`: Main module for Socket.IO integration.
+- `SocketIoModule.forRoot({ auth, cors, engine, ... })`: Configures namespace/message guards plus explicit CORS and Engine.IO payload bounds.
+- `SOCKETIO_SERVER`: Token to inject the raw Socket.IO `Server`.
+- `SOCKETIO_ROOM_SERVICE`: Token to inject the `SocketIoRoomService`.
+
+## Supported Platforms
+
+| Platform | Support | Note |
+| --- | --- | --- |
+| Node.js (Raw/Express/Fastify) | ✅ Full | Server-backed mode |
+| Bun | ✅ Full | Via `@socket.io/bun-engine` |
+| Deno | ❌ None | Not currently supported |
+| Workers | ❌ None | Not currently supported |
+
+## Example Sources
+
+- `packages/socket.io/src/module.test.ts`

package/dist/adapter.d.ts

@@ -0,0 +1,118 @@
+import type { Container } from '@fluojs/di';
+import type { HttpApplicationAdapter } from '@fluojs/http';
+import type { ApplicationLogger, CompiledModule, OnApplicationBootstrap, OnApplicationShutdown, OnModuleDestroy } from '@fluojs/runtime';
+import { Server } from 'socket.io';
+import type { SocketIoModuleOptions, SocketIoRoomService } from './types.js';
+/**
+ * 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.
+ */
+export declare class SocketIoLifecycleService implements OnApplicationBootstrap, OnApplicationShutdown, OnModuleDestroy, SocketIoRoomService {
+    private readonly runtimeContainer;
+    private readonly compiledModules;
+    private readonly logger;
+    private readonly adapter;
+    private readonly moduleOptions;
+    private attachments;
+    private bunEngine;
+    private io;
+    private readonly namespaceContext;
+    private readonly socketRegistry;
+    private shutdownPromise;
+    private wired;
+    constructor(runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger, adapter: HttpApplicationAdapter, moduleOptions: SocketIoModuleOptions);
+    /**
+     * 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(): Server;
+    /**
+     * Discovers gateway classes and binds their handlers to the resolved namespaces once per application lifecycle.
+     */
+    onApplicationBootstrap(): Promise<void>;
+    /**
+     * Shuts down Socket.IO resources during application shutdown.
+     */
+    onApplicationShutdown(): Promise<void>;
+    /**
+     * Shuts down Socket.IO resources when the containing module is destroyed.
+     */
+    onModuleDestroy(): Promise<void>;
+    /**
+     * 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: string, room: string, namespacePath?: string): void;
+    /**
+     * 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: string, room: string, namespacePath?: string): void;
+    /**
+     * 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: string, event: string, data: unknown, namespacePath?: string): void;
+    /**
+     * 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: string): ReadonlySet<string>;
+    private createServerOptions;
+    private createBunEngineOptions;
+    private resolveCorsOptions;
+    private resolveMaxHttpBufferSize;
+    private installBunSocketIoBinding;
+    private createBunSocketIoBinding;
+    private tryResolvePathname;
+    private matchesSocketIoEnginePath;
+    private assertNoServerBackedGatewayOptIn;
+    private prepareNamespaceAttachments;
+    private resolveNamespace;
+    private resolveContextNamespace;
+    private resolveRequiredNamespace;
+    private resolveSocket;
+    private bindNamespaceHandlers;
+    private runConnectionGuard;
+    private bindConnectionHandlers;
+    private createConnectionHandlerState;
+    private maxPendingMessagesPerSocket;
+    private attachConnectionListeners;
+    private replayBufferedConnectionEvents;
+    private resolveConnectionGateways;
+    private runConnectHandlers;
+    private handleMessage;
+    private resolveMessageGuardRejection;
+    private reportRejectedMessage;
+    private selectMessageHandlers;
+    private handleDisconnect;
+    private runHandlers;
+    private invokeGatewayMethod;
+    private resolveGatewayInstance;
+    private discoverGatewayDescriptors;
+    private shouldSkipGatewayCandidate;
+    private createGatewayDescriptor;
+    private discoveryCandidates;
+    private resolveShutdownTimeoutMs;
+    private shutdown;
+    private runShutdownLifecycle;
+    private closeServerWithTimeout;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

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