@fluojs/websockets 1.0.0-beta.1

package/dist/node/node-types.d.ts

@@ -0,0 +1,81 @@
+import type { IncomingMessage } from 'node:http';
+import type { WebSocket } from 'ws';
+/**
+ * Strongly typed message handler signature for the Node websocket runtime.
+ */
+export type TypedOnMessageHandler<TEvents extends Record<string, unknown>, K extends keyof TEvents> = (payload: TEvents[K], socket: WebSocket, request: IncomingMessage) => void | Promise<void>;
+/**
+ * Request and socket context passed to Node websocket gateway handlers.
+ */
+export interface WebSocketGatewayContext {
+    request: IncomingMessage;
+    socket: WebSocket;
+}
+/**
+ * Structured rejection returned by a pre-upgrade websocket guard.
+ */
+export interface WebSocketUpgradeRejection {
+    /** Optional plaintext response body sent with the rejection. */
+    body?: string;
+    /** Optional HTTP headers added to the rejection response. */
+    headers?: Record<string, string>;
+    /** HTTP status code returned instead of completing the websocket upgrade. */
+    status: number;
+}
+/**
+ * Runtime context passed to pre-upgrade websocket guards.
+ */
+export interface WebSocketUpgradeContext {
+    /** Current number of open websocket connections tracked by the lifecycle service. */
+    activeConnectionCount: number;
+    /** Normalized gateway path targeted by the upgrade request. */
+    path: string;
+}
+/**
+ * Hook that can allow or reject a websocket upgrade before the adapter accepts it.
+ */
+export type WebSocketUpgradeGuard = (request: IncomingMessage | Request, context: WebSocketUpgradeContext) => Promise<boolean | WebSocketUpgradeRejection | void> | boolean | WebSocketUpgradeRejection | void;
+/**
+ * Runtime options shared by the Node websocket lifecycle service.
+ */
+export interface WebSocketModuleOptions {
+    /**
+     * Limits that bound connection count and inbound payload size across runtime adapters.
+     */
+    limits?: {
+        /**
+         * Maximum number of concurrently tracked websocket connections before new upgrades are rejected.
+         */
+        maxConnections?: number;
+        /**
+         * Maximum inbound payload size in bytes before the connection is rejected or closed.
+         */
+        maxPayloadBytes?: number;
+    };
+    /**
+     * Upgrade-time controls that run before the adapter completes the websocket handshake.
+     */
+    upgrade?: {
+        /**
+         * Optional guard hook that can deny anonymous or otherwise invalid upgrade requests.
+         */
+        guard?: WebSocketUpgradeGuard;
+    };
+    backpressure?: {
+        maxBufferedAmountBytes?: number;
+        policy?: 'close' | 'drop';
+    };
+    buffer?: {
+        maxPendingMessagesPerSocket?: number;
+        overflowPolicy?: 'close' | 'drop-newest' | 'drop-oldest';
+    };
+    heartbeat?: {
+        enabled?: boolean;
+        intervalMs?: number;
+        timeoutMs?: number;
+    };
+    shutdown?: {
+        timeoutMs?: number;
+    };
+}
+//# sourceMappingURL=node-types.d.ts.map

package/dist/node/node-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-types.d.ts","sourceRoot":"","sources":["../../src/node/node-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAEpC;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,OAAO,IAAI,CACpG,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,eAAe,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,qFAAqF;IACrF,qBAAqB,EAAE,MAAM,CAAC;IAE9B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,eAAe,GAAG,OAAO,EAClC,OAAO,EAAE,uBAAuB,KAE9B,OAAO,CAAC,OAAO,GAAG,yBAAyB,GAAG,IAAI,CAAC,GACnD,OAAO,GACP,yBAAyB,GACzB,IAAI,CAAC;AAET;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,CAAC,EAAE;QACP;;WAEG;QACH,cAAc,CAAC,EAAE,MAAM,CAAC;QAExB;;WAEG;QACH,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IAEF;;OAEG;IACH,OAAO,CAAC,EAAE;QACR;;WAEG;QACH,KAAK,CAAC,EAAE,qBAAqB,CAAC;KAC/B,CAAC;IAEF,YAAY,CAAC,EAAE;QACb,sBAAsB,CAAC,EAAE,MAAM,CAAC;QAChC,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;KAC3B,CAAC;IACF,MAAM,CAAC,EAAE;QACP,2BAA2B,CAAC,EAAE,MAAM,CAAC;QACrC,cAAc,CAAC,EAAE,OAAO,GAAG,aAAa,GAAG,aAAa,CAAC;KAC1D,CAAC;IACF,SAAS,CAAC,EAAE;QACV,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH"}

