redweb 0.7.7 → 0.9.0

package/src/ws/SocketServer.js

@@ -6,16 +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);
-        if ((ownsServer && this.listen !== false) || (!ownsServer && options.listen === true)) {
-            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, 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

@@ -0,0 +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 };

package/src/ws/util.js

@@ -1,9 +1,38 @@
-function sendJson(socket, data) {
-    socket.send(JSON.stringify(data));
+function canSend(socket) {
+    return Boolean(
+        socket &&
+        typeof socket.send === 'function' &&
+        (socket.readyState === undefined || socket.readyState === 1 || socket.readyState === socket.OPEN)
+    );
 }
 
-function broadcast(sockets, data) {
-    sockets.forEach(socket => sendJson(socket, data));
+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;
+    }
 }
 
-module.exports = { sendJson, broadcast }
+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 };