redweb 0.8.0 → 0.10.0

package/src/ws/SocketServer.js

@@ -6,13 +6,13 @@ const { BaseSocketServer } = require('./BaseSocketServer');
  * @param {SocketServerOptions} options - Configuration options for SocketServer.
  * @return {Object} WebSocket server instance.
  */
-class SocketServer extends BaseSocketServer {
-    constructor(options) {
-        const ownsServer = !options?.server;
-        const server = options?.server || http.createServer();
-        super(server, options, ownsServer, 'SocketServer');
-        return this;
-    }
-}
+class SocketServer extends BaseSocketServer {
+    constructor(options) {
+        const ownsServer = !options?.server;
+        const server = options?.server || http.createServer();
+        super(server, options, ownsServer, 'SocketServer');
+        return this;
+    }
+}
 
 module.exports = SocketServer;

package/src/ws/TaskQueue.js

@@ -0,0 +1,64 @@
+class TaskQueue {
+    constructor(maxPending, onError = () => {}, errorContext) {
+        if (!Number.isInteger(maxPending) || maxPending < 1) {
+            throw new TypeError('`maxPending` must be a positive integer.');
+        }
+        if (typeof onError !== 'function') throw new TypeError('`onError` must be a function.');
+        this.maxPending = maxPending;
+        this.onError = onError;
+        this.errorContext = errorContext;
+        this.tasks = [];
+        this.running = false;
+        this.closed = false;
+        this.idleWaiters = [];
+    }
+
+    enqueue(task) {
+        if (typeof task !== 'function') throw new TypeError('Queued tasks must be functions.');
+        if (this.closed || this.tasks.length >= this.maxPending) return false;
+        this.tasks.push(task);
+        if (!this.running) void this.drain();
+        return true;
+    }
+
+    async drain() {
+        this.running = true;
+        while (!this.closed && this.tasks.length) {
+            const task = this.tasks.shift();
+            try {
+                await task();
+            } catch (error) {
+                try {
+                    await this.onError.call(this.errorContext, error);
+                } catch {
+                    // Error reporting must never interrupt queue cleanup.
+                }
+            }
+        }
+        this.running = false;
+        this.resolveIdle();
+    }
+
+    close() {
+        if (this.closed) return;
+        this.closed = true;
+        this.tasks.length = 0;
+        if (!this.running) this.resolveIdle();
+    }
+
+    whenIdle() {
+        if (!this.running && !this.tasks.length) return Promise.resolve();
+        return new Promise(resolve => this.idleWaiters.push(resolve));
+    }
+
+    resolveIdle() {
+        const waiters = this.idleWaiters.splice(0);
+        waiters.forEach(resolve => resolve());
+    }
+
+    get pending() {
+        return this.tasks.length + (this.running ? 1 : 0);
+    }
+}
+
+module.exports = TaskQueue;

package/src/ws/TokenBucket.js

@@ -0,0 +1,31 @@
+const { performance } = require('perf_hooks');
+
+class TokenBucket {
+    constructor({ capacity, refillPerSecond }, clock = () => performance.now()) {
+        if (!Number.isFinite(capacity) || capacity <= 0) {
+            throw new TypeError('`capacity` must be a positive number.');
+        }
+        if (!Number.isFinite(refillPerSecond) || refillPerSecond < 0) {
+            throw new TypeError('`refillPerSecond` must be a non-negative number.');
+        }
+        if (typeof clock !== 'function') throw new TypeError('`clock` must be a function.');
+        this.capacity = capacity;
+        this.refillPerMs = refillPerSecond / 1000;
+        this.tokens = capacity;
+        this.clock = clock;
+        this.updatedAt = clock();
+    }
+
+    consume(cost = 1) {
+        if (!Number.isFinite(cost) || cost <= 0) throw new TypeError('`cost` must be a positive number.');
+        const now = this.clock();
+        const elapsed = Math.max(0, now - this.updatedAt);
+        this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillPerMs);
+        this.updatedAt = now;
+        if (this.tokens < cost) return false;
+        this.tokens -= cost;
+        return true;
+    }
+}
+
+module.exports = TokenBucket;

