@iskra-bun/socket-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @iskra-bun/socket-kit
 
+## 0.2.0
+
+### Minor Changes
+
+- f9654df: New socket features:
+
+    - Rooms: `join(room)`/`leave(room)` on the socket context and `broadcastTo(room, event, payload)` on the driver (native Bun pub/sub topics). The existing global `broadcast()` is unchanged.
+    - A `socket:disconnected` event is emitted on close, as a counterpart to `socket:connected`.
+    - Each connection gets a stable unique `connectionId` (assigned at upgrade, stored on the typed socket data) included in the connected/disconnected payloads, so per-client tracking no longer relies on the non-unique remote address.
+
+### Patch Changes
+
+- f9654df: The running server is now typed with Bun's `Server` instead of `any`, and `SocketContext`/`SocketHandler` accept optional payload/connection-data generics so handlers can read a typed `socket.data`. Defaults preserve existing usage.
+- Add authorization and payload hardening to the socket driver:
+
+    - `canJoin` and `canPublish` hooks now gate room joins and publishes, so unauthorized clients can no longer subscribe to or broadcast on topics they are not permitted to use.
+    - `ctx.broadcast` wraps outgoing data in a consistent `{ event, payload }` envelope.
+    - `websocket.maxPayloadLength` is wired through (default 16 KiB) alongside a per-connection rate limit and an `allowedEvents` fallback gate, mitigating oversized-message and message-flood denial-of-service.
+
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+    - @iskra-bun/core@0.1.1
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,32 +1,91 @@
 import { Context, Driver, App, IskraError } from '@iskra-bun/core';
 import { ServerWebSocket } from 'bun';
 
-interface SocketContext<T = any> extends Context<T> {
-    socket: ServerWebSocket<any>;
-    broadcast(event: string, payload: any): void;
+/**
+ * Minimum data shape that every socket connection carries on ws.data.
+ * Drivers may extend this with app-specific fields via the TData generic.
+ */
+interface SocketData {
+    connectionId: string;
 }
-type SocketHandler = (ctx: SocketContext) => Promise<void> | void;
+interface SocketContext<TPayload = unknown, TData extends SocketData = SocketData> extends Context<TPayload> {
+    socket: ServerWebSocket<TData>;
+    /** Send a message back to this socket only. */
+    reply(data: unknown): void;
+    /**
+     * Publish to all sockets subscribed to topic (e.g. 'global'). The frame is
+     * wrapped in the driver envelope: {event: topic, payload: data}. Subject to
+     * the driver's canPublish authorization hook.
+     */
+    broadcast(topic: string, data: unknown): void;
+    /** Subscribe this socket to a named room. */
+    join(room: string): void;
+    /** Unsubscribe this socket from a named room. */
+    leave(room: string): void;
+}
+type SocketHandler<TPayload = unknown, TData extends SocketData = SocketData> = (ctx: SocketContext<TPayload, TData>) => Promise<void> | void;
 declare class SocketRouter {
     private handlers;
-    on(event: string, handler: SocketHandler): this;
+    /**
+     * Register a handler for an event. The generic lets callers pass a handler
+     * with a narrower payload type without an `as SocketHandler` cast; the
+     * handler is stored widened internally.
+     */
+    on<TPayload = unknown, TData extends SocketData = SocketData>(event: string, handler: SocketHandler<TPayload, TData>): this;
     getHandler(event: string): SocketHandler | undefined;
 }
 
+/** Authorization hook gating which rooms a connection may join. */
+type CanJoin = (connection: ServerWebSocket<SocketData>, room: string) => boolean;
+/** Authorization hook gating which topics a connection may publish to. */
+type CanPublish = (connection: ServerWebSocket<SocketData>, topic: string) => boolean;
+interface SocketDriverOptions {
+    port?: number;
+    router?: SocketRouter;
+    /** Max inbound frame size in bytes. Defaults to 16 KiB. */
+    maxPayloadLength?: number;
+    /** Gate ctx.join; deny by returning false. Defaults to allow-all. */
+    canJoin?: CanJoin;
+    /** Gate ctx.broadcast; deny by returning false. Defaults to allow-all. */
+    canPublish?: CanPublish;
+    /** Allowed fallback event names; when set, others are dropped. */
+    allowedEvents?: readonly string[];
+    /** Max inbound messages per connection per window. Defaults to 100. */
+    rateLimit?: number;
+    /** Rate-limit window in ms. Defaults to 1000. */
+    rateWindowMs?: number;
+}
 declare class SocketDriver implements Driver {
     name: string;
     private app;
     private router;
     private port;
     private runningServer;
-    constructor(options?: {
-        port?: number;
-        router?: SocketRouter;
-    });
+    readonly maxPayloadLength: number;
+    private readonly canJoin;
+    private readonly canPublish;
+    private readonly allowedEvents;
+    private readonly rateLimit;
+    private readonly rateWindowMs;
+    private rateStates;
+    constructor(options?: SocketDriverOptions);
     init(app: App): void;
     start(): void;
-    broadcast(event: string, payload: any): void;
+    /** Publish to all sockets subscribed to the global topic. */
+    broadcast(event: string, payload: unknown): void;
+    /** Publish to all sockets subscribed to a specific room. */
+    broadcastTo(room: string, event: string, payload: unknown): void;
     stop(): void;
+    /**
+     * Returns true if the connection is within its rate budget, recording the
+     * message. Bookkeeping is immutable: a fresh RateState replaces the old one.
+     */
+    private allowMessage;
     private handleMessage;
+    /** Subscribe to a room only when the authz hook permits it. */
+    private joinAuthorized;
+    /** Publish to a topic only when the authz hook permits it, using the envelope. */
+    private publishAuthorized;
 }
 
 declare class SocketConnectionError extends IskraError {
@@ -42,4 +101,4 @@ declare class SocketMessageError extends IskraError {
     });
 }
 