package/dist/node/node-types.js

@@ -0,0 +1 @@
+export {};

package/dist/node/node.d.ts

@@ -0,0 +1,4 @@
+export * from './node-module.js';
+export * from './node-service.js';
+export * from './node-types.js';
+//# sourceMappingURL=node.d.ts.map

package/dist/node/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node/node.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC"}

package/dist/node/node.js

@@ -0,0 +1,3 @@
+export * from './node-module.js';
+export * from './node-service.js';
+export * from './node-types.js';

package/dist/node.d.ts

@@ -0,0 +1,2 @@
+export * from './node/node.js';
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/node.js

@@ -0,0 +1 @@
+export * from './node/node.js';

package/dist/options-token.internal.d.ts

@@ -0,0 +1,7 @@
+import type { Token } from '@fluojs/core';
+import type { WebSocketModuleOptions } from './types.js';
+/**
+ * Internal injection token for the WebSocket module options.
+ */
+export declare const WEBSOCKET_OPTIONS_INTERNAL: Token<WebSocketModuleOptions>;
+//# sourceMappingURL=options-token.internal.d.ts.map

package/dist/options-token.internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options-token.internal.d.ts","sourceRoot":"","sources":["../src/options-token.internal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,KAAK,CAAC,sBAAsB,CAAwC,CAAC"}

package/dist/options-token.internal.js

@@ -0,0 +1,4 @@
+/**
+ * Internal injection token for the WebSocket module options.
+ */
+export const WEBSOCKET_OPTIONS_INTERNAL = Symbol.for('fluo.websocket.options');

package/dist/service.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Root export alias for the default Node.js-backed websocket lifecycle service.
+ *
+ * @remarks
+ * Import this alias from `@fluojs/websockets` when you need the shared lifecycle service token without reaching
+ * into runtime-specific subpaths.
+ */
+export { NodeWebSocketGatewayLifecycleService as WebSocketGatewayLifecycleService } from './node/node-service.js';
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,oCAAoC,IAAI,gCAAgC,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/service.js