package/src/ws/TransportPolicy.js

@@ -0,0 +1,68 @@
+const TokenBucket = require('./TokenBucket');
+const TaskQueue = require('./TaskQueue');
+
+const RATE_ACTIONS = new Set(['drop', 'disconnect']);
+const SLOW_ACTIONS = new Set(['drop', 'disconnect']);
+
+class TransportPolicy {
+    constructor(limits = {}, orderedMessages = false) {
+        if (!limits || typeof limits !== 'object' || Array.isArray(limits)) {
+            throw new TypeError('`limits` must be an object.');
+        }
+        const {
+            maxConnections = Infinity,
+            maxBufferedBytes = Infinity,
+            maxPendingMessages = 64,
+            messageRate = null,
+            slowConsumerAction = 'disconnect',
+        } = limits;
+        if (!(maxConnections === Infinity || Number.isInteger(maxConnections) && maxConnections > 0)) {
+            throw new TypeError('`limits.maxConnections` must be a positive integer.');
+        }
+        if (!(maxBufferedBytes === Infinity || Number.isInteger(maxBufferedBytes) && maxBufferedBytes >= 0)) {
+            throw new TypeError('`limits.maxBufferedBytes` must be a non-negative integer.');
+        }
+        if (!Number.isInteger(maxPendingMessages) || maxPendingMessages < 1) {
+            throw new TypeError('`limits.maxPendingMessages` must be a positive integer.');
+        }
+        if (!SLOW_ACTIONS.has(slowConsumerAction)) {
+            throw new TypeError('`limits.slowConsumerAction` must be "drop" or "disconnect".');
+        }
+        if (messageRate !== null) {
+            if (!messageRate || typeof messageRate !== 'object' || Array.isArray(messageRate)) {
+                throw new TypeError('`limits.messageRate` must be an object.');
+            }
+            if (!RATE_ACTIONS.has(messageRate.action ?? 'disconnect')) {
+                throw new TypeError('`limits.messageRate.action` must be "drop" or "disconnect".');
+            }
+            // Validate once without retaining the probe.
+            new TokenBucket(messageRate);
+        }
+        this.maxConnections = maxConnections;
+        this.maxBufferedBytes = maxBufferedBytes;
+        this.maxPendingMessages = maxPendingMessages;
+        this.messageRate = messageRate && { ...messageRate, action: messageRate.action ?? 'disconnect' };
+        this.slowConsumerAction = slowConsumerAction;
+        this.orderedMessages = Boolean(orderedMessages);
+    }
+
+    createRuntime(onError, errorContext) {
+        return {
+            limiter: this.messageRate ? new TokenBucket(this.messageRate) : null,
+            queue: this.orderedMessages ? new TaskQueue(this.maxPendingMessages, onError, errorContext) : null,
+        };
+    }
+
+    acceptsMessage(runtime) {
+        return runtime?.limiter ? runtime.limiter.consume() : true;
+    }
+
+    acceptsSend(socket, payloadBytes) {
+        if (this.maxBufferedBytes === Infinity) return true;
+        if ((socket.bufferedAmount || 0) + payloadBytes <= this.maxBufferedBytes) return true;
+        if (this.slowConsumerAction === 'disconnect') socket.close?.(1013, 'Slow consumer');
+        return false;
+    }
+}
+
+module.exports = TransportPolicy;

package/src/ws/index.js

@@ -1,9 +1,14 @@
 const { SOCKET_OPTIONS } = require('./BaseSocketServer');
+const { ERROR_CODES } = require('./ProtocolPolicy');
 module.exports = { 
     SecureSocketServer: require('./SecureSocketServer'),
     SocketServer: require('./SocketServer'),
     SocketRoute: require('./SocketRoute'),
     SocketService: require('./SocketService'),
+    FixedStepService: require('./FixedStepService'),
     SocketRegistry: require('./SocketRegistry'),
-    SOCKET_OPTIONS
-}
+    RoomRegistry: require('./RoomRegistry'),
+    SessionRegistry: require('./SessionRegistry'),
+    SOCKET_OPTIONS,
+    ERROR_CODES
+}