-export { SocketConnectionError, type SocketContext, SocketDriver, SocketMessageError, SocketRouter };
+export { type CanJoin, type CanPublish, SocketConnectionError, type SocketContext, type SocketData, SocketDriver, type SocketDriverOptions, type SocketHandler, SocketMessageError, SocketRouter };

package/dist/index.js

@@ -1,6 +1,11 @@
 // src/router.ts
 var SocketRouter = class {
   handlers = /* @__PURE__ */ new Map();
+  /**
+   * Register a handler for an event. The generic lets callers pass a handler
+   * with a narrower payload type without an `as SocketHandler` cast; the
+   * handler is stored widened internally.
+   */
   on(event, handler) {
     this.handlers.set(event, handler);
     return this;
@@ -26,15 +31,31 @@ var SocketMessageError = class extends IskraError {
 };
 
 // src/driver.ts
+var DEFAULT_MAX_PAYLOAD_LENGTH = 16 * 1024;
+var DEFAULT_RATE_LIMIT = 100;
+var DEFAULT_RATE_WINDOW_MS = 1e3;
 var SocketDriver = class {
   name = "SocketDriver";
   app = null;
   router;
   port;
-  runningServer;
+  runningServer = null;
+  maxPayloadLength;
+  canJoin;
+  canPublish;
+  allowedEvents;
+  rateLimit;
+  rateWindowMs;
+  rateStates = /* @__PURE__ */ new Map();
   constructor(options = {}) {
     this.port = options.port || 3001;
     this.router = options.router || new SocketRouter();
+    this.maxPayloadLength = options.maxPayloadLength ?? DEFAULT_MAX_PAYLOAD_LENGTH;
+    this.canJoin = options.canJoin ?? (() => true);
+    this.canPublish = options.canPublish ?? (() => true);
+    this.allowedEvents = options.allowedEvents ? new Set(options.allowedEvents) : null;
+    this.rateLimit = options.rateLimit ?? DEFAULT_RATE_LIMIT;
+    this.rateWindowMs = options.rateWindowMs ?? DEFAULT_RATE_WINDOW_MS;
   }
   init(app) {
     this.app = app;
@@ -44,40 +65,68 @@ var SocketDriver = class {
     this.runningServer = Bun.serve({
       port: this.port,
       fetch(req, server) {
-        if (server.upgrade(req)) {
+        const connectionId = crypto.randomUUID();
+        if (server.upgrade(req, { data: { connectionId } })) {
           return;
         }
         return new Response("Upgrade failed", { status: 500 });
       },
       websocket: {
+        maxPayloadLength: this.maxPayloadLength,
         open: (ws) => {
           this.app?.logger.debug("Socket connected");
           ws.subscribe("global");
-          this.app?.emit("socket:connected", { id: ws.remoteAddress });
+          this.app?.emit("socket:connected", {
+            connectionId: ws.data.connectionId
+          });
         },
         message: async (ws, message) => {
           await this.handleMessage(ws, message);
         },
         close: (ws) => {
           ws.unsubscribe("global");
+          this.rateStates.delete(ws.data.connectionId);
           this.app?.logger.debug("Socket disconnected");
+          this.app?.emit("socket:disconnected", {
+            connectionId: ws.data.connectionId
+          });
         }
       }
     });
   }
+  /** Publish to all sockets subscribed to the global topic. */
   broadcast(event, payload) {
-    if (this.runningServer) {
-      this.runningServer.publish("global", JSON.stringify({ event, payload }));
-    }
+    this.runningServer?.publish("global", JSON.stringify({ event, payload }));
+  }
+  /** Publish to all sockets subscribed to a specific room. */
+  broadcastTo(room, event, payload) {
+    this.runningServer?.publish(room, JSON.stringify({ event, payload }));
   }
   stop() {
-    if (this.runningServer) {
-      this.runningServer.stop();
-    }
+    this.runningServer?.stop();
     this.app?.logger.info("SocketDriver stopped");
   }
+  /**
+   * Returns true if the connection is within its rate budget, recording the
+   * message. Bookkeeping is immutable: a fresh RateState replaces the old one.
+   */
+  allowMessage(ws) {
+    const now = Date.now();
+    const key = ws.data.connectionId;
+    const prev = this.rateStates.get(key);
+    const next = !prev || now - prev.windowStart >= this.rateWindowMs ? { count: 1, windowStart: now } : { count: prev.count + 1, windowStart: prev.windowStart };
+    this.rateStates.set(key, next);
+    return next.count <= this.rateLimit;
+  }
   async handleMessage(ws, message) {
     try {
+      if (!this.allowMessage(ws)) {
+        this.app?.logger.warn(
+          { connectionId: ws.data.connectionId },
+          "Socket message rate limit exceeded; dropping frame"
+        );
+        return;
+      }
       const text = typeof message === "string" ? message : new TextDecoder().decode(message);
       const eventData = JSON.parse(text);
       const { event, payload } = eventData;
@@ -90,10 +139,18 @@ var SocketDriver = class {
           payload: payload || {},
           socket: ws,
           reply: (data) => ws.send(JSON.stringify({ event: `${event}:reply`, payload: data })),
-          broadcast: (evt, data) => this.runningServer.publish(evt, JSON.stringify(data))
-          // Publish to topic/channel logic needed? Or just broadcast
+          broadcast: (topic, data) => this.publishAuthorized(ws, topic, data),
+          join: (room) => this.joinAuthorized(ws, room),
+          leave: (room) => ws.unsubscribe(room)
         });
       } else {
+        if (this.allowedEvents && !this.allowedEvents.has(event)) {
+          this.app?.logger.warn(
+            { event },
+            "Dropping fallback socket event not in the allowed set"
+          );
+          return;
+        }
         this.app?.emit(`socket:${event}`, { socket: ws, payload });
       }
     } catch (err) {
@@ -103,6 +160,28 @@ var SocketDriver = class {
       this.app?.logger.error({ err: socketErr }, socketErr.message);
     }
   }
+  /** Subscribe to a room only when the authz hook permits it. */
+  joinAuthorized(ws, room) {
+    if (!this.canJoin(ws, room)) {
+      this.app?.logger.warn(
+        { connectionId: ws.data.connectionId, room },
+        "Denied socket join to unauthorized room"
+      );
+      return;
+    }
+    ws.subscribe(room);
+  }
+  /** Publish to a topic only when the authz hook permits it, using the envelope. */
+  publishAuthorized(ws, topic, data) {
+    if (!this.canPublish(ws, topic)) {
+      this.app?.logger.warn(
+        { connectionId: ws.data.connectionId, topic },
+        "Denied socket broadcast to unauthorized topic"
+      );
+      return;
+    }
+    this.runningServer?.publish(topic, JSON.stringify({ event: topic, payload: data }));
+  }
 };
 export {
   SocketConnectionError,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/router.ts","../src/errors.ts","../src/driver.ts"],"sourcesContent":["import type { App, Context } from '@iskra-bun/core';\nimport type { ServerWebSocket } from 'bun';\n\nexport interface SocketContext<T = any> extends Context<T> {\n    socket: ServerWebSocket<any>;\n    broadcast(event: string, payload: any): void;\n}\n\nexport type SocketHandler = (ctx: SocketContext) => Promise<void> | void;\n\nexport class SocketRouter {\n    private handlers: Map<string, SocketHandler> = new Map();\n\n    on(event: string, handler: SocketHandler) {\n        this.handlers.set(event, handler);\n        return this;\n    }\n\n    getHandler(event: string): SocketHandler | undefined {\n        return this.handlers.get(event);\n    }\n}\n","import { IskraError, ErrorCodes } from '@iskra-bun/core';\n\n// ─── Socket Connection Error ─────────────────────────────────────────────────\n\nexport class SocketConnectionError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.SOCKET_CONNECTION_ERROR, ...options });\n        this.name = 'SocketConnectionError';\n    }\n}\n\n// ─── Socket Message Error ────────────────────────────────────────────────────\n\nexport class SocketMessageError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.SOCKET_MESSAGE_ERROR, ...options });\n        this.name = 'SocketMessageError';\n    }\n}\n","import type { App, Driver } from '@iskra-bun/core';\nimport { SocketRouter } from './router';\nimport type { ServerWebSocket } from 'bun';\nimport { SocketMessageError } from './errors';\n\nexport class SocketDriver implements Driver {\n    name = 'SocketDriver';\n    private app: App | null = null;\n    private router: SocketRouter;\n    private port: number;\n    private runningServer: any;\n\n    constructor(options: { port?: number; router?: SocketRouter } = {}) {\n        this.port = options.port || 3001;\n        this.router = options.router || new SocketRouter();\n    }\n\n    init(app: App) {\n        this.app = app;\n    }\n\n    start() {\n        this.app?.logger.info(`Starting SocketDriver on port ${this.port}...`);\n\n        this.runningServer = Bun.serve({\n            port: this.port,\n            fetch(req, server) {\n                // Upgrade logic\n                if (server.upgrade(req)) {\n                    return; // Bun handles the rest\n                }\n                return new Response(\"Upgrade failed\", { status: 500 });\n            },\n            websocket: {\n                open: (ws) => {\n                    this.app?.logger.debug('Socket connected');\n                    ws.subscribe('global');\n                    this.app?.emit('socket:connected', { id: ws.remoteAddress });\n                },\n                message: async (ws, message) => {\n                    await this.handleMessage(ws, message);\n                },\n                close: (ws) => {\n                    ws.unsubscribe('global');\n                    this.app?.logger.debug('Socket disconnected');\n                }\n            }\n        });\n    }\n\n    public broadcast(event: string, payload: any) {\n        if (this.runningServer) {\n            this.runningServer.publish('global', JSON.stringify({ event, payload }));\n        }\n    }\n\n    stop() {\n        if (this.runningServer) {\n            this.runningServer.stop();\n        }\n        this.app?.logger.info('SocketDriver stopped');\n    }\n\n    private async handleMessage(ws: ServerWebSocket<any>, message: string | Buffer) {\n        try {\n            const text = typeof message === 'string' ? message : new TextDecoder().decode(message);\n            const eventData = JSON.parse(text);\n            const { event, payload } = eventData;\n\n            if (!event) return;\n\n            // 1. Try Router\n            const handler = this.router.getHandler(event);\n            if (handler && this.app) {\n                await handler({\n                    app: this.app,\n                    logger: this.app.logger.child({ source: 'socket', event }),\n                    payload: payload || {},\n                    socket: ws,\n                    reply: (data) => ws.send(JSON.stringify({ event: `${event}:reply`, payload: data })),\n                    broadcast: (evt, data) => this.runningServer.publish(evt, JSON.stringify(data)) // Publish to topic/channel logic needed? Or just broadcast\n                });\n            } else {\n                // 2. Fallback to Global App Event\n                this.app?.emit(`socket:${event}`, { socket: ws, payload });\n            }\n\n        } catch (err) {\n            const socketErr = new SocketMessageError('Failed to handle socket message', {\n                cause: err instanceof Error ? err : new Error(String(err)),\n            });\n            this.app?.logger.error({ err: socketErr }, socketErr.message);\n        }\n    }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/router.ts","../src/errors.ts","../src/driver.ts"],"sourcesContent":["import type { App, Context } from '@iskra-bun/core';\nimport type { ServerWebSocket } from 'bun';\n\n/**\n * Minimum data shape that every socket connection carries on ws.data.\n * Drivers may extend this with app-specific fields via the TData generic.\n */\nexport interface SocketData {\n    connectionId: string;\n}\n\nexport interface SocketContext<TPayload = unknown, TData extends SocketData = SocketData> extends Context<TPayload> {\n    socket: ServerWebSocket<TData>;\n    /** Send a message back to this socket only. */\n    reply(data: unknown): void;\n    /**\n     * Publish to all sockets subscribed to topic (e.g. 'global'). The frame is\n     * wrapped in the driver envelope: {event: topic, payload: data}. Subject to\n     * the driver's canPublish authorization hook.\n     */\n    broadcast(topic: string, data: unknown): void;\n    /** Subscribe this socket to a named room. */\n    join(room: string): void;\n    /** Unsubscribe this socket from a named room. */\n    leave(room: string): void;\n}\n\nexport type SocketHandler<TPayload = unknown, TData extends SocketData = SocketData> = (\n    ctx: SocketContext<TPayload, TData>\n) => Promise<void> | void;\n\nexport class SocketRouter {\n    private handlers: Map<string, SocketHandler> = new Map();\n\n    /**\n     * Register a handler for an event. The generic lets callers pass a handler\n     * with a narrower payload type without an `as SocketHandler` cast; the\n     * handler is stored widened internally.\n     */\n    on<TPayload = unknown, TData extends SocketData = SocketData>(\n        event: string,\n        handler: SocketHandler<TPayload, TData>\n    ) {\n        this.handlers.set(event, handler as SocketHandler);\n        return this;\n    }\n\n    getHandler(event: string): SocketHandler | undefined {\n        return this.handlers.get(event);\n    }\n}\n","import { IskraError, ErrorCodes } from '@iskra-bun/core';\n\n// ─── Socket Connection Error ─────────────────────────────────────────────────\n\nexport class SocketConnectionError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.SOCKET_CONNECTION_ERROR, ...options });\n        this.name = 'SocketConnectionError';\n    }\n}\n\n// ─── Socket Message Error ────────────────────────────────────────────────────\n\nexport class SocketMessageError extends IskraError {\n    constructor(message: string, options?: { cause?: Error; context?: Record<string, unknown> }) {\n        super(message, { code: ErrorCodes.SOCKET_MESSAGE_ERROR, ...options });\n        this.name = 'SocketMessageError';\n    }\n}\n","import type { App, Driver } from '@iskra-bun/core';\nimport { SocketRouter } from './router';\nimport type { SocketData } from './router';\nimport type { Server, ServerWebSocket } from 'bun';\nimport { SocketMessageError } from './errors';\n\n/** Default cap on a single inbound frame (16 KiB) to bound JSON.parse cost. */\nconst DEFAULT_MAX_PAYLOAD_LENGTH = 16 * 1024;\n/** Default per-connection inbound message budget per rate window. */\nconst DEFAULT_RATE_LIMIT = 100;\n/** Default rate-limit window in milliseconds. */\nconst DEFAULT_RATE_WINDOW_MS = 1000;\n\n/** Authorization hook gating which rooms a connection may join. */\nexport type CanJoin = (connection: ServerWebSocket<SocketData>, room: string) => boolean;\n/** Authorization hook gating which topics a connection may publish to. */\nexport type CanPublish = (connection: ServerWebSocket<SocketData>, topic: string) => boolean;\n\nexport interface SocketDriverOptions {\n    port?: number;\n    router?: SocketRouter;\n    /** Max inbound frame size in bytes. Defaults to 16 KiB. */\n    maxPayloadLength?: number;\n    /** Gate ctx.join; deny by returning false. Defaults to allow-all. */\n    canJoin?: CanJoin;\n    /** Gate ctx.broadcast; deny by returning false. Defaults to allow-all. */\n    canPublish?: CanPublish;\n    /** Allowed fallback event names; when set, others are dropped. */\n    allowedEvents?: readonly string[];\n    /** Max inbound messages per connection per window. Defaults to 100. */\n    rateLimit?: number;\n    /** Rate-limit window in ms. Defaults to 1000. */\n    rateWindowMs?: number;\n}\n\n/** Per-connection rate-limit bookkeeping, replaced immutably on each update. */\ninterface RateState {\n    count: number;\n    windowStart: number;\n}\n\nexport class SocketDriver implements Driver {\n    name = 'SocketDriver';\n    private app: App | null = null;\n    private router: SocketRouter;\n    private port: number;\n    private runningServer: Server<SocketData> | null = null;\n\n    public readonly maxPayloadLength: number;\n    private readonly canJoin: CanJoin;\n    private readonly canPublish: CanPublish;\n    private readonly allowedEvents: ReadonlySet<string> | null;\n    private readonly rateLimit: number;\n    private readonly rateWindowMs: number;\n    private rateStates: Map<string, RateState> = new Map();\n\n    constructor(options: SocketDriverOptions = {}) {\n        this.port = options.port || 3001;\n        this.router = options.router || new SocketRouter();\n        this.maxPayloadLength = options.maxPayloadLength ?? DEFAULT_MAX_PAYLOAD_LENGTH;\n        this.canJoin = options.canJoin ?? (() => true);\n        this.canPublish = options.canPublish ?? (() => true);\n        this.allowedEvents = options.allowedEvents ? new Set(options.allowedEvents) : null;\n        this.rateLimit = options.rateLimit ?? DEFAULT_RATE_LIMIT;\n        this.rateWindowMs = options.rateWindowMs ?? DEFAULT_RATE_WINDOW_MS;\n    }\n\n    init(app: App) {\n        this.app = app;\n    }\n\n    start() {\n        this.app?.logger.info(`Starting SocketDriver on port ${this.port}...`);\n\n        this.runningServer = Bun.serve<SocketData>({\n            port: this.port,\n            fetch(req, server) {\n                // Assign a unique id per connection at upgrade time.\n                const connectionId = crypto.randomUUID();\n                if (server.upgrade(req, { data: { connectionId } })) {\n                    return; // Bun handles the rest\n                }\n                return new Response('Upgrade failed', { status: 500 });\n            },\n            websocket: {\n                maxPayloadLength: this.maxPayloadLength,\n                open: (ws) => {\n                    this.app?.logger.debug('Socket connected');\n                    ws.subscribe('global');\n                    this.app?.emit('socket:connected', {\n                        connectionId: ws.data.connectionId,\n                    });\n                },\n                message: async (ws, message) => {\n                    await this.handleMessage(ws, message);\n                },\n                close: (ws) => {\n                    ws.unsubscribe('global');\n                    this.rateStates.delete(ws.data.connectionId);\n                    this.app?.logger.debug('Socket disconnected');\n                    this.app?.emit('socket:disconnected', {\n                        connectionId: ws.data.connectionId,\n                    });\n                },\n            },\n        });\n    }\n\n    /** Publish to all sockets subscribed to the global topic. */\n    public broadcast(event: string, payload: unknown) {\n        this.runningServer?.publish('global', JSON.stringify({ event, payload }));\n    }\n\n    /** Publish to all sockets subscribed to a specific room. */\n    public broadcastTo(room: string, event: string, payload: unknown) {\n        this.runningServer?.publish(room, JSON.stringify({ event, payload }));\n    }\n\n    stop() {\n        this.runningServer?.stop();\n        this.app?.logger.info('SocketDriver stopped');\n    }\n\n    /**\n     * Returns true if the connection is within its rate budget, recording the\n     * message. Bookkeeping is immutable: a fresh RateState replaces the old one.\n     */\n    private allowMessage(ws: ServerWebSocket<SocketData>): boolean {\n        const now = Date.now();\n        const key = ws.data.connectionId;\n        const prev = this.rateStates.get(key);\n        const next: RateState =\n            !prev || now - prev.windowStart >= this.rateWindowMs\n                ? { count: 1, windowStart: now }\n                : { count: prev.count + 1, windowStart: prev.windowStart };\n        this.rateStates.set(key, next);\n        return next.count <= this.rateLimit;\n    }\n\n    private async handleMessage(ws: ServerWebSocket<SocketData>, message: string | Buffer) {\n        try {\n            if (!this.allowMessage(ws)) {\n                this.app?.logger.warn(\n                    { connectionId: ws.data.connectionId },\n                    'Socket message rate limit exceeded; dropping frame'\n                );\n                return;\n            }\n\n            const text = typeof message === 'string' ? message : new TextDecoder().decode(message);\n            const eventData = JSON.parse(text);\n            const { event, payload } = eventData;\n\n            if (!event) return;\n\n            const handler = this.router.getHandler(event);\n            if (handler && this.app) {\n                await handler({\n                    app: this.app,\n                    logger: this.app.logger.child({ source: 'socket', event }),\n                    payload: payload || {},\n                    socket: ws,\n                    reply: (data) => ws.send(JSON.stringify({ event: `${event}:reply`, payload: data })),\n                    broadcast: (topic, data) => this.publishAuthorized(ws, topic, data),\n                    join: (room) => this.joinAuthorized(ws, room),\n                    leave: (room) => ws.unsubscribe(room),\n                });\n            } else {\n                // Fallback to the global app event bus, but only for events that\n                // pass the allow-list (when configured). Unknown names are dropped.\n                if (this.allowedEvents && !this.allowedEvents.has(event)) {\n                    this.app?.logger.warn(\n                        { event },\n                        'Dropping fallback socket event not in the allowed set'\n                    );\n                    return;\n                }\n                this.app?.emit(`socket:${event}`, { socket: ws, payload });\n            }\n        } catch (err) {\n            const socketErr = new SocketMessageError('Failed to handle socket message', {\n                cause: err instanceof Error ? err : new Error(String(err)),\n            });\n            this.app?.logger.error({ err: socketErr }, socketErr.message);\n        }\n    }\n\n    /** Subscribe to a room only when the authz hook permits it. */\n    private joinAuthorized(ws: ServerWebSocket<SocketData>, room: string) {\n        if (!this.canJoin(ws, room)) {\n            this.app?.logger.warn(\n                { connectionId: ws.data.connectionId, room },\n                'Denied socket join to unauthorized room'\n            );\n            return;\n        }\n        ws.subscribe(room);\n    }\n\n    /** Publish to a topic only when the authz hook permits it, using the envelope. */\n    private publishAuthorized(ws: ServerWebSocket<SocketData>, topic: string, data: unknown) {\n        if (!this.canPublish(ws, topic)) {\n            this.app?.logger.warn(\n                { connectionId: ws.data.connectionId, topic },\n                'Denied socket broadcast to unauthorized topic'\n            );\n            return;\n        }\n        this.runningServer?.publish(topic, JSON.stringify({ event: topic, payload: data }));\n    }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@iskra-bun/socket-kit",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "WebSocket nativo de Bun para Iskra, con router y broadcast.",
     "keywords": [
         "iskra",
@@ -46,7 +46,7 @@
         "build": "tsup --config ../../tsup.config.ts"
     },
     "dependencies": {
-        "@iskra-bun/core": "0.1.0"
+        "@iskra-bun/core": "0.1.1"
     },
     "devDependencies": {
         "@types/bun": "^1.3.5",

package/src/driver.ts

@@ -1,18 +1,68 @@
 import type { App, Driver } from '@iskra-bun/core';
 import { SocketRouter } from './router';
-import type { ServerWebSocket } from 'bun';
+import type { SocketData } from './router';
+import type { Server, ServerWebSocket } from 'bun';
 import { SocketMessageError } from './errors';
 
+/** Default cap on a single inbound frame (16 KiB) to bound JSON.parse cost. */
+const DEFAULT_MAX_PAYLOAD_LENGTH = 16 * 1024;
+/** Default per-connection inbound message budget per rate window. */
+const DEFAULT_RATE_LIMIT = 100;
+/** Default rate-limit window in milliseconds. */
+const DEFAULT_RATE_WINDOW_MS = 1000;
+
+/** Authorization hook gating which rooms a connection may join. */
+export type CanJoin = (connection: ServerWebSocket<SocketData>, room: string) => boolean;
+/** Authorization hook gating which topics a connection may publish to. */
+export type CanPublish = (connection: ServerWebSocket<SocketData>, topic: string) => boolean;
+
+export interface SocketDriverOptions {
+    port?: number;
+    router?: SocketRouter;
+    /** Max inbound frame size in bytes. Defaults to 16 KiB. */
+    maxPayloadLength?: number;
+    /** Gate ctx.join; deny by returning false. Defaults to allow-all. */
+    canJoin?: CanJoin;
+    /** Gate ctx.broadcast; deny by returning false. Defaults to allow-all. */
+    canPublish?: CanPublish;
+    /** Allowed fallback event names; when set, others are dropped. */
+    allowedEvents?: readonly string[];
+    /** Max inbound messages per connection per window. Defaults to 100. */
+    rateLimit?: number;
+    /** Rate-limit window in ms. Defaults to 1000. */
+    rateWindowMs?: number;
+}
+
+/** Per-connection rate-limit bookkeeping, replaced immutably on each update. */
+interface RateState {
+    count: number;
+    windowStart: number;
+}
+
 export class SocketDriver implements Driver {
     name = 'SocketDriver';
     private app: App | null = null;
     private router: SocketRouter;
     private port: number;
-    private runningServer: any;
+    private runningServer: Server<SocketData> | null = null;
+
+    public readonly maxPayloadLength: number;
+    private readonly canJoin: CanJoin;
+    private readonly canPublish: CanPublish;
+    private readonly allowedEvents: ReadonlySet<string> | null;
+    private readonly rateLimit: number;
+    private readonly rateWindowMs: number;
+    private rateStates: Map<string, RateState> = new Map();
 
-    constructor(options: { port?: number; router?: SocketRouter } = {}) {
+    constructor(options: SocketDriverOptions = {}) {
         this.port = options.port || 3001;
         this.router = options.router || new SocketRouter();
+        this.maxPayloadLength = options.maxPayloadLength ?? DEFAULT_MAX_PAYLOAD_LENGTH;
+        this.canJoin = options.canJoin ?? (() => true);
+        this.canPublish = options.canPublish ?? (() => true);
+        this.allowedEvents = options.allowedEvents ? new Set(options.allowedEvents) : null;
+        this.rateLimit = options.rateLimit ?? DEFAULT_RATE_LIMIT;
+        this.rateWindowMs = options.rateWindowMs ?? DEFAULT_RATE_WINDOW_MS;
     }
 
     init(app: App) {
@@ -22,54 +72,87 @@ export class SocketDriver implements Driver {
     start() {
         this.app?.logger.info(`Starting SocketDriver on port ${this.port}...`);
 
-        this.runningServer = Bun.serve({
+        this.runningServer = Bun.serve<SocketData>({
             port: this.port,
             fetch(req, server) {
-                // Upgrade logic
-                if (server.upgrade(req)) {
+                // Assign a unique id per connection at upgrade time.
+                const connectionId = crypto.randomUUID();
+                if (server.upgrade(req, { data: { connectionId } })) {
                     return; // Bun handles the rest
                 }
-                return new Response("Upgrade failed", { status: 500 });
+                return new Response('Upgrade failed', { status: 500 });
             },
             websocket: {
+                maxPayloadLength: this.maxPayloadLength,
                 open: (ws) => {
                     this.app?.logger.debug('Socket connected');
                     ws.subscribe('global');
-                    this.app?.emit('socket:connected', { id: ws.remoteAddress });
+                    this.app?.emit('socket:connected', {
+                        connectionId: ws.data.connectionId,
+                    });
                 },
                 message: async (ws, message) => {
                     await this.handleMessage(ws, message);
                 },
                 close: (ws) => {
                     ws.unsubscribe('global');
+                    this.rateStates.delete(ws.data.connectionId);
                     this.app?.logger.debug('Socket disconnected');
-                }
-            }
+                    this.app?.emit('socket:disconnected', {
+                        connectionId: ws.data.connectionId,
+                    });
+                },
+            },
         });
     }
 
-    public broadcast(event: string, payload: any) {
-        if (this.runningServer) {
-            this.runningServer.publish('global', JSON.stringify({ event, payload }));
-        }
+    /** Publish to all sockets subscribed to the global topic. */
+    public broadcast(event: string, payload: unknown) {
+        this.runningServer?.publish('global', JSON.stringify({ event, payload }));
+    }
+
+    /** Publish to all sockets subscribed to a specific room. */
+    public broadcastTo(room: string, event: string, payload: unknown) {
+        this.runningServer?.publish(room, JSON.stringify({ event, payload }));
     }
 
     stop() {
-        if (this.runningServer) {
-            this.runningServer.stop();
-        }
+        this.runningServer?.stop();
         this.app?.logger.info('SocketDriver stopped');
     }
 
-    private async handleMessage(ws: ServerWebSocket<any>, message: string | Buffer) {
+    /**
+     * Returns true if the connection is within its rate budget, recording the
+     * message. Bookkeeping is immutable: a fresh RateState replaces the old one.
+     */
+    private allowMessage(ws: ServerWebSocket<SocketData>): boolean {
+        const now = Date.now();
+        const key = ws.data.connectionId;
+        const prev = this.rateStates.get(key);
+        const next: RateState =
+            !prev || now - prev.windowStart >= this.rateWindowMs
+                ? { count: 1, windowStart: now }
+                : { count: prev.count + 1, windowStart: prev.windowStart };
+        this.rateStates.set(key, next);
+        return next.count <= this.rateLimit;
+    }
+
+    private async handleMessage(ws: ServerWebSocket<SocketData>, message: string | Buffer) {
         try {
+            if (!this.allowMessage(ws)) {
+                this.app?.logger.warn(
+                    { connectionId: ws.data.connectionId },
+                    'Socket message rate limit exceeded; dropping frame'
+                );
+                return;
+            }
+
             const text = typeof message === 'string' ? message : new TextDecoder().decode(message);
             const eventData = JSON.parse(text);
             const { event, payload } = eventData;
 
             if (!event) return;
 
-            // 1. Try Router
             const handler = this.router.getHandler(event);
             if (handler && this.app) {
                 await handler({
@@ -78,13 +161,22 @@ export class SocketDriver implements Driver {
                     payload: payload || {},
                     socket: ws,
                     reply: (data) => ws.send(JSON.stringify({ event: `${event}:reply`, payload: data })),
-                    broadcast: (evt, data) => this.runningServer.publish(evt, JSON.stringify(data)) // Publish to topic/channel logic needed? Or just broadcast
+                    broadcast: (topic, data) => this.publishAuthorized(ws, topic, data),
+                    join: (room) => this.joinAuthorized(ws, room),
+                    leave: (room) => ws.unsubscribe(room),
                 });
             } else {
-                // 2. Fallback to Global App Event
+                // Fallback to the global app event bus, but only for events that
+                // pass the allow-list (when configured). Unknown names are dropped.
+                if (this.allowedEvents && !this.allowedEvents.has(event)) {
+                    this.app?.logger.warn(
+                        { event },
+                        'Dropping fallback socket event not in the allowed set'
+                    );
+                    return;
+                }
                 this.app?.emit(`socket:${event}`, { socket: ws, payload });
             }
-
         } catch (err) {
             const socketErr = new SocketMessageError('Failed to handle socket message', {
                 cause: err instanceof Error ? err : new Error(String(err)),
@@ -92,4 +184,28 @@ export class SocketDriver implements Driver {
             this.app?.logger.error({ err: socketErr }, socketErr.message);
         }
     }
+
+    /** Subscribe to a room only when the authz hook permits it. */
+    private joinAuthorized(ws: ServerWebSocket<SocketData>, room: string) {
+        if (!this.canJoin(ws, room)) {
+            this.app?.logger.warn(
+                { connectionId: ws.data.connectionId, room },
+                'Denied socket join to unauthorized room'
+            );
+            return;
+        }
+        ws.subscribe(room);
+    }
+
+    /** Publish to a topic only when the authz hook permits it, using the envelope. */
+    private publishAuthorized(ws: ServerWebSocket<SocketData>, topic: string, data: unknown) {
+        if (!this.canPublish(ws, topic)) {
+            this.app?.logger.warn(
+                { connectionId: ws.data.connectionId, topic },
+                'Denied socket broadcast to unauthorized topic'
+            );
+            return;
+        }
+        this.runningServer?.publish(topic, JSON.stringify({ event: topic, payload: data }));
+    }
 }

package/src/index.ts

@@ -1,3 +1,3 @@
-export { SocketDriver } from './driver';
-export { SocketRouter, type SocketContext } from './router';
+export { SocketDriver, type SocketDriverOptions, type CanJoin, type CanPublish } from './driver';
+export { SocketRouter, type SocketContext, type SocketHandler, type SocketData } from './router';
 export * from './errors';

package/src/router.ts

@@ -1,18 +1,47 @@
 import type { App, Context } from '@iskra-bun/core';
 import type { ServerWebSocket } from 'bun';
 
-export interface SocketContext<T = any> extends Context<T> {
-    socket: ServerWebSocket<any>;
-    broadcast(event: string, payload: any): void;
+/**
+ * Minimum data shape that every socket connection carries on ws.data.
+ * Drivers may extend this with app-specific fields via the TData generic.
+ */
+export interface SocketData {
+    connectionId: string;
 }
 
-export type SocketHandler = (ctx: SocketContext) => Promise<void> | void;
+export interface SocketContext<TPayload = unknown, TData extends SocketData = SocketData> extends Context<TPayload> {
+    socket: ServerWebSocket<TData>;
+    /** Send a message back to this socket only. */
+    reply(data: unknown): void;
+    /**
+     * Publish to all sockets subscribed to topic (e.g. 'global'). The frame is
+     * wrapped in the driver envelope: {event: topic, payload: data}. Subject to
+     * the driver's canPublish authorization hook.
+     */
+    broadcast(topic: string, data: unknown): void;
+    /** Subscribe this socket to a named room. */
+    join(room: string): void;
+    /** Unsubscribe this socket from a named room. */
+    leave(room: string): void;
+}
+
+export type SocketHandler<TPayload = unknown, TData extends SocketData = SocketData> = (
+    ctx: SocketContext<TPayload, TData>
+) => Promise<void> | void;
 
 export class SocketRouter {
     private handlers: Map<string, SocketHandler> = new Map();
 
-    on(event: string, handler: SocketHandler) {
-        this.handlers.set(event, handler);
+    /**
+     * Register a handler for an event. The generic lets callers pass a handler
+     * with a narrower payload type without an `as SocketHandler` cast; the
+     * handler is stored widened internally.
+     */
+    on<TPayload = unknown, TData extends SocketData = SocketData>(
+        event: string,
+        handler: SocketHandler<TPayload, TData>
+    ) {
+        this.handlers.set(event, handler as SocketHandler);
         return this;
     }