@@ -0,0 +1,8 @@
+/**
+ * Root export alias for the default Node.js-backed websocket lifecycle service.
+ *
+ * @remarks
+ * Import this alias from `@fluojs/websockets` when you need the shared lifecycle service token without reaching
+ * into runtime-specific subpaths.
+ */
+export { NodeWebSocketGatewayLifecycleService as WebSocketGatewayLifecycleService } from './node/node-service.js';

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+import type { MetadataPropertyKey, Token } from '@fluojs/core';
+import type { TypedOnMessageHandler as NodeTypedOnMessageHandler, WebSocketGatewayContext as NodeWebSocketGatewayContext, WebSocketModuleOptions as NodeWebSocketModuleOptions, WebSocketUpgradeContext as NodeWebSocketUpgradeContext, WebSocketUpgradeGuard as NodeWebSocketUpgradeGuard, WebSocketUpgradeRejection as NodeWebSocketUpgradeRejection } from './node/node-types.js';
+/**
+ * Event-name-to-payload map used to type `@OnMessage(...)` handlers.
+ */
+export type WebSocketEventMap = Record<string, unknown>;
+/**
+ * Strongly typed message handler signature resolved from one {@link WebSocketEventMap} entry.
+ */
+export type TypedOnMessageHandler<TEvents extends WebSocketEventMap, K extends keyof TEvents> = NodeTypedOnMessageHandler<TEvents, K>;
+/**
+ * Dedicated listener configuration for runtimes that can host a standalone WebSocket server.
+ */
+export interface WebSocketGatewayServerBackedOptions {
+    /** TCP port used by the dedicated listener. */
+    port: number;
+}
+/**
+ * Options accepted by {@link WebSocketGateway}.
+ */
+export interface WebSocketGatewayOptions {
+    /** Request path used to match upgrade traffic for this gateway. */
+    path?: string;
+    /** Optional dedicated listener settings for server-backed Node.js adapters. */
+    serverBacked?: WebSocketGatewayServerBackedOptions;
+}
+/**
+ * Normalized gateway metadata stored on one decorated gateway class.
+ */
+export interface WebSocketGatewayMetadata {
+    /** Normalized path captured from the decorator options. */
+    path: string;
+    /** Dedicated listener settings when the gateway opts into server-backed hosting. */
+    serverBacked?: WebSocketGatewayServerBackedOptions;
+}
+/**
+ * Lifecycle categories available to WebSocket gateway handlers.
+ */
+export type WebSocketGatewayHandlerType = 'connect' | 'disconnect' | 'message';
+/**
+ * Metadata stored for one decorated gateway method.
+ */
+export interface WebSocketGatewayHandlerMetadata {
+    /** Optional inbound event name associated with a message handler. */
+    event?: string;
+    /** Handler lifecycle category recorded for the decorated method. */
+    type: WebSocketGatewayHandlerType;
+}
+/**
+ * Normalized descriptor for one discovered gateway handler.
+ */
+export interface WebSocketGatewayHandlerDescriptor {
+    /** Optional inbound event name associated with this handler. */
+    event?: string;
+    /** Metadata property key used to resolve the method on the gateway instance. */
+    methodKey: MetadataPropertyKey;
+    /** Human-readable method name used in diagnostics and discovery output. */
+    methodName: string;
+    /** Handler lifecycle category. */
+    type: WebSocketGatewayHandlerType;
+}
+/**
+ * Runtime descriptor for one discovered gateway class.
+ */
+export interface WebSocketGatewayDescriptor {
+    /** Ordered handler descriptors discovered on the gateway. */
+    handlers: WebSocketGatewayHandlerDescriptor[];
+    /** Module name that contributed this gateway. */
+    moduleName: string;
+    /** Normalized upgrade path handled by the gateway. */
+    path: string;
+    /** Dedicated listener settings when the gateway opts into server-backed hosting. */
+    serverBacked?: WebSocketGatewayServerBackedOptions;
+    /** Class name used in diagnostics and error messages. */
+    targetName: string;
+    /** DI token used to resolve the gateway instance. */
+    token: Token;
+}
+/**
+ * Runtime context passed to gateway handlers on the default Node.js adapter surface.
+ */
+export type WebSocketGatewayContext = NodeWebSocketGatewayContext;
+/**
+ * Upgrade-time context shared with pre-upgrade websocket guards.
+ */
+export type WebSocketUpgradeContext = NodeWebSocketUpgradeContext;
+/**
+ * Structured rejection returned by a pre-upgrade websocket guard.
+ */
+export type WebSocketUpgradeRejection = NodeWebSocketUpgradeRejection;
+/**
+ * Hook that can allow or reject a websocket upgrade before the adapter accepts it.
+ */
+export type WebSocketUpgradeGuard = NodeWebSocketUpgradeGuard;
+/**
+ * Room management API shared by WebSocket protocol adapters.
+ */
+export interface WebSocketRoomService {
+    /**
+     * Adds one socket to a room.
+     *
+     * @param socketId Socket identifier to add.
+     * @param room Room identifier to join.
+     */
+    joinRoom(socketId: string, room: string): void;
+    /**
+     * Removes one socket from a room.
+     *
+     * @param socketId Socket identifier to remove.
+     * @param room Room identifier to leave.
+     */
+    leaveRoom(socketId: string, room: string): void;
+    /**
+     * Emits one event to every socket currently in a room.
+     *
+     * @param room Room identifier that should receive the event.
+     * @param event Event name delivered to room members.
+     * @param data Payload delivered with the event.
+     */
+    broadcastToRoom(room: string, event: string, data: unknown): void;
+    /**
+     * Returns the rooms currently joined by one socket.
+     *
+     * @param socketId Socket identifier to inspect.
+     * @returns The current room set tracked for that socket.
+     */
+    getRooms(socketId: string): ReadonlySet<string>;
+}
+/**
+ * Runtime-agnostic module options that currently mirror the Node.js adapter options.
+ */
+export type WebSocketModuleOptions = NodeWebSocketModuleOptions;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,KAAK,EACV,qBAAqB,IAAI,yBAAyB,EAClD,uBAAuB,IAAI,2BAA2B,EACtD,sBAAsB,IAAI,0BAA0B,EACpD,uBAAuB,IAAI,2BAA2B,EACtD,qBAAqB,IAAI,yBAAyB,EAClD,yBAAyB,IAAI,6BAA6B,EAC3D,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,OAAO,SAAS,iBAAiB,EAAE,CAAC,SAAS,MAAM,OAAO,IAC1F,yBAAyB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,mCAAmC;IAClD,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,+EAA+E;IAC/E,YAAY,CAAC,EAAE,mCAAmC,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IAEb,oFAAoF;IACpF,YAAY,CAAC,EAAE,mCAAmC,CAAC;CACpD;AAED;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,oEAAoE;IACpE,IAAI,EAAE,2BAA2B,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,iCAAiC;IAChD,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,gFAAgF;IAChF,SAAS,EAAE,mBAAmB,CAAC;IAE/B,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IAEnB,kCAAkC;IAClC,IAAI,EAAE,2BAA2B,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,6DAA6D;IAC7D,QAAQ,EAAE,iCAAiC,EAAE,CAAC;IAE9C,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IAEnB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IAEb,oFAAoF;IACpF,YAAY,CAAC,EAAE,mCAAmC,CAAC;IAEnD,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IAEnB,qDAAqD;IACrD,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,6BAA6B,CAAC;AAEtE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/C;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhD;;;;;;OAMG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAElE;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,0BAA0B,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@fluojs/websockets",
+  "description": "Decorator-based WebSocket gateway authoring core for Fluo, with explicit Node, Bun, Deno, and Cloudflare Workers raw websocket bindings on dedicated subpaths.",
+  "keywords": [
+    "fluo",
+    "websocket",
+    "ws",
+    "gateway",
+    "realtime",
+    "upgrade"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/websockets"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./bun": {
+      "types": "./dist/bun.d.ts",
+      "import": "./dist/bun.js"
+    },
+    "./deno": {
+      "types": "./dist/deno.d.ts",
+      "import": "./dist/deno.js"
+    },
+    "./cloudflare-workers": {
+      "types": "./dist/cloudflare-workers.d.ts",
+      "import": "./dist/cloudflare-workers.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "bun": [
+        "./dist/bun.d.ts"
+      ],
+      "deno": [
+        "./dist/deno.d.ts"
+      ],
+      "cloudflare-workers": [
+        "./dist/cloudflare-workers.d.ts"
+      ],
+      "node": [
+        "./dist/node.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ws": "^8.18.3",
+    "@fluojs/core": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/http": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "vitest": "^3.2.4",
+    "@fluojs/platform-fastify": "^1.0.0-beta.1",
+    "@fluojs/platform-express": "^1.0.0-beta.1",
+    "@fluojs/platform-bun": "^1.0.0-beta.1"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}