package/src/ws/protocol-schema.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "errorCodes": [
+    "INVALID_MESSAGE",
+    "UNKNOWN_HANDLER",
+    "HANDLER_FAILED",
+    "BINARY_UNSUPPORTED",
+    "RATE_LIMITED",
+    "QUEUE_FULL",
+    "CAPACITY_REACHED",
+    "INITIALIZATION_FAILED"
+  ]
+}

package/src/ws/protocol-validation.js

@@ -0,0 +1,21 @@
+function validString(value, maxLength) {
+    return typeof value === 'string' && value.length > 0 && value.length <= maxLength;
+}
+
+function validateEnvelope(message, version) {
+    if (!message || typeof message !== 'object' || message.v !== version || !validString(message.type, 256)) return false;
+    if (message.requestId !== undefined && !validString(message.requestId, 256)) return false;
+    if (message.sequence !== undefined && (!Number.isSafeInteger(message.sequence) || message.sequence < 0)) return false;
+    if (message.type === 'error') {
+        return Boolean(
+            !Object.prototype.hasOwnProperty.call(message, 'payload') &&
+            message.error &&
+            typeof message.error === 'object' &&
+            validString(message.error.code, 256) &&
+            validString(message.error.message, 1024)
+        );
+    }
+    return Object.prototype.hasOwnProperty.call(message, 'payload') && message.error === undefined;
+}
+
+module.exports = { validateEnvelope };

package/src/ws/shutdown.js

@@ -1,33 +1,33 @@
-function closeWebSocketServer(server, clients, timeoutMs) {
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        const finish = (error) => {
-            if (settled) return;
-            settled = true;
-            clearTimeout(timer);
-            if (error) reject(error);
-            else resolve();
-        };
-
-        const timer = setTimeout(() => {
-            const errors = [];
-            clients.forEach(socket => {
-                try {
-                    socket.terminate?.();
-                } catch (error) {
-                    errors.push(error);
-                }
-            });
-            finish(errors[0]);
-        }, timeoutMs);
-        timer.unref();
-
-        try {
-            server.close(finish);
-        } catch (error) {
-            finish(error);
-        }
-    });
-}
-
-module.exports = { closeWebSocketServer };
+function closeWebSocketServer(server, clients, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            if (error) reject(error);
+            else resolve();
+        };
+
+        const timer = setTimeout(() => {
+            const errors = [];
+            clients.forEach(socket => {
+                try {
+                    socket.terminate?.();
+                } catch (error) {
+                    errors.push(error);
+                }
+            });
+            finish(errors[0]);
+        }, timeoutMs);
+        timer.unref();
+
+        try {
+            server.close(finish);
+        } catch (error) {
+            finish(error);
+        }
+    });
+}
+
+module.exports = { closeWebSocketServer };

package/src/ws/util.js

