redweb 0.6.4 → 0.6.5

package/README.md

@@ -74,9 +74,9 @@ const options = {
 const app = new HttpsServer(options);
 ```
 
-### WebSocket Server with Handlers
+### WebSocket Server with Routes and Handlers
 
-RedWeb supports **handler-based routing** for WebSocket connections, allowing you to modularize and secure your WebSocket message handling logic.
+RedWeb uses **route-based architecture** for WebSocket connections, allowing you to modularize and secure your WebSocket message handling logic.
 
 #### Defining a Custom Handler
 
@@ -87,86 +87,85 @@ const { BaseHandler } = require('redweb');
 
 class ChatHandler extends BaseHandler {
     constructor() {
-        super({
-            name: 'ChatHandler',
-            handlers: {
-                chat: (socket, data) => {
-                    console.log(`Received chat message: ${data.message}`);
-                    socket.send(JSON.stringify({ type: 'chatResponse', message: 'Hello!' }));
-                }
-            }
-        });
+        super('chat');
+    }
+
+    onMessage(socket, message) {
+        console.log(`Received chat message: ${message.text}`);
+        socket.send(JSON.stringify({ type: 'chatResponse', message: 'Hello!' }));
     }
 }
 
 module.exports = ChatHandler;
 ```
 
-#### Setting Up a WebSocket Server with Handlers
+#### Defining a WebSocket Route
+
+Routes group handlers and specify the WebSocket path.
 
 ```javascript
-const { SocketServer } = require('redweb');
+const { SocketRoute } = require('redweb');
 const ChatHandler = require('./ChatHandler');
 
-const options = {
-    port: 3000,
-    handlerConfig: [ChatHandler],
-    connectionOpenCallback: (socket) => {
-        console.log('WebSocket client connected');
-    },
-    connectionCloseCallback: (socket) => {
-        console.log('WebSocket client disconnected');
+class ChatRoute extends SocketRoute {
+    constructor() {
+        super({
+            path: '/chat',
+            handlers: [ChatHandler]
+        });
     }
-};
+}
 
-const socketServer = new SocketServer(options);
+module.exports = ChatRoute;
 ```
 
-#### Adding Handlers Dynamically
+#### Setting Up a WebSocket Server with Routes
 
-Handlers can be added after the WebSocket server has started using the `addHandler` method.
+```javascript
+const { SocketServer } = require('redweb');
+const ChatRoute = require('./ChatRoute');
+
+new SocketServer({
+    port: 3000,
+    routes: [ChatRoute]
+});
+```
+
+### Adding Routes Dynamically
+
+Routes can be added to the WebSocket server after initialization.
 
 ```javascript
-class DynamicHandler {
-    constructor() {
-        this.name = 'DynamicHandler';
-        this.handlers = {
-            dynamicMessage: (socket, data) => {
-                console.log(`Received dynamic message: ${data.message}`);
-                socket.send(JSON.stringify({ type: 'dynamicResponse', message: 'Handled dynamically!' }));
-            }
-        };
-    }
+const { SocketServer, SocketRoute } = require('redweb');
+const ChatHandler = require('./ChatHandler');
 
-    newConnection(socket) {
-        console.log('DynamicHandler: New connection established');
+class ChatRoute extends SocketRoute {
+    constructor() {
+        super({
+            path: '/chat',
+            handlers: [ChatHandler]
+        });
     }
 }
 
-const { SocketServer } = require('redweb');
 const socketServer = new SocketServer({ port: 3000 });
 
-// Dynamically add a new handler
-socketServer.addHandler(DynamicHandler);
+// Dynamically add a new route
+const chatRoute = new ChatRoute();
+socketServer.routes.push(chatRoute);
 ```
 
-#### Client Communication with a Handler
+### Client Communication with a Route
 
-The client must identify the handler during the initial connection with a `__handlerConnect` message.
+The client connects to the WebSocket server using the specified route.
 
 ```javascript
 const WebSocket = require('ws');
 
-const ws = new WebSocket('ws://localhost:3000');
+const ws = new WebSocket('ws://localhost:3000/chat');
 
 ws.on('open', () => {
-    ws.send(JSON.stringify({
-        type: '__handlerConnect',
-        data: { handlerName: 'ChatHandler' }
-    }));
-
-    // Send a message to the handler
-    ws.send(JSON.stringify({ type: 'chat', message: 'Hi there!' }));
+    ws.send(JSON.stringify({ type: 'chat', text: 'Hello there!' }));
 });
 
 ws.on('message', (message) => {
@@ -176,42 +175,25 @@ ws.on('message', (message) => {
 
 ### Managing Connected Clients
 
-RedWeb's WebSocket server maintains a list of connected clients by their IP addresses. This list is automatically updated when clients connect or disconnect.
+RedWeb's WebSocket server maintains a list of connected clients by their IP addresses for each route. This list is automatically updated when clients connect or disconnect.
 
 ```javascript
-const { SocketServer } = require('redweb');
+const { SocketRoute } = require('redweb');
 
-const socketServer = new SocketServer({
-    port: 3000,
-    connectionOpenCallback: (socket) => {
-        console.log('WebSocket client connected');
-    },
-    connectionCloseCallback: (socket) => {
-        console.log('WebSocket client disconnected');
+class ChatRoute extends SocketRoute {
+    constructor() {
+        super({
+            path: '/chat',
+            handlers: []
+        });
     }
-});
 
-// Access the list of connected clients
-console.log(socketServer.clients); // Map of clients by their IP addresses
-```
-
-### Backward-Compatible Message Handlers
-
-If no handler is assigned during the initial connection, you can still use traditional `messageHandlers`.
-
-```javascript
-const { SocketServer } = require('redweb');
-
-const options = {
-    port: 3000,
-    messageHandlers: {
-        echo: (socket, data) => {
-            socket.send(JSON.stringify({ type: 'echoResponse', message: data.message }));
-        }
+    onConnection(socket) {
+        console.log('New client connected:', socket.remoteAddress);
     }
-};
+}
 
-const socketServer = new SocketServer(options);
+module.exports = ChatRoute;
 ```
 
 ## Options
@@ -226,14 +208,10 @@ const socketServer = new SocketServer(options);
 - **encoding**: Encoding type for request bodies (`'json'` or `'urlencoded'`).
 - **ssl**: SSL configuration for HTTPS server (`{ key: './path/to/key.pem', cert: './path/to/cert.pem' }`).
 
-### SocketServer and SecureSocketServer Options
+### SocketServer Options
 
 - **port**: Port number (default: `3000`).
-- **connectionOpenCallback**: Function to execute once a client connects.
-- **connectionCloseCallback**: Function to execute once a client disconnects.
-- **messageCallback**: Function to execute for every message received.
-- **messageHandlers**: Object containing message handlers based on message type.
-- **handlerConfig**: Array of handler classes to support handler-based routing.
+- **routes**: Array of `SocketRoute` classes to define WebSocket routes and handlers.
 - **ssl**: SSL configuration for SecureSocketServer (`{ key: './path/to/key.pem', cert: './path/to/cert.pem' }`).
 
 ## License

package/index.d.ts

@@ -59,61 +59,103 @@ declare module 'redweb' {
             key: string;
             cert: string;
         };
-        handlerConfig?: Array<new () => BaseHandler>;
+        routes?: Array<new () => SocketRoute>;
     }
 
     /**
-     * Base class for WebSocket handlers.
+     * WebSocket route configuration.
      */
-    export class BaseHandler {
+    export interface SocketRouteConfig {
+        path: string; // The WebSocket route path (e.g., "/chat").
+        handlers: Array<new () => BaseHandler>; // Array of handler classes for the route.
+    }
+
+    /**
+     * Represents a WebSocket route.
+     */
+    export class SocketRoute {
         /**
-         * The name of the handler (used to identify it in the server).
+         * The path for the WebSocket route.
          */
-        name: string;
+        path: string;
 
         /**
-         * Dictionary of message handlers for this handler.
+         * Handlers associated with the route.
          */
-        messageHandlers: {
-            [type: string]: (socket: WebSocket, data: any) => void;
-        };
+        handlers: BaseHandler[];
 
         /**
-         * List of active WebSocket connections managed by this handler.
+         * Creates a new `SocketRoute` instance.
+         * @param config - Configuration options for the route.
          */
-        connections: WebSocket[];
+        constructor(config: SocketRouteConfig);
 
         /**
-         * Creates a new handler instance.
-         * @param config - Configuration for the handler.
+         * Adds a new handler dynamically.
+         * @param HandlerClass - A class extending `BaseHandler`.
          */
-        constructor(config: HandlerConfig);
+        addHandler(HandlerClass: new () => BaseHandler): void;
 
         /**
-         * Adds a new WebSocket connection, processes initial data, and sets up message handling for this handler.
-         * @param socket - The WebSocket connection to add.
-         * @param data - Optional initial data sent during the connection handshake.
+         * Handles a new WebSocket connection.
+         * @param socket - The WebSocket connection instance.
+         * @param req - The HTTP request associated with the connection.
          */
-        newConnection(socket: WebSocket, data?: any): void;
+        handleConnection(socket: WebSocket, req: import('http').IncomingMessage): void;
 
         /**
-         * Method called when a WebSocket connection is closed. Can be overridden in subclasses.
-         * @param socket - The WebSocket connection being closed.
+         * Handles incoming WebSocket messages.
+         * @param socket - The WebSocket connection instance.
+         * @param data - The message data.
          */
-        onClose(socket: WebSocket): void;
+        handleMessage(socket: WebSocket, data: any): void;
+
+        /**
+         * Handles WebSocket disconnections.
+         * @param socket - The WebSocket connection instance.
+         */
+        handleClose(socket: WebSocket): void;
 
         /**
-         * Handles an incoming message and routes it to the appropriate handler function.
+         * Handles WebSocket errors.
+         * @param socket - The WebSocket connection instance.
+         * @param error - The error object.
+         */
+        handleError(socket: WebSocket, error: Error): void;
+    }
+
+    /**
+     * Base class for WebSocket handlers.
+     */
+    export class BaseHandler {
+        /**
+         * The name of the handler (used to identify it in the server).
+         */
+        name: string;
+        /**
+         * Creates a new handler instance.
+         * @param name - The name of the handler.
+         */
+        constructor(name: string);
+
+        /**
+         * Handles an incoming message.
          * @param socket - The WebSocket connection that sent the message.
-         * @param message - The incoming message in JSON string format.
+         * @param message - The message data.
          */
-        handleMessage(socket: WebSocket, message: string): void;
+        onMessage(socket: WebSocket, message: Object): void;
 
         /**
-         * Broadcasts a message to all connections managed by this handler.
-         * @param message - The message to broadcast.
+         * Called during the first contact with a new WebSocket connection.
+         * @param socket - The WebSocket connection instance.
          */
-        broadcast(message: object): void;
+        onInitialContact(socket: WebSocket): void;
+
+        /**
+         * Called when a WebSocket connection closes.
+         * @param socket - The WebSocket connection instance.
+         */
+        onClose(socket: WebSocket): void;
     }
 
     /**
@@ -121,22 +163,30 @@ declare module 'redweb' {
      */
     export class BaseSocketServer {
         /**
-         * Map of connected WebSocket clients by their IP address.
+         * List of WebSocket routes.
          */
-        clients: Map<string, WebSocket>;
+        routes: SocketRoute[];
 
         /**
-         * List of handler instances currently registered with the server.
+         * Creates a new `BaseSocketServer`.
+         * @param server - The HTTP server instance.
+         * @param options - Configuration options.
          */
-        handlers: BaseHandler[];
-
         constructor(server: HTTPServer | HTTPSServer, options?: SocketServerOptions);
 
         /**
-         * Adds a new handler to the WebSocket server.
-         * @param HandlerClass - A class extending `BaseHandler` to add to the server.
+         * Handles WebSocket upgrade requests.
+         * @param req - The incoming HTTP upgrade request.
+         * @param socket - The raw network socket.
+         * @param head - The initial data chunk.
          */
-        addHandler(HandlerClass: new () => BaseHandler): void;
+        handleUpgrade(req: import('http').IncomingMessage, socket: import('net').Socket, head: Buffer): void;
+
+        /**
+         * 
+         * @param route 
+         */
+        addRoute(route: new () => SocketRoute);
     }
 
     /**

package/index.js

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

package/package.json

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

package/src/ws/BaseHandler.js

@@ -4,94 +4,35 @@
 class BaseHandler {
     /**
      * Creates a new handler instance.
-     * @param {{ name: string, handlers: Record<string, (socket: WebSocket, data: object) => void> }} config
-     * - `name`: The unique name of the handler.
-     * - `handlers`: A dictionary of message types and their corresponding handler functions.
+     * @param {string} name - The name of the Handler, used in the client 'type' arg of request e.g {"type": "<handler-name>", ...}
      */
-    constructor(config) {
+    constructor(name) {
         /**
-         * The name of the handler (used to identify this handler in the server).
+         * he name of the Handler, used in the client 'type' arg of request e.g {"type": "<handler-name>", ...}.
          * @type {string}
          */
-        this.name = config.name;
-
-        /**
-         * The dictionary of message handlers for this handler.
-         * @type {Record<string, (socket: WebSocket, data: object) => void>}
-         */
-        this.messageHandlers = config.handlers || {};
-
-        /**
-         * The list of active WebSocket connections managed by this handler.
-         * @type {WebSocket[]}
-         */
-        this.connections = [];
-    }
-
-    handleSocketMessages(socket) {
-        socket.on('message', (message) => this.handleMessage(socket, message));
-    }
-
-    handleSocketClose(socket) {
-        socket.on('close', () => {
-            this.onClose(socket);
-            this.connections = this.connections.filter((conn) => conn !== socket);
-            console.log(`Connection closed for handler "${this.name}".`);
-        });
-    }
-
-    handleNewConnection(socket) {
-        this.connections.push(socket);
-        this.handleSocketMessages(socket);
-        this.handleSocketClose(socket);
-        socket.isAssigned = true;
-        console.log(`New connection added to handler "${this.name}".`);
+        this.name = name;
     }
-
     /**
-     * Adds a new WebSocket connection and sets up message handling for this handler.
-     * @param {WebSocket} socket - The WebSocket connection to add.
+     * Handles an incoming message and routes it to the appropriate handler function.
+     * @param {WebSocket & {sendJson: (message: Object) => void, broadcast: (message: Object) => void}} socket - The WebSocket connection that sent the message.
+     * @param {string} message - The incoming message in JSON string format.
      */
-    newConnection(socket, data) {
-        console.log(`Received newConnection data ${JSON.stringify(data)}`);
-        this.handleNewConnection(socket);
-    }
-
-    onClose(socket) {
-        console.log(`Closing socket ${socket.remoteAddress}`);
+    handleMessage(socket, message) {
+        this.onMessage(socket, message);
     }
 
     /**
-     * Handles an incoming message and routes it to the appropriate handler function.
+     * Method to be overriden to process messages.
      * @param {WebSocket} socket - The WebSocket connection that sent the message.
      * @param {string} message - The incoming message in JSON string format.
      */
-    handleMessage(socket, message) {
-        try {
-            const parsedMessage = JSON.parse(message);
-            const { type, ...data } = parsedMessage;
-
-            if (this.messageHandlers[type]) {
-                this.messageHandlers[type](socket, data);
-            } else {
-                console.warn(`Unhandled message type: "${type}" in handler "${this.name}".`);
-                socket.close();
-            }
-        } catch (error) {
-            console.error(`Error processing message in handler "${this.name}":`, error);
-        }
+    onMessage(socket, message) {
+        throw "Not yet implemented!";
     }
 
-    /**
-     * Broadcasts a message to all connections managed by this handler.
-     * @param {object} message - The message to broadcast.
-     */
-    broadcast(message) {
-        this.connections.forEach((socket) => {
-            if (socket.readyState === WebSocket.OPEN) {
-                socket.send(JSON.stringify(message));
-            }
-        });
+    onInitialContact(socket) {
+
     }
 }
 

package/src/ws/BaseSocketServer.js

@@ -1,26 +1,16 @@
-const WebSocket = require('ws');
-
 /**
  * @typedef {Object} SocketServerOptions
  * @property {import('http').Server} [server] - The HTTP server instance to bind the WebSocket server to.
  * @property {number} [port=3000] - The port number for the WebSocket server.
- * @property {(socket: WebSocket) => void} [connectionOpenCallback] - Callback executed when a client connects.
- * @property {(socket: WebSocket) => void} [connectionCloseCallback] - Callback executed when a client disconnects.
- * @property {(socket: WebSocket, message: object) => void} [messageCallback] - Callback executed when a message is received.
- * @property {Record<string, (socket: WebSocket, data: object) => void>} [messageHandlers] - A dictionary of message types and their corresponding handler functions.
- * @property {{ key: string, cert: string } | null} [ssl] - SSL configuration for a secure WebSocket server.
- * @property {Array<new () => BaseHandler>} [handlerConfig] - An array of handler classes to use for routing.
+ * @property {Array<new () => import('./SocketRoute').SocketRoute>} [routes] - An array of handler classes to use for routing.
  */
 
+const DefaultRoute = require('./DefaultRoute');
+
 const SOCKET_OPTIONS = {
     port: 3000,
-    connectionOpenCallback: undefined,
-    connectionCloseCallback: undefined,
-    messageCallback: undefined,
-    messageHandlers: {
-        ping: (socket, data) => socket.send(JSON.stringify({ type: 'pong' }))
-    },
-    ssl: null
+    ssl: null,
+    routes: []
 };
 
 /**
@@ -41,162 +31,26 @@ class BaseSocketServer {
      * @param {SocketServerOptions} options - The configuration options for the WebSocket server.
      */
     constructor(server, options = {}) {
-        this.wss = new WebSocket.Server({ server });
         this.clients = new Map(); // Map of clients by their IP addresses.
         Object.assign(this, { ...SOCKET_OPTIONS, ...options });
-
-        this.handlers = this.initHandlers(options.handlerConfig || []);
-        this.wss.on('connection', this.handleConnection.bind(this));
-    }
-
-    /**
-     * Initializes the handler classes.
-     * @param {Array<new () => BaseHandler>} handlerConfig - Array of handler classes.
-     * @returns {BaseHandler[]} - Array of handler instances.
-     */
-    initHandlers(handlerConfig) {
-        return handlerConfig.map(HandlerClass => new HandlerClass());
-    }
-
-    /**
-     * Adds a new handler to the WebSocket server.
-     * @param {new () => BaseHandler} HandlerClass - The handler class to add.
-     */
-    addHandler(HandlerClass) {
-        const newHandler = new HandlerClass();
-        if (this.handlers.find(handler => handler.name === newHandler.name)) {
-            console.warn(`Handler with name '${newHandler.name}' already exists.`);
-            return;
-        }
-        this.handlers.push(newHandler);
-        console.log(`Handler '${newHandler.name}' added successfully.`);
-    }
-
-    /**
-     * Handles a new WebSocket connection.
-     * @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.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.
-
-        if (this.connectionOpenCallback) this.connectionOpenCallback(socket);
-
-        socket.on('message', message => this.initialMessageHandler(socket, message, ip));
-        socket.on('close', () => this.handleClose(socket, ip));
-        socket.on('error', error => this.handleError(socket, error, ip));
-    }
-
-    /**
-     * Processes the initial message to determine if a handler assignment is required.
-     * @param {WebSocket} socket - The WebSocket connection instance.
-     * @param {string} message - The received message.
-     * @param {string} ip - The client's IP address.
-     */
-    initialMessageHandler(socket, message, ip) {
-        try {
-            const parsedMessage = JSON.parse(message);
-
-            // If the first message is '__handlerConnect', attempt to assign a handler
-            if (parsedMessage.type === '__handlerConnect') {
-                this.assignToHandler(socket, parsedMessage);
-                return;
-            }
-
-            // If no handler is assigned, use the default messageHandlers or fallback
-            if (!socket.isAssigned) {
-                this.handleMessage(socket, parsedMessage, ip);
-            } else {
-                throw new Error('Unexpected message after handler assignment');
-            }
-        } catch (error) {
-            console.error(`Error handling initial message from ${ip}:`, error);
-            socket.close(); // Optionally close the socket for invalid behavior.
-        }
-    }
-
-    /**
-     * Assigns the socket to a specific handler.
-     * @param {WebSocket} socket - The WebSocket connection instance.
-     * @param {{ handlerName: string, key?: string }} data - Data containing the handler name and optional authentication key.
-     */
-    assignToHandler(socket, connectMessage) {
-        if (!connectMessage.data) {
-            console.warn(`No data provided for handlerConnect message.`);
-            socket.close();
-            return;
-        }
-        const { handlerName, data } = connectMessage.data;
-        const handler = this.handlers.find(h => h.name === handlerName);
-        if (!handler) {
-            console.warn(`Handler not found: ${handlerName}`);
-            socket.send(JSON.stringify({ error: `Handler '${handlerName}' not found` }));
-            socket.close();
-            return;
-        }
-
-        // Optional: Perform authentication with `key`
-        socket.removeAllListeners('message');
-        handler.newConnection(socket, connectMessage.data);
-    }
-
-    /**
-     * Handles a message using the default messageHandlers.
-     * @param {WebSocket} socket - The WebSocket connection instance.
-     * @param {{ type: string, [key: string]: any }} parsedMessage - The parsed message object.
-     * @param {string} ip - The client's IP address.
-     */
-    handleMessage(socket, parsedMessage, ip) {
-        const { type, ...data } = parsedMessage;
-
-        if (this.messageCallback) this.messageCallback(socket, parsedMessage);
-
-        if (this.messageHandlers[type]) {
-            this.messageHandlers[type](socket, data);
-        } else {
-            console.warn(`Unhandled message type from ${ip}: ${type}`);
-            socket.close();
-        }
-    }
-
-    /**
-     * 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);
+        this.server = server;
+        if (!options.routes?.length) options.routes = [ DefaultRoute ];
+        this.routes = options.routes.map((route) => new route(server));
+        this.server.on('upgrade', this.handleUpgrade.bind(this));
     }
 
-    /**
-     * Handles socket errors.
-     * @param {WebSocket} socket - The WebSocket connection instance.
-     * @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);
+    handleUpgrade(req, sock, head) {
+        const route = this.routes.find(route => route.path == req.url);
+        if (!route) sock.destroy();
+        else route.server.handleUpgrade(req, sock, head, (s, r) => route.server.emit('connection', s, r));
     }
 
     /**
-     * Broadcasts a message to all connected clients.
-     * @param {object} message - The message to broadcast.
+     * 
+     * @param {new () => import('./SocketRoute')} route 
      */
-    broadcast(message) {
-        broadcast(this, message);
+    addRoute(route) {
+        this.routes.push(new route(this.server));
     }
 }
 

package/src/ws/DefaultHandler.js

@@ -0,0 +1,14 @@
+const { BaseHandler } = require("./BaseHandler");
+const { sendJson } = require("./util");
+
+class DefaultHandler extends BaseHandler {
+    constructor() {
+        super("DefaultHandler");
+    }
+
+    onMessage(socket, message) {
+        socket.send(sendJson(`I got your message of ${JSON.stringify(message)}`));
+    }
+}
+
+module.exports = DefaultHandler;

package/src/ws/DefaultRoute.js

@@ -0,0 +1,14 @@
+const SocketRoute  = require("./SocketRoute");
+const DefaultHandler = require('./DefaultHandler');
+
+class DefaultRoute extends SocketRoute {
+    constructor(server) {
+        super({
+            server,
+            path: "/",
+            handlers: [DefaultHandler]
+        })
+    }
+}
+
+module.exports = DefaultRoute;

package/src/ws/SocketRoute.js

@@ -0,0 +1,114 @@
+const { WebSocketServer } = require("ws");
+const { sendJson, broadcast } = require("./util");
+
+/**
+ * Represents a WebSocket route configuration.
+ * This class is used to define a specific WebSocket endpoint (`path`) and its associated handlers.
+ */
+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 {import('./BaseHandler').BaseHandler[]} options.handlers - An array of handler instances that manage connections and messages for this route.
+     */
+    constructor({path, handlers } = {}) {
+        if (!path) {
+            throw new Error('A `path` must be specified for the SocketRoute.');
+        }
+        if (!handlers || !Array.isArray(handlers) || handlers.length === 0) {
+            throw new Error('At least one handler must be specified for the SocketRoute.');
+        }
+        /**
+         * The path of the WebSocket route.
+         * This determines the endpoint that clients must connect to (e.g., `ws://localhost:3000/chat`).
+         * @type {string}
+         */
+        this.path = path;
+        /**
+         * 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));
+    }
+    /**
+     * Adds a new handler to the WebSocket server.
+     * @param {new () => BaseHandler} HandlerClass - The handler class to add.
+     */
+    addHandler(HandlerClass) {
+        const newHandler = new HandlerClass();
+        if (this.handlers.find(handler => handler.name === newHandler.name)) {
+            console.warn(`Handler with name '${newHandler.name}' already exists.`);
+            return;
+        }
+        this.handlers.push(newHandler);
+        console.log(`Handler '${newHandler.name}' added successfully.`);
+    }
+    /**
+     * Handles a new WebSocket connection.
+     * @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.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()], data);
+
+        this.connectionOpenCallback(socket);
+        socket.on('message', (message) => this.handleMessage(socket, JSON.parse(message)));
+        socket.on('close', this.handleClose.bind(this));
+        socket.on('error', this.handleError.bind(this));
+    }
+
+    connectionOpenCallback(socket) {
+        console.log(`Opening new connection: ${socket.remoteAddress}`);
+    }
+
+    handleMessage(sock, data) {
+        const handler = this.handlers.find((handler) => handler.name == data.type);
+        if (!handler) {
+            sendJson(sock, {error: `No such handler ${data.type}`});
+            sock.close();
+        } else {
+            handler.handleMessage(sock, data);
+        }
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * Handles socket errors.
+     * @param {WebSocket} socket - The WebSocket connection instance.
+     * @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);
+    }
+}
+
+module.exports = SocketRoute;

package/src/ws/index.js

@@ -2,5 +2,6 @@ const { SOCKET_OPTIONS } = require('./BaseSocketServer');
 module.exports = { 
     SecureSocketServer: require('./SecureSocketServer'),
     SocketServer: require('./SocketServer'),
+    SocketRoute: require('./SocketRoute'),
     SOCKET_OPTIONS
 }

package/src/ws/util.js

@@ -0,0 +1,9 @@
+function sendJson(socket, data) {
+    socket.send(JSON.stringify(data));
+}
+
+function broadcast(sockets, data) {
+    sockets.forEach(socket => sendJson(socket, data));
+}
+
+module.exports = { sendJson, broadcast }