redweb 0.7.0 → 0.7.1

package/README.md

@@ -1,7 +1,3 @@
-Here is the **fully updated and cleaned-up `README.md`** for RedWeb, now featuring a **working broadcast chat example** using `allowDuplicateConnections`:
-
----
-
 # RedWeb
 
 **RedWeb** is a flexible Node.js framework built on top of **Express.js** and **WebSocket**. It enables quick setup of HTTP(S) and WebSocket servers with a modular route and handler system.
@@ -21,8 +17,8 @@ npm install redweb
 ```js
 const { HttpServer, SocketServer } = require('redweb');
 
-const httpServer = new HttpServer();
-const socketServer = new SocketServer();
+new HttpServer(); // serves public/ by default
+new SocketServer(); // starts WS on :3000
 ```
 
 ---
@@ -49,8 +45,7 @@ new HttpServer({
 });
 ```
 
-`.htmx` files under `public/` will render server-side.
-Example:
+`.htmx` files under `public/` will render server-side. Example:
 
 ```html
 <!-- public/hello.htmx -->
@@ -75,7 +70,6 @@ class ChatHandler extends BaseHandler {
 
   onMessage(socket, message) {
     const text = message.text;
-    console.log(`Broadcasting: ${text}`);
     socket.broadcast({ type: 'chat', text });
   }
 }
@@ -96,7 +90,7 @@ class ChatRoute extends SocketRoute {
     super({
       path: '/chat',
       handlers: [ChatHandler],
-      allowDuplicateConnections: true // key for local testing!
+      allowDuplicateConnections: true
     });
   }
 }