@@ -1,30 +1,38 @@
-function canSend(socket) {
-    return Boolean(
-        socket &&
-        typeof socket.send === 'function' &&
-        (socket.readyState === undefined || socket.readyState === 1 || socket.readyState === socket.OPEN)
-    );
-}
-
-function sendJson(socket, data) {
-    if (!canSend(socket)) return false;
-    socket.send(JSON.stringify(data));
-    return true;
-}
-
-function broadcast(sockets, data) {
-    const payload = JSON.stringify(data);
-    let sent = 0;
-    sockets.forEach((socket) => {
-        if (!canSend(socket)) return;
-        try {
-            socket.send(payload);
-            sent += 1;
-        } catch {
-            // A socket can close between the ready-state check and send.
-        }
-    });
-    return sent;
-}
-
-module.exports = { sendJson, broadcast, canSend };
+function canSend(socket) {
+    return Boolean(
+        socket &&
+        typeof socket.send === 'function' &&
+        (socket.readyState === undefined || socket.readyState === 1 || socket.readyState === socket.OPEN)
+    );
+}
+
+function sendPayload(socket, payload, policy) {
+    if (!canSend(socket)) return false;
+    if (policy && !policy.acceptsSend(socket, Buffer.byteLength(payload))) return false;
+    try {
+        socket.send(payload);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function sendJson(socket, data, policy) {
+    if (arguments.length < 3) {
+        if (!canSend(socket)) return false;
+        socket.send(JSON.stringify(data));
+        return true;
+    }
+    return sendPayload(socket, JSON.stringify(data), policy);
+}
+
+function broadcast(sockets, data, policy) {
+    const payload = JSON.stringify(data);
+    let sent = 0;
+    sockets.forEach((socket) => {
+        if (sendPayload(socket, payload, policy)) sent += 1;
+    });
+    return sent;
+}
+
+module.exports = { sendJson, sendPayload, broadcast, canSend };

package/src/htmx/HtmxRenderer.js

@@ -1,73 +0,0 @@
-const fs = require('fs');
-const vm = require('vm');
-const path = require('path');
-
-class HtmxRenderer {
-    /**
-     * Render an .htmx file as JavaScript with embedded print statements.
-     * @param {string} filePath - Path to the .htmx file.
-     * @returns {string} Rendered HTML string with normalized whitespace.
-     */
-    static render(filePath, { rootDir = path.dirname(path.resolve(filePath)), timeoutMs = 1000 } = {}) {
-        if (!fs.existsSync(filePath)) {
-            throw new Error(`Template file not found: ${filePath}`);
-        }
-
-        let output = '';
-        const templateContent = fs.readFileSync(filePath, 'utf-8');
-
-        // Transform <@ ... @/> blocks into print() calls
-        const transformedTemplate = templateContent.replace(
-            /<@>([\s\S]*?)<@\/>/g,
-            (_, content) => `print(\`${content.replace(/{{\s*(.*?)\s*}}/g, '${$1}')}\`);`
-        );
-
-        // Wrap the script in an IIFE
-        const wrappedScript = `
-        (() => {
-            const print = (html) => output += html;
-            ${transformedTemplate}
-            return output;
-        })();
-        `;
-
-        // Create a custom require function that resolves paths relative to the template
-        const resolvedRoot = path.resolve(rootDir);
-        const customRequire = (modulePath) => {
-            if (typeof modulePath !== 'string' || !modulePath.startsWith('.')) {
-                throw new Error('Templates may only require relative modules');
-            }
-            const absolutePath = path.resolve(path.dirname(filePath), modulePath);
-            const relative = path.relative(resolvedRoot, absolutePath);
-            if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-                throw new Error('Template module is outside the allowed root');
-            }
-            return require(absolutePath);
-        };
-
-        // Execute the script in a sandbox
-        const script = new vm.Script(wrappedScript);
-        const sandbox = {
-            output: '',
-            require: customRequire, // Add custom require
-            __dirname: path.dirname(filePath),
-            __filename: filePath,
-        };
-        vm.createContext(sandbox);
-
-        // Get the rendered output
-        let result = script.runInContext(sandbox, { timeout: timeoutMs });
-
-        // Normalize spaces but preserve those in content
-        result = result
-            .replace(/>\s+</g, '><')       // Remove spaces between tags
-            .replace(/\s+/g, ' ')         // Collapse multiple spaces to one
-            .replace(/>\s+/g, '>')        // Remove spaces after tags
-            .replace(/\s+</g, '<')        // Remove spaces before tags
-            .trim();                      // Trim leading and trailing spaces
-
-        return result;
-    }
-}
-
-module.exports = HtmxRenderer;

package/src/htmx/RedWebHtmxComponent.js

@@ -1,11 +0,0 @@
-class RedWebHtmxComponent {
-    constructor(props = {}) {
-        this.props = props;
-    }
-
-    render() {
-        throw new Error('Render method must be implemented in derived components');
-    }
-}
-
-module.exports = RedWebHtmxComponent;