redweb 0.7.4 → 0.7.5

package/index.d.ts

@@ -2,7 +2,8 @@ declare module 'redweb' {
     import { Application } from 'express';
     import { CorsOptions } from 'cors';
     import { Server as HttpServer } from 'http';
-    import { WebSocket } from 'ws';
+    import { WebSocket, ServerOptions } from 'ws';
+    import { Buffer } from 'buffer';
 
     /** ─────────────────── HTTP / CORE ─────────────────── */
 
@@ -34,9 +35,10 @@ declare module 'redweb' {
 
     export interface SocketRouteConfig {
         path: string;
-        handlers: Array<new () => BaseHandler>;
-        services?: Array<new () => SocketService>;
-        allowDuplicateConnections?: boolean;
+        handlers: Array<new () => BaseHandler>;
+        services?: Array<new () => SocketService>;
+        allowDuplicateConnections?: boolean;
+        websocketOptions?: ServerOptions;
     }
 
     /** Socket‑side autonomous service (game loops, timers, etc.) */
@@ -70,21 +72,26 @@ declare module 'redweb' {
             message: any
         ): void;
 
-        onMessage(socket: WebSocket, message: any): void;
-        onInitialContact(socket: WebSocket): void;
-    }
+        onMessage(socket: WebSocket, message: any): void;
+        acceptsBinary?(socket: WebSocket, buffer: Buffer): boolean;
+        handleBinaryMessage(socket: WebSocket, buffer: Buffer): void;
+        onBinaryMessage(socket: WebSocket, buffer: Buffer): void;
+        onInitialContact(socket: WebSocket): void;
+    }
 
     export class SocketRoute {
         path: string;
-        handlers: BaseHandler[];
-        clients: Map<string, WebSocket>;
-        allowDuplicateConnections?: boolean;
-
-        constructor(config: SocketRouteConfig);
-
-        addHandler(handler: new () => BaseHandler): void;
-        handleMessage(sock: WebSocket, data: any): void;
-    }
+        handlers: BaseHandler[];
+        clients: Map<string, WebSocket>;
+        allowDuplicateConnections?: boolean;
+        websocketOptions?: ServerOptions;
+
+        constructor(config: SocketRouteConfig);
+
+        addHandler(handler: new () => BaseHandler): void;
+        handleMessage(sock: WebSocket, data: any): void;
+        handleBinaryMessage(socket: WebSocket, buffer: Buffer): void;
+    }
 
     /** ─────────────────── SERVER BASE ─────────────────── */
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redweb",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "A way to quickly set up an express server",
   "main": "index.js",
   "scripts": {

package/src/http/BaseHttpServer.js

@@ -45,10 +45,10 @@ const HTTP_OPTIONS = {
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function BaseHttpServer(options = {}) {
-    this.options = { ...HTTP_OPTIONS, ...options };
-    this.app = express() || this.options.server;
-    Object.assign(this, this.options);
+function BaseHttpServer(options = {}) {
+    this.options = { ...HTTP_OPTIONS, ...options };
+    this.app = this.options.server || express();
+    Object.assign(this, this.options);
 
     // Middleware to parse request bodies based on the specified encoding
     if (this.encoding === ENCODINGS.json) {

package/src/ws/BaseHandler.js

@@ -18,21 +18,39 @@ class BaseHandler {
      * @param {WebSocket & {sendJson: (message: Object) => void, broadcast: (message: Object) => void}} socket - The WebSocket connection that sent the message.
      * @param {any} message - The incoming message in parsed JSON.
      */
-    handleMessage(socket, message) {
-        this.onMessage(socket, message);
-    }
-
-    /**
-     * Method to be overriden to process messages.
-     * @param {WebSocket} socket - The WebSocket connection that sent the message.
-     * @param {any} message - The incoming message in parsed JSON.
+    handleMessage(socket, message) {
+        this.onMessage(socket, message);
+    }
+
+    /**
+     * Handles an incoming binary message.
+     * @param {WebSocket & {sendJson: (message: Object) => void}} socket - The WebSocket connection that sent the message.
+     * @param {Buffer} buffer - The incoming binary message.
+     */
+    handleBinaryMessage(socket, buffer) {
+        this.onBinaryMessage(socket, buffer);
+    }
+
+    /**
+     * Method to be overriden to process messages.
+     * @param {WebSocket} socket - The WebSocket connection that sent the message.
+     * @param {any} message - The incoming message in parsed JSON.
      */
-    onMessage(socket, message) {
-        throw "Not yet implemented!";
-    }
-
-    onInitialContact(socket) {
-
+    onMessage(socket, message) {
+        throw "Not yet implemented!";
+    }
+
+    /**
+     * Method to be overriden to process binary messages.
+     * @param {WebSocket & {sendJson: (message: Object) => void}} socket - The WebSocket connection that sent the message.
+     * @param {Buffer} buffer - The incoming binary message.
+     */
+    onBinaryMessage(socket, buffer) {
+        socket.sendJson({ error: 'Binary messages are not supported by this handler' });
+    }
+
+    onInitialContact(socket) {
+
     }
 }
 

package/src/ws/SocketRoute.js

@@ -11,11 +11,12 @@ class SocketRoute {
      * Creates a new instance of `SocketRoute`.
      * @param {Object} options - Configuration options for the WebSocket route.
      * @param {string} options.path - The path of the WebSocket route (e.g., `/chat`, `/lobby`).
-     * @param {boolean} options.allowDuplicateConnections - Whether to allow multiple connections from the same client IP address.
-     * @param {import('./BaseHandler').BaseHandler[]} options.handlers - An array of handler instances that manage connections and messages for this route.
-     * @param {Array<new () => SocketService>} [options.services] 
-    */
-    constructor({ path, handlers, services = [], allowDuplicateConnections } = {}) {
+     * @param {boolean} options.allowDuplicateConnections - Whether to allow multiple connections from the same client IP address.
+     * @param {import('./BaseHandler').BaseHandler[]} options.handlers - An array of handler instances that manage connections and messages for this route.
+     * @param {Array<new () => SocketService>} [options.services] 
+     * @param {import('ws').ServerOptions} [options.websocketOptions] - Options passed to the underlying WebSocketServer.
+    */
+    constructor({ path, handlers, services = [], allowDuplicateConnections, websocketOptions = {} } = {}) {
         if (!path) {
             throw new Error('A `path` must be specified for the SocketRoute.');
         }
@@ -27,17 +28,18 @@ class SocketRoute {
          * This determines the endpoint that clients must connect to (e.g., `ws://localhost:3000/chat`).
          * @type {string}
          */
-        this.path = path;
+        this.path = path;
+        this.websocketOptions = websocketOptions;
         /**
          * The array of handler instances associated with this route.
          * Each handler is responsible for managing WebSocket connections and message handling logic.
          * @type {import('./BaseHandler').BaseHandler[]}
          */
-        this.handlers = handlers.map(HandlerClass => new HandlerClass());
-        this.clients = new Map();
-        this.server = new WebSocketServer({ noServer: true, path });
-        this.server.on('connection', this.handleConnection.bind(this));
-        this.allowDuplicateConnections = allowDuplicateConnections;
+        this.handlers = handlers.map(HandlerClass => new HandlerClass());
+        this.clients = new Map();
+        this.server = new WebSocketServer({ noServer: true, path, ...websocketOptions });
+        this.server.on('connection', this.handleConnection.bind(this));
+        this.allowDuplicateConnections = allowDuplicateConnections;
 
         /* ─── ROUTE‑SCOPED SERVICES ─────────────────────────── */
         this.services = services.map(SvcClass => {
@@ -64,41 +66,51 @@ class SocketRoute {
      * @param {WebSocket} socket - The WebSocket connection instance.
      * @param {import('http').IncomingMessage} req - The HTTP request object associated with the connection.
      */
-    handleConnection(socket, req) {
-        const ip = req.socket.remoteAddress;
-        console.log(`New client connected: ${ip}`);
-        if (this.allowDuplicateConnections) {
-            this.clients.set(randomUUID(), socket);
-        } else {
-            if (this.clients.get(ip) !== undefined) {
-                const oldClient = this.clients.get(ip);
-                console.warn(`Client ${ip} already connected, disconnecting existing connection.`);
-                oldClient.send(
-                    JSON.stringify({ msg: 'You are being disconnected because a new client is connected with your IP address.' })
-                );
-                oldClient.close();
-            }
-            this.clients.set(ip, socket);
-        }
-        socket.isAssigned = false; // Tracks whether the socket has been assigned a handler.
-        socket.sendJson = (data) => sendJson(socket, data);
-        socket.broadcast = (data) => broadcast([...this.clients.values()].filter(sock => sock !== socket), data);
-
-        this.connectionOpenCallback(socket);
-        socket.on('close', this.handleClose.bind(this));
-        socket.on('error', this.handleError.bind(this));
-        socket.on('message', (message) => {
-            try {
-                const parsed = JSON.parse(message);
-                this.handleMessage(socket, parsed);
-            } catch (error) {
-                console.error(`Error parsing message from ${ip}:`, error);
-                socket.sendJson({ error: 'Invalid JSON format' });
-                socket.close();
-                return;
-            }
-        });
-    }
+    handleConnection(socket, req) {
+        const ip = req?.socket?.remoteAddress || 'unknown';
+        const clientKey = this.allowDuplicateConnections ? randomUUID() : ip;
+
+        console.log(`New client connected: ${ip}`);
+
+        if (!this.allowDuplicateConnections) {
+            const existing = this.clients.get(clientKey);
+            if (existing) {
+                console.warn(`Client ${ip} already connected, disconnecting existing connection.`);
+                existing.send(
+                    JSON.stringify({ msg: 'You are being disconnected because a new client is connected with your IP address.' })
+                );
+                existing.close();
+            }
+        }
+
+        this.clients.set(clientKey, socket);
+        socket.clientKey = clientKey;
+        socket.__redwebClientKey = clientKey;
+        socket.remoteAddress = socket.remoteAddress || ip;
+        socket.isAssigned = false; // Tracks whether the socket has been assigned a handler.
+        socket.sendJson = (data) => sendJson(socket, data);
+        socket.broadcast = (data) => broadcast([...this.clients.values()].filter(sock => sock !== socket), data);
+
+        this.connectionOpenCallback(socket);
+        socket.on('close', () => this.handleClose(socket));
+        socket.on('error', (error) => this.handleError(socket, error));
+        socket.on('message', (message, isBinary) => {
+            if (isBinary) {
+                this.handleBinaryMessage(socket, message);
+                return;
+            }
+
+            try {
+                const parsed = JSON.parse(message);
+                this.handleMessage(socket, parsed);
+            } catch (error) {
+                console.error(`Error parsing message from ${ip}:`, error);
+                socket.sendJson({ error: 'Invalid JSON format' });
+                socket.close();
+                return;
+            }
+        });
+    }
 
     connectionOpenCallback(socket) {
         console.log(`Opening new connection: ${socket.remoteAddress}`);
@@ -117,19 +129,43 @@ class SocketRoute {
                 sendJson(sock, { error: `${error.message}` });
                 sock.close();
             }
-        }
-    }
+        }
+    }
+
+    handleBinaryMessage(socket, buffer) {
+        const hasBinaryPredicate = this.handlers.some(handler => typeof handler.acceptsBinary === 'function');
+        const handler = hasBinaryPredicate
+            ? this.handlers.find(handler => handler.acceptsBinary?.(socket, buffer))
+            : this.handlers.find(handler => typeof handler.handleBinaryMessage === 'function');
+
+        if (handler) {
+            try {
+                handler.handleBinaryMessage(socket, buffer);
+            } catch (error) {
+                console.error(`Error handling binary message in handler ${handler.name}:`, error);
+                sendJson(socket, { error: `${error.message}` });
+                socket.close();
+            }
+            return;
+        }
+
+        sendJson(socket, {
+            error: 'Binary messages are not supported on this route'
+        });
+    }
 
     /**
      * Handles socket disconnection.
      * @param {WebSocket} socket - The WebSocket connection instance.
      * @param {string} ip - The client's IP address.
      */
-    handleClose(socket, ip) {
-        console.log(`Client disconnected: ${ip}`);
-        this.clients.delete(ip);
-        if (this.connectionCloseCallback) this.connectionCloseCallback(socket);
-    }
+    handleClose(socket) {
+        const key = socket.clientKey || socket.__redwebClientKey;
+        const ip = socket.remoteAddress || 'unknown';
+        console.log(`Client disconnected: ${ip}`);
+        if (key && this.clients.get(key) === socket) this.clients.delete(key);
+        if (this.connectionCloseCallback) this.connectionCloseCallback(socket);
+    }
 
     shutdown() {
         this.services.forEach(svc => svc.onShutdown && svc.onShutdown());
@@ -142,9 +178,10 @@ class SocketRoute {
      * @param {Error} error - The error object.
      * @param {string} ip - The client's IP address.
      */
-    handleError(socket, error, ip) {
-        console.error(`Socket error from ${ip}:`, error);
-    }
-}
+    handleError(socket, error) {
+        const ip = socket.remoteAddress || 'unknown';
+        console.error(`Socket error from ${ip}:`, error);
+    }
+}
 
-module.exports = SocketRoute;
+module.exports = SocketRoute;