@@ -149,13 +143,163 @@ new SocketServer({
 </html>
 ```
 
-Open multiple tabs to test!
+Open multiple tabs to test.
+
+---
+
+## 🧩 Socket Architecture
+
+### `SocketRoute`
+
+Defines a WebSocket path, handlers, and optional route-scoped services:
+
+```js
+new SocketRoute({
+  path: '/game',
+  handlers: [ChatHandler, MoveHandler],
+  services: [MatchService], // ✅ Scoped only to this route
+  allowDuplicateConnections: true
+});
+```
+
+---
+
+### `BaseHandler`
+
+Handlers are message-type keyed classes:
+
+```js
+class MoveHandler extends BaseHandler {
+  constructor() {
+    super('move');
+  }
+
+  onMessage(socket, message) {
+    // handle movement logic
+  }
+}
+```
+
+---
+
+### `SocketService` (NEW)
+
+Socket services run alongside handlers on a route. Use for timers, logic, cleanup.
+
+```js
+class MatchService extends SocketService {
+  constructor() {
+    super('match', 1000); // tick every 1s
+  }
+
+  onInit(route) {
+    route.registry.on('maxPlayersReached', () => this.startMatch());
+  }
+
+  onTick() {
+    // tick logic
+  }
+
+  onShutdown() {
+    // cleanup
+  }
+}
+```
+
+### 📦 `SocketRegistry` (NEW) – Event-Driven Socket Object Store
+
+`SocketRegistry` is a lightweight, extendable class for managing WebSocket-connected clients (or any socket-bound object). It provides add/remove/get/broadcast utilities with full `EventEmitter` support.
+
+Useful for managing players, NPCs, chat members, rooms, etc.
+
+---
+
+### 🔧 Basic Usage
+
+```js
+const { SocketRegistry } = require('redweb');
+
+class Player {
+    constructor(socket, id) {
+        this.socket = socket;
+        this.id = id;
+    }
+
+    send(type, payload) {
+        this.socket.send(JSON.stringify({ type, ...payload }));
+    }
+
+    getSanitized() {
+        return { id: this.id };
+    }
+}
+```
+
+---
+
+### 🚀 Extending `SocketRegistry` to Create a Player Registry
+
+```js
+class PlayerRegistry extends SocketRegistry {
+    create(socket, id) {
+        return new Player(socket, id);
+    }
+
+    addPlayer(socket, id) {
+        const player = this.create(socket, id);
+        const success = this.add(player);
+        if (success) this.emit('playerJoined', player);
+        return success;
+    }
+
+    removePlayer(id) {
+        const success = this.remove(id);
+        if (success) this.emit('playerLeft', id);
+        return success;
+    }
+
+    broadcastToAll(message) {
+        this.items.forEach(player => player.send(message.type, message));
+    }
+}
+```
 
 ---
 
-## 🔧 Options
+### 📣 Built-in Events
 
-### HTTP / HTTPS Server Options
+You can listen to events:
+
+```js
+const registry = new PlayerRegistry();
+
+registry.on('playerJoined', player => {
+    console.log('New player:', player.id);
+});
+
+registry.on('playerLeft', id => {
+    console.log('Player left:', id);
+});
+```
+
+---
+
+### 🔄 Built-in Methods
+
+* `add(player)`
+* `remove(id)`
+* `getById(id)`
+* `getBySocket(socket)`
+* `all()`
+* `count()`
+* `broadcast(message, excludeSocket?)`
+* `getSanitizedList()`
+
+---
+
+## 🔧 Configuration
+
+### HTTP / HTTPS Options
 
 | Option                | Type      | Default        | Description                    |
 | --------------------- | --------- | -------------- | ------------------------------ |
@@ -170,20 +314,38 @@ Open multiple tabs to test!
 
 ### WebSocket Server Options
 
-| Option                      | Type                | Default | Description                         |
-| --------------------------- | ------------------- | ------- | ----------------------------------- |
-| `port`                      | number              | `3000`  | WebSocket port                      |
-| `routes`                    | `SocketRoute[]`     | `[]`    | List of custom route classes        |
-| `allowDuplicateConnections` | boolean (per route) | `false` | Allow multiple clients from same IP |
+| Option   | Type            | Default | Description                  |
+| -------- | --------------- | ------- | ---------------------------- |
+| `port`   | number          | `3000`  | WebSocket port               |
+| `routes` | `SocketRoute[]` | `[]`    | List of custom route classes |
+
+&nbsp;
+
+# Changelog
+Here’s the updated `CHANGELOG.md` entry for **RedWeb v0.7.1**, written professionally and focused only on the framework-level additions:
 
 ---
 
-## 🆕 0.7.0 Update Highlights
+## 📦 RedWeb v0.7.1 – Socket Services & Registries
+
+### ✨ Added
+
+* `SocketService`: A new class for running autonomous, lifecycle-aware logic alongside a `SocketRoute`. Ideal for game loops, timers, state machines, or server-side AI.
+
+  * Hooks: `onInit(route)`, `onTick()`, `onShutdown()`
+  * Optional `tickRateMs` support for periodic execution
+
+* `SocketRegistry`: A generic, event-driven registry for managing WebSocket-bound entities
+
+  * Includes `.add()`, `.remove()`, `.getById()`, `.broadcast()`
+  * Fully compatible with custom socket wrappers and `EventEmitter`
+
+## 0.7.0 Update Highlights
 
-* ✅ `allowDuplicateConnections` for multi-tab testing
-* ✅ Robust message validation
-* ✅ `socket.broadcast()` now excludes sender
-* ✅ Better error handling
+* allowDuplicateConnections for multi-tab testing
+* Robust message validation
+* socket.broadcast() now excludes sender
+* Better error handling
 
 ---
 

package/index.d.ts

@@ -3,96 +3,170 @@ declare module 'redweb' {
     import { CorsOptions } from 'cors';
     import { Server as HttpServer } from 'http';
     import { WebSocket } from 'ws';
-  
+
+    /** ─────────────────── HTTP / CORE ─────────────────── */
+
     export type RedWebEncoding = 'json' | 'urlencoded';
-  
+
     export interface RedWebOptions {
-      port?: number;
-      bind?: string;
-      publicPaths?: string[];
-      services?: Array<{ serviceName: string; method: string; function: Function }>;
-      listenCallback?: () => void;
-      encoding?: RedWebEncoding;
-      ssl?: { key: string; cert: string };
-      server?: Application;
-      corsOptions?: CorsOptions;
-      enableHtmxRendering?: boolean;
+        port?: number;
+        bind?: string;
+        publicPaths?: string[];
+        services?: Array<{ serviceName: string; method: string; function: Function }>;
+        listenCallback?: () => void;
+        encoding?: RedWebEncoding;
+        ssl?: { key: string; cert: string };
+        server?: Application;
+        corsOptions?: CorsOptions;
+        enableHtmxRendering?: boolean;
     }
-  
+
+    /** ─────────────────── SOCKET SERVER ─────────────────── */
+
     export interface SocketServerOptions {
-      server?: HttpServer;
-      port?: number;
-      routes?: Array<new () => SocketRoute>;
-      ssl?: { key: string; cert: string };
+        server?: HttpServer;
+        port?: number;
+        routes?: Array<new () => SocketRoute>;
+        ssl?: { key: string; cert: string };
     }
-  
+
+    /** ─────────────────── ROUTES & HANDLERS ─────────────────── */
+
     export interface SocketRouteConfig {
-      path: string;
-      handlers: Array<new () => BaseHandler>;
-      allowDuplicateConnections?: boolean;
+        path: string;
+        handlers: Array<new () => BaseHandler>;
+        services?: Array<new () => SocketService>;
+        allowDuplicateConnections?: boolean;
     }
-  
+
+    /** Socket‑side autonomous service (game loops, timers, etc.) */
+    export abstract class SocketService {
+        name: string;
+        tickRateMs?: number;
+        protected _tickHandle?: NodeJS.Timeout;
+
+        constructor(name: string, tickRateMs?: number);
+
+        /** Called once when the route is initialised */
+        onInit(route: SocketRoute): void;
+
+        /** Optional recurring tick (respecting tickRateMs) */
+        onTick?(): void;
+
+        /** Called on process shutdown / route removal */
+        onShutdown(): void;
+    }
+
+    /** Message handler, triggered by client messages */
     export class BaseHandler {
-      name: string;
-      constructor(name: string);
-      handleMessage(
-        socket: WebSocket & {
-          sendJson: (message: object) => void;
-          broadcast: (message: object) => void;
-        },
-        message: any
-      ): void;
-      onMessage(socket: WebSocket, message: any): void;
-      onInitialContact(socket: WebSocket): void;
+        name: string;
+        constructor(name: string);
+
+        handleMessage(
+            socket: WebSocket & {
+                sendJson: (message: object) => void;
+                broadcast: (message: object) => void;
+            },
+            message: any
+        ): void;
+
+        onMessage(socket: WebSocket, message: any): 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;
+        path: string;
+        handlers: BaseHandler[];
+        clients: Map<string, WebSocket>;
+        allowDuplicateConnections?: boolean;
+
+        constructor(config: SocketRouteConfig);
+
+        addHandler(handler: new () => BaseHandler): void;
+        handleMessage(sock: WebSocket, data: any): void;
     }
-  
+
+    /** ─────────────────── SERVER BASE ─────────────────── */
+
     export class BaseSocketServer {
-      clients: Map<string, WebSocket>;
-      server: HttpServer;
-      routes: SocketRoute[];
-      constructor(server: HttpServer, options?: SocketServerOptions);
-      addRoute(route: new () => SocketRoute): void;
+        clients: Map<string, WebSocket>;
+        server: HttpServer;
+        routes: SocketRoute[];
+
+        constructor(server: HttpServer, options?: SocketServerOptions);
+
+        addRoute(route: new () => SocketRoute): void;
+    }
+
+    /** ─────────────────── REGISTRY & UTIL TYPES ─────────────────── */
+
+    export interface SocketWrapper {
+        socket: WebSocket;
+        id: string;
+        send: (type: string, payload: Record<string, any>) => void;
+        getSanitized?(): Record<string, any>;
+    }
+
+    export type SocketMessage = {
+        type: string;
+        [key: string]: any;
+    };
+
+    /** Generic event‑driven registry for socket objects */
+    export class SocketRegistry<T extends SocketWrapper = SocketWrapper> {
+        protected clients: T[];
+
+        onCreate?: (client: T) => boolean | void;
+        onRemove?: (client: T) => boolean | void;
+
+        constructor();
+
+        setCreateValidator(fn: (client: T) => boolean | void): void;
+        setRemoveValidator(fn: (client: T) => boolean | void): void;
+
+        add(client: T): boolean;
+        removeById(id: string): boolean;
+
+        getById(id: string): T | undefined;
+        getBySocket(socket: WebSocket): T | undefined;
+        allWithout(socket: WebSocket): T[];
+
+        broadcast(message: SocketMessage, excludeSocket?: WebSocket | null): void;
+        getSanitizedList(): Record<string, any>[];
     }
-  
+
+    /** ─────────────────── CONCRETE SERVERS ─────────────────── */
+
     export class SocketServer extends BaseSocketServer {
-      constructor(options?: SocketServerOptions);
+        constructor(options?: SocketServerOptions);
     }
-  
+
     export class SecureSocketServer extends BaseSocketServer {
-      constructor(options?: SocketServerOptions);
+        constructor(options?: SocketServerOptions);
     }
-  
+
     export class HttpServer {
-      constructor(options?: RedWebOptions);
+        constructor(options?: RedWebOptions);
     }
-  
+
     export class HttpsServer {
-      constructor(options?: RedWebOptions);
+        constructor(options?: RedWebOptions);
     }
-  
+
+    /** ─────────────────── CONSTANTS ─────────────────── */
+
     export const METHODS: {
-      GET: 'get';
-      POST: 'post';
-      PUT: 'put';
-      DELETE: 'delete';
+        GET: 'get';
+        POST: 'post';
+        PUT: 'put';
+        DELETE: 'delete';
     };
-  
+
     export const ENCODINGS: {
-      json: 'json';
-      urlencoded: 'urlencoded';
+        json: 'json';
+        urlencoded: 'urlencoded';
     };
-  
+
     export const HTTP_OPTIONS: RedWebOptions;
     export const SOCKET_OPTIONS: SocketServerOptions;
-  }
-  
+}

package/index.js

@@ -1,6 +1,6 @@
 const { METHODS } = require('./src/http');
 const { sendJson } = require('./src/ws/util');
-const { SocketServer, SecureSocketServer, SOCKET_OPTIONS, SocketRoute } = require('./src/ws');
+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');
@@ -11,6 +11,8 @@ module.exports = {
     SecureSocketServer,
     BaseHandler,
     SocketRoute,
+    SocketService,
+    SocketRegistry,
     sendJson,
     SOCKET_OPTIONS,
     METHODS

package/package.json

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

package/src/ws/BaseSocketServer.js

@@ -1,57 +1,62 @@
 /**
  * @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 {Array<new () => import('./SocketRoute').SocketRoute>} [routes] - An array of handler classes to use for routing.
+ * @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]
  */
 
 const DefaultRoute = require('./DefaultRoute');
 
 const SOCKET_OPTIONS = {
-    port: 3000,
-    ssl: null,
-    routes: []
+  port: 3000,
+  ssl:  null,
+  routes: []
 };
 
 /**
- * Broadcasts a message to all connected clients.
- * @param {BaseSocketServer} socketServer - The WebSocket server instance.
- * @param {object} message - The message to broadcast.
- */
-function broadcast(socketServer, message) {
-    socketServer.clients.forEach(client => client.send(JSON.stringify(message)));
-}
-
-/**
- * Represents the base WebSocket server.
+ * Base WebSocket server
  */
 class BaseSocketServer {
-    /**
-     * @param {import('http').Server} server - The HTTP server instance to bind the WebSocket server to.
-     * @param {SocketServerOptions} options - The configuration options for the WebSocket server.
-     */
-    constructor(server, options = {}) {
-        this.clients = new Map(); // Map of clients by their IP addresses.
-        Object.assign(this, { ...SOCKET_OPTIONS, ...options });
-        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));
-    }
-
-    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));
-    }
-
-    /**
-     * 
-     * @param {new () => import('./SocketRoute')} route 
-     */
-    addRoute(route) {
-        this.routes.push(new route(this.server));
-    }
+  /**
+   * @param {import('http').Server} server
+   * @param {SocketServerOptions}  [options]
+   */
+  constructor(server, options = {}) {
+    this.clients = new Map();
+    Object.assign(this, { ...SOCKET_OPTIONS, ...options });
+    this.server = server;
+
+    /* ─── ROUTE INITIALISATION ─────────────────────────── */
+    if (!options.routes?.length) options.routes = [DefaultRoute];
+    this.routes = options.routes.map(RouteClass => new RouteClass(server));
+
+    this.server.on('upgrade', this.handleUpgrade.bind(this));
+  }
+
+  handleUpgrade(req, sock, head) {
+    const route = this.routes.find(r => r.path === req.url);
+    if (!route) return sock.destroy();
+
+    route.server.handleUpgrade(req, sock, head, (s, r) =>
+      route.server.emit('connection', s, r)
+    );
+  }
+
+  /**
+   * Dynamically attach a new route at runtime
+   * @param {new () => import('./SocketRoute').SocketRoute} RouteClass
+   */
+  addRoute(RouteClass) {
+    this.routes.push(new RouteClass(this.server));
+  }
+
+  /**
+   * Gracefully tear down all routes (and their services)
+   */
+  shutdown() {
+    this.routes.forEach(route => route.shutdown?.());
+    this.server.close();
+  }
 }
 
 module.exports = { BaseSocketServer, SOCKET_OPTIONS };

package/src/ws/SocketRegistry.js

@@ -0,0 +1,37 @@
+// handlers/SocketRegistry.js
+const { EventEmitter } = require("events");
+
+class SocketRegistry extends EventEmitter {
+    constructor() {
+        super();
+        this.items = [];
+    }
+
+    add(item) {
+        this.items.push(item);
+        this.emit("added", item);
+    }
+
+    remove(itemOrId, by = "id") {
+        const idx = typeof itemOrId === "object"
+            ? this.items.findIndex(i => i === itemOrId)
+            : this.items.findIndex(i => i[by] === itemOrId);
+
+        if (idx !== -1) {
+            const [removed] = this.items.splice(idx, 1);
+            this.emit("removed", removed);
+            return true;
+        }
+        return false;
+    }
+
+    all() {
+        return [...this.items];
+    }
+
+    count() {
+        return this.all().length;
+    }
+}
+
+module.exports = SocketRegistry;

package/src/ws/SocketRoute.js

@@ -13,8 +13,9 @@ class SocketRoute {
      * @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.
-     */
-    constructor({path, handlers, allowDuplicateConnections } = {}) {
+     * @param {Array<new () => SocketService>} [options.services] 
+    */
+    constructor({ path, handlers, services = [], allowDuplicateConnections } = {}) {
         if (!path) {
             throw new Error('A `path` must be specified for the SocketRoute.');
         }
@@ -37,6 +38,13 @@ class SocketRoute {
         this.server = new WebSocketServer({ noServer: true, path });
         this.server.on('connection', this.handleConnection.bind(this));
         this.allowDuplicateConnections = allowDuplicateConnections;
+
+        /* ─── ROUTE‑SCOPED SERVICES ─────────────────────────── */
+        this.services = services.map(SvcClass => {
+            const svc = new SvcClass();
+            if (typeof svc.onInit === 'function') svc.onInit(this);
+            return svc;
+        });
     }
     /**
      * Adds a new handler to the WebSocket server.
@@ -99,7 +107,7 @@ class SocketRoute {
     handleMessage(sock, data) {
         const handler = this.handlers.find((handler) => handler.name == data.type);
         if (!handler) {
-            sendJson(sock, {error: `No such handler ${data.type}`});
+            sendJson(sock, { error: `No such handler ${data.type}` });
             sock.close();
         } else {
             try {
@@ -123,6 +131,11 @@ class SocketRoute {
         if (this.connectionCloseCallback) this.connectionCloseCallback(socket);
     }
 
+    shutdown() {
+        this.services.forEach(svc => svc.onShutdown && svc.onShutdown());
+        this.server.close();
+    }
+
     /**
      * Handles socket errors.
      * @param {WebSocket} socket - The WebSocket connection instance.

package/src/ws/SocketService.js

@@ -0,0 +1,33 @@
+// handlers/SocketService.js
+class SocketService {
+    /**
+     * @param {string} name            – service identifier
+     * @param {?number} tickRateMs     – optional tick interval (ms)
+     */
+    constructor(name, tickRateMs = null) {
+      this.name        = name;
+      this.tickRateMs  = tickRateMs;
+      this._tickHandle = null;
+    }
+  
+    /**
+     * Called once by the owning SocketRoute.
+     * @param {import('../SocketRoute')} route – the route this service belongs to
+     */
+    onInit(route) {
+      this.route = route;                        // full access to route, clients, broadcast…
+      if (this.tickRateMs && this.onTick) {
+        this._tickHandle = setInterval(() => this.onTick(), this.tickRateMs);
+      }
+    }
+  
+    /* Optional */
+    // onTick() {}
+  
+    onShutdown() {
+      if (this._tickHandle) clearInterval(this._tickHandle);
+    }
+  }
+  
+  module.exports = SocketService;
+  

package/src/ws/index.js

@@ -3,5 +3,7 @@ module.exports = {
     SecureSocketServer: require('./SecureSocketServer'),
     SocketServer: require('./SocketServer'),
     SocketRoute: require('./SocketRoute'),
+    SocketService: require('./SocketService'),
+    SocketRegistry: require('./SocketRegistry'),
     SOCKET_OPTIONS
 }