redweb 0.7.5 → 0.7.7

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
@@ -28,7 +29,7 @@ const {
 
 ## HTTP servers (Express)
 
-`new HttpServer(options)` starts listening immediately (default port `80`). `new HttpsServer({ ssl: { key, cert }, ... })` does the same over TLS.
+`new HttpServer(options)` creates a Node HTTP server and starts listening immediately by default (default port `80`). `new HttpsServer({ ssl: { key, cert }, ... })` does the same over TLS.
 
 Options:
 
@@ -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` and `.server` without binding a port.
 - `listenCallback` (function): invoked after `.listen`.
 - `encoding` (`'json' | 'urlencoded'`): body parser selection.
 - `corsOptions`: passed to `cors`.
@@ -129,21 +131,102 @@ 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 and Node server without binding a port. Then pass `httpServer.server` 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 }
+  ]
+});
 
-app.get('/', (req, res) => res.send('hello'));
+new SocketServer({
+  server: httpServer.server,
+  routes: [ClipboardRoute]
+});
 
-new SocketServer({ server, port: 4000, routes: [ChatRoute] });
+httpServer.server.listen(3030, () => console.log('HTTP and WebSocket server listening on 3030'));
 ```
 
 ### Socket services
@@ -182,8 +265,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,7 +1,7 @@
 declare module 'redweb' {
     import { Application } from 'express';
     import { CorsOptions } from 'cors';
-    import { Server as HttpServer } from 'http';
+    import { Server as NodeHttpServer } from 'http';
     import { WebSocket, ServerOptions } from 'ws';
     import { Buffer } from 'buffer';
 
@@ -12,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;
@@ -25,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 };
     }
 
@@ -97,10 +99,10 @@ declare module 'redweb' {
 
     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;
     }
@@ -153,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.5",
+  "version": "0.7.7",
   "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,

package/src/http/HttpServer.js

@@ -1,14 +1,18 @@
-const { BaseHttpServer } = require('./BaseHttpServer');
+const http = require('http');
+const { BaseHttpServer } = require('./BaseHttpServer');
 
 /**
  * HTTP Server
  * @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);
+    this.server = http.createServer(this.app);
+    if (this.listen !== false) {
+        this.server.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/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/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;