@fluojs/websockets 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,133 @@
+# @fluojs/websockets
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo 런타임을 위한 데코레이터 기반 WebSocket 게이트웨이 작성 패키지입니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 패턴](#주요-패턴)
+- [공개 API 개요](#공개-api-개요)
+- [런타임별 서브패스](#런타임별-서브패스)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/websockets ws
+```
+
+## 사용 시점
+
+fluo 애플리케이션에 실시간 WebSocket 기능을 추가할 때 이 패키지를 사용합니다. 연결, 메시지 및 연결 해제 처리를 위한 깔끔한 데코레이터 기반 API를 제공하며, 다양한 런타임(Node.js, Bun, Deno, Cloudflare Workers)을 최고 수준으로 지원합니다.
+
+## 빠른 시작
+
+기본 Node.js 기반 websocket 런타임을 사용하려면 `WebSocketModule.forRoot()`를 사용합니다.
+
+```typescript
+import { WebSocketGateway, OnConnect, OnMessage, WebSocketModule } from '@fluojs/websockets';
+import { Module } from '@fluojs/core';
+
+@WebSocketGateway({ path: '/chat' })
+class ChatGateway {
+  @OnConnect()
+  handleConnect(socket) {
+    console.log('클라이언트 연결됨');
+  }
+
+  @OnMessage('ping')
+  handlePing(payload, socket) {
+    socket.send(JSON.stringify({ event: 'pong', data: payload }));
+  }
+}
+
+@Module({
+  imports: [WebSocketModule.forRoot()],
+  providers: [ChatGateway],
+})
+export class AppModule {}
+```
+
+## 주요 패턴
+
+### 경로 공유 게이트웨이
+여러 게이트웨이가 동일한 경로를 공유할 수 있으며, 이들의 핸들러는 탐색된 순서대로 실행됩니다.
+
+```typescript
+@WebSocketGateway({ path: '/events' })
+class MetricsGateway {
+  @OnMessage('metrics')
+  handleMetrics(data) { /* ... */ }
+}
+```
+
+### Server-Backed (Node.js 전용)
+Node 기반 어댑터(Express/Fastify)의 경우 전용 리스너 포트를 사용하도록 설정할 수 있습니다.
+
+```typescript
+@WebSocketGateway({ 
+  path: '/chat', 
+  serverBacked: { port: 3101 } 
+})
+class DedicatedChatGateway {}
+```
+
+### pre-upgrade guard와 기본 제한값
+`WebSocketModule.forRoot(...)`를 사용하면 핸드셰이크 전에 익명 업그레이드를 거절하고, 공통 연결/페이로드 제한을 조정할 수 있습니다.
+
+```typescript
+import { UnauthorizedException } from '@fluojs/http';
+
+WebSocketModule.forRoot({
+  limits: {
+    maxConnections: 500,
+    maxPayloadBytes: 65_536,
+  },
+  upgrade: {
+    guard(request) {
+      const authorization = request instanceof Request
+        ? request.headers.get('authorization')
+        : request.headers.authorization;
+
+      if (authorization !== 'Bearer demo-token') {
+        throw new UnauthorizedException('Authentication required.');
+      }
+    },
+  },
+});
+```
+
+옵션을 생략하면 `@fluojs/websockets`는 동시 연결 수와 인바운드 페이로드 크기에 대해 기본 제한값을 적용합니다. 또한 server-backed Node 리스너는 `heartbeat.enabled`를 명시적으로 `false`로 두지 않는 한 heartbeat 타이머를 활성화합니다.
+
+## 공개 API 개요
+
+- `@WebSocketGateway(options)`: 클래스를 WebSocket 게이트웨이로 표시합니다.
+- `@OnConnect()`: 연결 핸들러를 위한 데코레이터입니다.
+- `@OnMessage(event?)`: 인바운드 메시지 핸들러를 위한 데코레이터입니다.
+- `@OnDisconnect()`: 연결 해제 핸들러를 위한 데코레이터입니다.
+- `WebSocketModule`: WebSocket 통합을 위한 루트 모듈입니다.
+- `WebSocketModule.forRoot({ upgrade, limits, heartbeat, ... })`: pre-upgrade guard와 기본 제한값을 구성합니다.
+- `WebSocketGatewayLifecycleService`: 기본 Node.js 기반 lifecycle service token을 위한 루트 alias입니다.
+- `WebSocketModule.forRoot(...)`: 기본 루트 WebSocket 모듈의 패키지 수준 등록을 구성합니다.
+
+## 런타임별 서브패스
+
+기본 루트 Node.js alias 대신 런타임을 명시적으로 고정하고 싶다면 런타임별 서브패스를 사용하세요. 각 서브패스는 해당 `*WebSocketModule.forRoot(...)` 진입점과 일치하는 런타임 lifecycle service export를 제공합니다.
+
+| 런타임 | 서브패스 | 모듈 |
+| --- | --- | --- |
+| Node.js | `@fluojs/websockets/node` | `NodeWebSocketModule` |
+| Bun | `@fluojs/websockets/bun` | `BunWebSocketModule` |
+| Deno | `@fluojs/websockets/deno` | `DenoWebSocketModule` |
+| Workers | `@fluojs/websockets/cloudflare-workers` | `CloudflareWorkersWebSocketModule` |
+
+## 예제 소스
+
+- `packages/websockets/src/module.test.ts`
+- `packages/websockets/src/public-surface.test.ts`
+- `packages/websockets/src/node/node.test.ts`
+- `packages/websockets/src/bun/bun.test.ts`

package/README.md

@@ -0,0 +1,133 @@
+# @fluojs/websockets
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Decorator-based WebSocket gateway authoring 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)
+- [Runtime-Specific Subpaths](#runtime-specific-subpaths)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/websockets ws
+```
+
+## When to Use
+
+Use this package to add real-time WebSocket capabilities to your fluo application. It provides a clean, decorator-driven API for handling connections, messages, and disconnections, with first-class support for multiple runtimes (Node.js, Bun, Deno, Cloudflare Workers).
+
+## Quick Start
+
+Use `WebSocketModule.forRoot()` when you want the default Node.js-backed websocket runtime.
+
+```typescript
+import { WebSocketGateway, OnConnect, OnMessage, WebSocketModule } from '@fluojs/websockets';
+import { Module } from '@fluojs/core';
+
+@WebSocketGateway({ path: '/chat' })
+class ChatGateway {
+  @OnConnect()
+  handleConnect(socket) {
+    console.log('Client connected');
+  }
+
+  @OnMessage('ping')
+  handlePing(payload, socket) {
+    socket.send(JSON.stringify({ event: 'pong', data: payload }));
+  }
+}
+
+@Module({
+  imports: [WebSocketModule.forRoot()],
+  providers: [ChatGateway],
+})
+export class AppModule {}
+```
+
+## Common Patterns
+
+### Shared Path Gateways
+Multiple gateways can share the same path; their handlers will execute in discovery order.
+
+```typescript
+@WebSocketGateway({ path: '/events' })
+class MetricsGateway {
+  @OnMessage('metrics')
+  handleMetrics(data) { /* ... */ }
+}
+```
+
+### Server-Backed (Node.js Only)
+For Node-based adapters (Express/Fastify), you can opt into a dedicated listener port.
+
+```typescript
+@WebSocketGateway({ 
+  path: '/chat', 
+  serverBacked: { port: 3101 } 
+})
+class DedicatedChatGateway {}
+```
+
+### Pre-upgrade guards and bounded defaults
+Use `WebSocketModule.forRoot(...)` to reject anonymous upgrades before the handshake completes and to tune the shared connection/payload limits.
+
+```typescript
+import { UnauthorizedException } from '@fluojs/http';
+
+WebSocketModule.forRoot({
+  limits: {
+    maxConnections: 500,
+    maxPayloadBytes: 65_536,
+  },
+  upgrade: {
+    guard(request) {
+      const authorization = request instanceof Request
+        ? request.headers.get('authorization')
+        : request.headers.authorization;
+
+      if (authorization !== 'Bearer demo-token') {
+        throw new UnauthorizedException('Authentication required.');
+      }
+    },
+  },
+});
+```
+
+When omitted, `@fluojs/websockets` now applies bounded defaults for concurrent connections and inbound payload size. Server-backed Node listeners also enable heartbeat timers unless you explicitly set `heartbeat.enabled` to `false`.
+
+## Public API Overview
+
+- `@WebSocketGateway(options)`: Marks a class as a WebSocket gateway.
+- `@OnConnect()`: Decorator for connection handlers.
+- `@OnMessage(event?)`: Decorator for inbound message handlers.
+- `@OnDisconnect()`: Decorator for disconnection handlers.
+- `WebSocketModule`: Root module for WebSocket integration.
+- `WebSocketModule.forRoot({ upgrade, limits, heartbeat, ... })`: Configures pre-upgrade guards and bounded runtime defaults.
+- `WebSocketGatewayLifecycleService`: Root alias for the default Node.js-backed lifecycle service token.
+- `WebSocketModule.forRoot(...)`: Configures package-level registration for the default root websocket module.
+
+## Runtime-Specific Subpaths
+
+Use the runtime subpaths when you want an explicit runtime binding instead of the default root Node.js alias. Each subpath exposes its `*WebSocketModule.forRoot(...)` entrypoint plus the matching runtime lifecycle service export.
+
+| Runtime | Subpath | Module |
+| --- | --- | --- |
+| Node.js | `@fluojs/websockets/node` | `NodeWebSocketModule` |
+| Bun | `@fluojs/websockets/bun` | `BunWebSocketModule` |
+| Deno | `@fluojs/websockets/deno` | `DenoWebSocketModule` |
+| Workers | `@fluojs/websockets/cloudflare-workers` | `CloudflareWorkersWebSocketModule` |
+
+## Example Sources
+
+- `packages/websockets/src/module.test.ts`
+- `packages/websockets/src/public-surface.test.ts`
+- `packages/websockets/src/node/node.test.ts`
+- `packages/websockets/src/bun/bun.test.ts`

package/dist/bun/bun-module.d.ts

@@ -0,0 +1,15 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { WebSocketModuleOptions } from './bun-types.js';
+/**
+ * Explicit Bun websocket module entrypoint.
+ */
+export declare class BunWebSocketModule {
+    /**
+     * Registers the Bun websocket lifecycle service for request-upgrade gateway hosting.
+     *
+     * @param options Websocket gateway runtime options for guards, limits, heartbeat, and shutdown behavior.
+     * @returns A runtime module definition scoped to the Bun websocket adapter.
+     */
+    static forRoot(options?: WebSocketModuleOptions): ModuleType;
+}
+//# sourceMappingURL=bun-module.d.ts.map

package/dist/bun/bun-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun-module.d.ts","sourceRoot":"","sources":["../../src/bun/bun-module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAY7D;;GAEG;AACH,qBAAa,kBAAkB;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,sBAA2B,GAAG,UAAU;CAOjE"}

package/dist/bun/bun-module.js

@@ -0,0 +1,27 @@
+import { defineModule } from '@fluojs/runtime';
+import { WEBSOCKET_OPTIONS_INTERNAL } from '../options-token.internal.js';
+import { BunWebSocketGatewayLifecycleService } from './bun-service.js';
+function createBunWebSocketProviders(options = {}) {
+  return [{
+    provide: WEBSOCKET_OPTIONS_INTERNAL,
+    useValue: options
+  }, BunWebSocketGatewayLifecycleService];
+}
+
+/**
+ * Explicit Bun websocket module entrypoint.
+ */
+export class BunWebSocketModule {
+  /**
+   * Registers the Bun websocket lifecycle service for request-upgrade gateway hosting.
+   *
+   * @param options Websocket gateway runtime options for guards, limits, heartbeat, and shutdown behavior.
+   * @returns A runtime module definition scoped to the Bun websocket adapter.
+   */
+  static forRoot(options = {}) {
+    class BunWebSocketRuntimeModule extends BunWebSocketModule {}
+    return defineModule(BunWebSocketRuntimeModule, {
+      providers: createBunWebSocketProviders(options)
+    });
+  }
+}

package/dist/bun/bun-service.d.ts

@@ -0,0 +1,63 @@
+import type { Container } from '@fluojs/di';
+import type { ApplicationLogger, CompiledModule, OnApplicationBootstrap, OnApplicationShutdown, OnModuleDestroy } from '@fluojs/runtime';
+import type { HttpApplicationAdapter } from '@fluojs/http';
+import type { WebSocketRoomService } from '../types.js';
+import type { WebSocketModuleOptions } from './bun-types.js';
+/**
+ * Boots Bun-backed websocket gateways and manages their room lifecycle state.
+ */
+export declare class BunWebSocketGatewayLifecycleService implements OnApplicationBootstrap, OnApplicationShutdown, OnModuleDestroy, WebSocketRoomService {
+    private readonly runtimeContainer;
+    private readonly compiledModules;
+    private readonly logger;
+    private readonly adapter;
+    private readonly moduleOptions;
+    private pendingUpgradeReservations;
+    private readonly roomSockets;
+    private shutdownPromise;
+    private readonly socketRegistry;
+    private readonly socketRooms;
+    constructor(runtimeContainer: Container, compiledModules: readonly CompiledModule[], logger: ApplicationLogger, adapter: HttpApplicationAdapter, moduleOptions: WebSocketModuleOptions);
+    onApplicationBootstrap(): Promise<void>;
+    private assertNoServerBackedGatewayOptIn;
+    onApplicationShutdown(): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    private createBinding;
+    private groupDescriptorsByPath;
+    private handleUpgradeRequest;
+    private bindConnectionHandlers;
+    private createConnectionHandlerState;
+    private getBufferedMessageCount;
+    private getQueuedMessageCount;
+    private maybeCompactBufferedMessages;
+    private clearBufferedMessages;
+    private maybeCompactQueuedMessages;
+    private clearQueuedMessages;
+    private handleSocketMessage;
+    private handleSocketClose;
+    private bufferIncomingMessage;
+    private enqueueMessageDispatch;
+    private drainMessageQueue;
+    private enqueueDisconnectDispatch;
+    private resolveConnectionGateways;
+    private runConnectHandlers;
+    private finalizeConnectionBinding;
+    private replayBufferedConnectionEvents;
+    private resolveBackpressureLimit;
+    private resolveUpgradeRejection;
+    private closeOversizedPayload;
+    private resolveMaxConnectionCount;
+    private resolveReservedConnectionCount;
+    private tryReserveUpgradeSlot;
+    private releaseUpgradeReservation;
+    private resolveMaxPayloadBytes;
+    private resolveIdleTimeoutSeconds;
+    private shutdown;
+    private runShutdownLifecycle;
+    joinRoom(socketId: string, room: string): void;
+    leaveRoom(socketId: string, room: string): void;
+    broadcastToRoom(room: string, event: string, data: unknown): void;
+    getRooms(socketId: string): ReadonlySet<string>;
+    private unregisterSocket;
+}
+//# sourceMappingURL=bun-service.d.ts.map

package/dist/bun/bun-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bun-service.d.ts","sourceRoot":"","sources":["../../src/bun/bun-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AASzI,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAa3D,OAAO,KAAK,EAGV,oBAAoB,EACrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAyG7D;;GAEG;AACH,qBACa,mCACX,YAAW,sBAAsB,EAAE,qBAAqB,EAAE,eAAe,EAAE,oBAAoB;IAS7F,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAXhC,OAAO,CAAC,0BAA0B,CAAK;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;IAC9D,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwD;IACvF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkC;gBAG3C,gBAAgB,EAAE,SAAS,EAC3B,eAAe,EAAE,SAAS,cAAc,EAAE,EAC1C,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,sBAAsB,EAC/B,aAAa,EAAE,sBAAsB;IAGlD,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB7C,OAAO,CAAC,gCAAgC;IAclC,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAItC,OAAO,CAAC,aAAa;IAiCrB,OAAO,CAAC,sBAAsB;YAmBhB,oBAAoB;YAkDpB,sBAAsB;IAWpC,OAAO,CAAC,4BAA4B;IAqBpC,OAAO,CAAC,uBAAuB;IAI/B,OAAO,CAAC,qBAAqB;IAI7B,OAAO,CAAC,4BAA4B;IASpC,OAAO,CAAC,qBAAqB;IAK7B,OAAO,CAAC,0BAA0B;IASlC,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,mBAAmB;IAe3B,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,qBAAqB;IA0C7B,OAAO,CAAC,sBAAsB;YAwDhB,iBAAiB;IAmB/B,OAAO,CAAC,yBAAyB;YAsBnB,yBAAyB;YAczB,kBAAkB;YASlB,yBAAyB;IASvC,OAAO,CAAC,8BAA8B;IAoBtC,OAAO,CAAC,wBAAwB;YAUlB,uBAAuB;IAmDrC,OAAO,CAAC,qBAAqB;IAmB7B,OAAO,CAAC,yBAAyB;IAUjC,OAAO,CAAC,8BAA8B;IAItC,OAAO,CAAC,qBAAqB;IAS7B,OAAO,CAAC,yBAAyB;IAMjC,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,yBAAyB;YAcnB,QAAQ;YAUR,oBAAoB;IAYlC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAmB9C,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAc/C,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IA4BjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC;IAU/C,OAAO,CAAC,gBAAgB;CAgBzB"}