redweb 0.7.4 → 0.7.6

package/README.md

@@ -19,6 +19,7 @@ const {
   SocketRoute,         // Per-path WebSocket routing
   SocketService,       // Route-scoped background/tick logic
   SocketRegistry,      // Evented in-memory store
+  BaseHttpServer,      // Express app builder for advanced composition
   BaseHandler,         // WebSocket message handler base
   sendJson,            // Utility to stringify+send
   SOCKET_OPTIONS,      // Defaults for socket servers
@@ -36,6 +37,7 @@ Options:
 - `bind` (string): defaults to `0.0.0.0`.
 - `publicPaths` (string[]): folders served as static assets.
 - `services` (array): `{ serviceName, method, function }` for REST endpoints.
+- `listen` (boolean): defaults to `true`; set `false` to build `.app` without binding a port.
 - `listenCallback` (function): invoked after `.listen`.
 - `encoding` (`'json' | 'urlencoded'`): body parser selection.
 - `corsOptions`: passed to `cors`.
@@ -129,21 +131,105 @@ Each connected socket gets:
 
 Invalid JSON triggers an error response and closes the socket.
 
+### Binary WebSocket messages
+
+Text frames are still parsed as JSON and routed by `message.type`. Binary frames are dispatched separately, so handlers can receive raw `Buffer` payloads without triggering JSON parse errors.
+
+```js
+const { BaseHandler, SocketRoute } = require('redweb');
+
+class UploadHandler extends BaseHandler {
+  constructor() { super('upload'); }
+
+  onMessage(socket, message) {
+    socket.sendJson({ type: 'upload:control', action: message.action });
+  }
+
+  onBinaryMessage(socket, buffer) {
+    socket.sendJson({ type: 'upload:chunk', bytes: buffer.length });
+  }
+}
+
+class UploadRoute extends SocketRoute {
+  constructor() {
+    super({
+      path: '/upload',
+      handlers: [UploadHandler],
+      allowDuplicateConnections: true,
+      websocketOptions: {
+        maxPayload: 2 * 1024 * 1024
+      }
+    });
+  }
+}
+```
+
+`BaseHandler` provides `handleBinaryMessage(socket, buffer)` and `onBinaryMessage(socket, buffer)`. Override `onBinaryMessage` for normal use. If a handler does not override it, RedWeb sends:
+
+```json
+{ "error": "Binary messages are not supported by this handler" }
+```
+
+Routes may also select a binary-capable handler with `acceptsBinary(socket, buffer)`:
+
+```js
+class ImageHandler extends BaseHandler {
+  constructor() { super('image'); }
+
+  acceptsBinary(socket, buffer) {
+    return buffer.length > 0;
+  }
+
+  onMessage(socket, message) {}
+  onBinaryMessage(socket, buffer) {}
+}
+```
+
+### WebSocket route options
+
+`SocketRoute` accepts `websocketOptions`, which are passed to `new WebSocketServer(...)`. Use this for `ws` server settings such as `maxPayload` or `perMessageDeflate`.
+
+```js
+class ClipboardRoute extends SocketRoute {
+  constructor() {
+    super({
+      path: '/clipboard',
+      handlers: [ClipboardHandler],
+      websocketOptions: {
+        maxPayload: 1024 * 1024,
+        perMessageDeflate: false
+      }
+    });
+  }
+}
+```
+
 ### Sharing an HTTP/HTTPS server
 
-`SocketServer` and `SecureSocketServer` accept a prebuilt Node server via `server`. They attach upgrade handling and then call `.listen(port)`, so only pass a server that is **not** already listening.
+Use `listen: false` on `HttpServer` to build the Express app without binding a port. Then create one Node server from `httpServer.app` and pass it to `SocketServer`. When `SocketServer` receives a prebuilt `server`, it attaches upgrade handling but does not call `.listen()` unless you explicitly set `listen: true`.
 
 ```js
 const http = require('http');
-const express = require('express');
-const { SocketServer } = require('redweb');
+const { HttpServer, METHODS, SocketServer } = require('redweb');
 
-const app = express();
-const server = http.createServer(app);
+const httpServer = new HttpServer({
+  port: 3030,
+  listen: false,
+  publicPaths: ['./public'],
+  services: [
+    { serviceName: '/health', method: METHODS.GET, function: (req, res) => res.json({ ok: true }) },
+    { serviceName: '/session', method: METHODS.POST, function: createSession }
+  ]
+});
+
+const server = http.createServer(httpServer.app);
 
-app.get('/', (req, res) => res.send('hello'));
+new SocketServer({
+  server,
+  routes: [ClipboardRoute]
+});
 
-new SocketServer({ server, port: 4000, routes: [ChatRoute] });
+server.listen(3030, () => console.log('HTTP and WebSocket server listening on 3030'));
 ```
 
 ### Socket services
@@ -182,8 +268,9 @@ Helpers: `add`, `remove(itemOrId, byKey = 'id')`, `all()`, `count()`.
 
 ## Defaults and lifecycle
 
-- HTTP defaults: port `80`, bind `0.0.0.0`.
+- HTTP defaults: port `80`, bind `0.0.0.0`, `listen: true`.
 - WebSocket defaults: port `3000`, single connection per IP unless `allowDuplicateConnections` is set.
+- `SocketServer` owns and listens on its own server by default; if you pass `server`, you own calling `.listen()` unless you also pass `listen: true`.
 - If you do not supply `routes`, `SocketServer` registers a default route at `/` with `DefaultHandler` (it expects messages with `type: 'DefaultHandler'`).
 - `BaseSocketServer.shutdown()` closes all routes, services, and the underlying server.
 

package/index.d.ts

@@ -1,8 +1,9 @@
 declare module 'redweb' {
     import { Application } from 'express';
     import { CorsOptions } from 'cors';
-    import { Server as HttpServer } from 'http';
-    import { WebSocket } from 'ws';
+    import { Server as NodeHttpServer } from 'http';
+    import { WebSocket, ServerOptions } from 'ws';
+    import { Buffer } from 'buffer';
 
     /** ─────────────────── HTTP / CORE ─────────────────── */
 
@@ -11,9 +12,10 @@ declare module 'redweb' {
     export interface RedWebOptions {
         port?: number;
         bind?: string;
-        publicPaths?: string[];
-        services?: Array<{ serviceName: string; method: string; function: Function }>;
-        listenCallback?: () => void;
+        publicPaths?: string[];
+        services?: Array<{ serviceName: string; method: string; function: Function }>;
+        listen?: boolean;
+        listenCallback?: () => void;
         encoding?: RedWebEncoding;
         ssl?: { key: string; cert: string };
         server?: Application;
@@ -24,9 +26,10 @@ declare module 'redweb' {
     /** ─────────────────── SOCKET SERVER ─────────────────── */
 
     export interface SocketServerOptions {
-        server?: HttpServer;
-        port?: number;
-        routes?: Array<new () => SocketRoute>;
+        server?: NodeHttpServer;
+        port?: number;
+        listen?: boolean;
+        routes?: Array<new () => SocketRoute>;
         ssl?: { key: string; cert: string };
     }
 
@@ -34,9 +37,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,30 +74,35 @@ 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 ─────────────────── */
 
     export class BaseSocketServer {
         clients: Map<string, WebSocket>;
-        server: HttpServer;
+        server: NodeHttpServer;
         routes: SocketRoute[];
 
-        constructor(server: HttpServer, options?: SocketServerOptions);
+        constructor(server: NodeHttpServer, options?: SocketServerOptions);
 
         addRoute(route: new () => SocketRoute): void;
     }
@@ -146,13 +155,19 @@ declare module 'redweb' {
         constructor(options?: SocketServerOptions);
     }
 
-    export class HttpServer {
-        constructor(options?: RedWebOptions);
-    }
-
-    export class HttpsServer {
-        constructor(options?: RedWebOptions);
-    }
+    export class BaseHttpServer {
+        app: Application;
+        server?: NodeHttpServer;
+        constructor(options?: RedWebOptions);
+    }
+
+    export class HttpServer extends BaseHttpServer {
+        constructor(options?: RedWebOptions);
+    }
+
+    export class HttpsServer extends BaseHttpServer {
+        constructor(options?: RedWebOptions);
+    }
 
     /** ─────────────────── CONSTANTS ─────────────────── */
 

package/index.js

@@ -1,13 +1,14 @@
-const { METHODS } = require('./src/http');
+const { BaseHttpServer, METHODS } = require('./src/http');
 const { sendJson } = require('./src/ws/util');
 const { SocketServer, SecureSocketServer, SOCKET_OPTIONS, SocketRoute, SocketService, SocketRegistry } = require('./src/ws');
 const { BaseHandler } = require('./src/ws/BaseHandler');
 const HttpServer = require('./src/http/HttpServer');
 const HttpsServer = require('./src/http/HttpsServer');
 module.exports = {
-    HttpServer,
-    HttpsServer,
-    SocketServer,
+    HttpServer,
+    HttpsServer,
+    BaseHttpServer,
+    SocketServer,
     SecureSocketServer,
     BaseHandler,
     SocketRoute,

package/package.json

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

package/src/http/BaseHttpServer.js

@@ -15,13 +15,14 @@ const HtmxRenderer = require('../htmx/HtmxRenderer'); // Import the HtmxRenderer
  * @property {number} [port=80] - The port number to bind the server.
  * @property {string} [bind='0.0.0.0'] - The bind address for the server.
  * @property {string[]} [publicPaths=['./public']] - An array of paths to serve static files from.
- * @property {Array<{serviceName: string, method: string, function: Function}>} [services=[]] - An array of services with their endpoints and handlers.
- * @property {Function} [listenCallback] - Callback function to execute once the server starts listening.
+ * @property {Array<{serviceName: string, method: string, function: Function}>} [services=[]] - An array of services with their endpoints and handlers.
+ * @property {boolean} [listen=true] - Whether HttpServer/HttpsServer should automatically start listening.
+ * @property {Function} [listenCallback] - Callback function to execute once the server starts listening.
  * @property {RedWebEncoding} [encoding='json'] - The encoding type for the request bodies ('json' or 'urlencoded').
  * @property {Object} [ssl] - SSL configuration for HTTPS server.
  * @property {string} [ssl.key] - Path to the SSL key file.
  * @property {string} [ssl.cert] - Path to the SSL certificate file.
- * @property {import('express').Application} [server] - Whether to automatically start listening.
+ * @property {import('express').Application} [server] - Existing Express application to configure.
  * @property {import('cors').CorsOptions} [corsOptions] - The CORS Options.
  * @property {boolean} [enableHtmxRendering=false] - Enable dynamic HTMX file rendering.
  */
@@ -30,9 +31,10 @@ const ENCODINGS = { json: 'json', urlencoded: 'urlencoded' };
 const HTTP_OPTIONS = {
     port: 80,
     bind: '0.0.0.0',
-    publicPaths: ['./public'],
-    services: [],
-    listenCallback: undefined,
+    publicPaths: ['./public'],
+    services: [],
+    listen: true,
+    listenCallback: undefined,
     encoding: ENCODINGS.json,
     ssl: null,
     server: undefined,
@@ -45,10 +47,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/http/HttpServer.js

@@ -5,10 +5,14 @@ const { BaseHttpServer } = require('./BaseHttpServer');
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function HttpServer(options = {}) {
-    BaseHttpServer.call(this, options);
-    this.server = this.app.listen(this.port, this.listenCallback ? this.listenCallback : () => console.log(`RedWeb HttpServer listening on port ${this.port}`));
-    return this;
-}
+function HttpServer(options = {}) {
+    BaseHttpServer.call(this, options);
+    if (this.listen === false) {
+        return this;
+    }
+
+    this.server = this.app.listen(this.port, this.listenCallback ? this.listenCallback : () => console.log(`RedWeb HttpServer listening on port ${this.port}`));
+    return this;
+}
 
 module.exports = HttpServer;

package/src/http/HttpsServer.js

@@ -7,11 +7,16 @@ const loadSslConfig = require('../sslConfig');
  * @param {RedWebOptions} options - Configuration options for RedWeb.
  * @return {Object} Express application instance.
  */
-function HttpsServer(options = {}) {
-    BaseHttpServer.call(this, options);
-    const sslOptions = loadSslConfig(this.ssl);
-    https.createServer(sslOptions, this.app).listen(this.port, this.listenCallback ? this.listenCallback : () => console.log(`RedWeb HttpsServer listening on port ${this.port}`));
-    return this;
-}
+function HttpsServer(options = {}) {
+    BaseHttpServer.call(this, options);
+    const sslOptions = loadSslConfig(this.ssl);
+    this.server = https.createServer(sslOptions, this.app);
+    if (this.listen === false) {
+        return this;
+    }
+
+    this.server.listen(this.port, this.listenCallback ? this.listenCallback : () => console.log(`RedWeb HttpsServer listening on port ${this.port}`));
+    return this;
+}
 
 module.exports = HttpsServer;

package/src/http/index.js

@@ -1,2 +1,2 @@
-const { METHODS } = require('./BaseHttpServer');
-module.exports = { HttpServer: require('./HttpServer'), HttpsServer: require('./HttpsServer'), METHODS}
+const { BaseHttpServer, METHODS } = require('./BaseHttpServer');
+module.exports = { BaseHttpServer, HttpServer: require('./HttpServer'), HttpsServer: require('./HttpsServer'), METHODS}

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/BaseSocketServer.js

@@ -1,17 +1,19 @@
 /**
  * @typedef {Object} SocketServerOptions
- * @property {import('http').Server} [server]                    HTTP server to bind to
- * @property {number}              [port=3000]                  Port to listen on
- * @property {Array<new () => import('./SocketRoute').SocketRoute>} [routes]
- */
+ * @property {import('http').Server} [server]                    HTTP server to bind to
+ * @property {number}              [port=3000]                  Port to listen on
+ * @property {boolean}             [listen=true]                Whether owned servers should automatically start listening
+ * @property {Array<new () => import('./SocketRoute').SocketRoute>} [routes]
+ */
 
 const DefaultRoute = require('./DefaultRoute');
 
 const SOCKET_OPTIONS = {
-  port: 3000,
-  ssl:  null,
-  routes: []
-};
+  port: 3000,
+  ssl:  null,
+  listen: true,
+  routes: []
+};
 
 /**
  * Base WebSocket server

package/src/ws/SecureSocketServer.js

@@ -7,14 +7,17 @@ const { BaseSocketServer } = require('./BaseSocketServer');
  * @param {SocketServerOptions} options - Configuration options for SecureSocketServer.
  * @return {Object} WebSocket server instance.
  */
-class SecureSocketServer extends BaseSocketServer {
-    constructor(options = {}) {
-        const sslOptions = loadSslConfig(options.ssl);
-        const server = https.createServer(sslOptions);
-        super(server, options);
-        server.listen(this.port, () => console.log(`RedWeb SecureSocketServer listening on port ${this.port}`));
-        return this;
-    }
-}
+class SecureSocketServer extends BaseSocketServer {
+    constructor(options = {}) {
+        const ownsServer = !options?.server;
+        const sslOptions = ownsServer ? loadSslConfig(options.ssl) : null;
+        const server = options?.server || https.createServer(sslOptions);
+        super(server, options);
+        if ((ownsServer && this.listen !== false) || (!ownsServer && options.listen === true)) {
+            server.listen(this.port, () => console.log(`RedWeb SecureSocketServer listening on port ${this.port}`));
+        }
+        return this;
+    }
+}
 
 module.exports = SecureSocketServer;

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;

package/src/ws/SocketServer.js

@@ -6,13 +6,16 @@ const { BaseSocketServer } = require('./BaseSocketServer');
  * @param {SocketServerOptions} options - Configuration options for SocketServer.
  * @return {Object} WebSocket server instance.
  */
-class SocketServer extends BaseSocketServer {
-    constructor(options = {}) {
-        const server = options?.server || http.createServer();
-        super(server, options);
-        server.listen(this.port, () => console.log(`RedWeb SocketServer listening on port ${this.port}`));
-        return this;
-    }
-}
+class SocketServer extends BaseSocketServer {
+    constructor(options = {}) {
+        const ownsServer = !options?.server;
+        const server = options?.server || http.createServer();
+        super(server, options);
+        if ((ownsServer && this.listen !== false) || (!ownsServer && options.listen === true)) {
+            server.listen(this.port, () => console.log(`RedWeb SocketServer listening on port ${this.port}`));
+        }
+        return this;
+    }
+}
 
 module.exports = SocketServer;