redweb 0.8.0 → 0.9.0

package/src/ws/RoomRegistry.js

@@ -0,0 +1,117 @@
+const { broadcast } = require('./util');
+
+class RoomRegistry {
+    constructor(options = {}, { hasConnection, policy, onChange } = {}) {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) {
+            throw new TypeError('`rooms` must be an object or true.');
+        }
+        const {
+            maxRooms = 1000,
+            maxMembersPerRoom = 1000,
+            maxRoomsPerConnection = 32,
+            maxRoomIdLength = 128,
+        } = options;
+        for (const [name, value] of Object.entries({ maxRooms, maxMembersPerRoom, maxRoomsPerConnection, maxRoomIdLength })) {
+            if (!Number.isInteger(value) || value < 1) throw new TypeError(`\`rooms.${name}\` must be a positive integer.`);
+        }
+        if (hasConnection !== undefined && typeof hasConnection !== 'function') {
+            throw new TypeError('`hasConnection` must be a function.');
+        }
+        if (onChange !== undefined && typeof onChange !== 'function') {
+            throw new TypeError('`onChange` must be a function.');
+        }
+        this.options = { maxRooms, maxMembersPerRoom, maxRoomsPerConnection, maxRoomIdLength };
+        this.hasConnection = hasConnection || (() => true);
+        this.policy = policy;
+        this.onChange = onChange || (() => {});
+        this.rooms = new Map();
+        this.memberships = new WeakMap();
+        this.closed = false;
+    }
+
+    validateRoomId(roomId) {
+        if (typeof roomId !== 'string' || !roomId || roomId.length > this.options.maxRoomIdLength) {
+            throw new TypeError(`Room IDs must be non-empty strings of at most ${this.options.maxRoomIdLength} characters.`);
+        }
+    }
+
+    join(roomId, socket) {
+        this.validateRoomId(roomId);
+        if (this.closed) return false;
+        if (!socket || !this.hasConnection(socket)) return false;
+        let members = this.rooms.get(roomId);
+        if (members?.has(socket)) return true;
+        const memberships = this.memberships.get(socket) || new Set();
+        if (!members && this.rooms.size >= this.options.maxRooms) return false;
+        if (members && members.size >= this.options.maxMembersPerRoom) return false;
+        if (memberships.size >= this.options.maxRoomsPerConnection) return false;
+        if (!members) {
+            members = new Set();
+            this.rooms.set(roomId, members);
+        }
+        members.add(socket);
+        memberships.add(roomId);
+        this.memberships.set(socket, memberships);
+        this.onChange('join', roomId, socket);
+        return true;
+    }
+
+    leave(roomId, socket) {
+        this.validateRoomId(roomId);
+        const members = this.rooms.get(roomId);
+        if (!members?.delete(socket)) return false;
+        const memberships = this.memberships.get(socket);
+        memberships?.delete(roomId);
+        if (!memberships?.size) this.memberships.delete(socket);
+        if (!members.size) this.rooms.delete(roomId);
+        this.onChange('leave', roomId, socket);
+        return true;
+    }
+
+    leaveAll(socket) {
+        const memberships = this.memberships.get(socket);
+        if (!memberships) return 0;
+        const roomIds = [...memberships];
+        roomIds.forEach(roomId => this.leave(roomId, socket));
+        return roomIds.length;
+    }
+
+    members(roomId) {
+        this.validateRoomId(roomId);
+        return [...(this.rooms.get(roomId) || [])];
+    }
+
+    has(roomId, socket) {
+        this.validateRoomId(roomId);
+        return Boolean(this.rooms.get(roomId)?.has(socket));
+    }
+
+    broadcast(roomId, data, { except } = {}) {
+        this.validateRoomId(roomId);
+        if (this.closed) return 0;
+        const members = this.rooms.get(roomId);
+        if (!members) return 0;
+        const recipients = except === undefined
+            ? members
+            : [...members].filter(socket => socket !== except);
+        return broadcast(recipients, data, this.policy);
+    }
+
+    clear() {
+        this.rooms.clear();
+        this.memberships = new WeakMap();
+    }
+
+    close() {
+        if (this.closed) return false;
+        this.closed = true;
+        this.clear();
+        return true;
+    }
+
+    get size() {
+        return this.rooms.size;
+    }
+}
+
+module.exports = RoomRegistry;

package/src/ws/RouteRuntime.js

@@ -0,0 +1,146 @@
+const { randomUUID } = require('crypto');
+const { ADMISSION_CONTEXT } = require('./AdmissionPolicy');
+const { PROTOCOL_CONTEXT } = require('./ProtocolPolicy');
+const HeartbeatMonitor = require('./HeartbeatMonitor');
+const RoomRegistry = require('./RoomRegistry');
+const SessionRegistry = require('./SessionRegistry');
+const DistributionBridge = require('./DistributionBridge');
+
+function joinRoom(roomId) { return this.__redwebRuntimeOwner.rooms.join(roomId, this); }
+function leaveRoom(roomId) { return this.__redwebRuntimeOwner.rooms.leave(roomId, this); }
+function roomBroadcast(roomId, data, options) { return this.__redwebRuntimeOwner.rooms.broadcast(roomId, data, options); }
+function createSession(sessionId, data) {
+    this.__redwebRuntimeOwner.ensureContext(this);
+    return this.__redwebRuntimeOwner.sessions.create(sessionId, data, this);
+}
+function resumeSession(sessionId) {
+    this.__redwebRuntimeOwner.ensureContext(this);
+    return this.__redwebRuntimeOwner.sessions.resume(sessionId, this);
+}
+function publishEvent(type, payload) { return this.__redwebRuntimeOwner.route.publish(type, payload); }
+
+class RouteRuntime {
+    constructor(route, { heartbeat, rooms, sessions, distribution, drainHandlers }) {
+        this.route = route;
+        this.inFlight = drainHandlers ? new Set() : null;
+        this.abortController = drainHandlers ? new AbortController() : null;
+        this.acceptingWork = true;
+        try {
+            this.heartbeat = heartbeat === undefined ? null : new HeartbeatMonitor(heartbeat, route.logger);
+            this.rooms = rooms === undefined || rooms === false
+                ? null
+                : new RoomRegistry(rooms === true ? {} : rooms, {
+                    hasConnection: socket => route.clients.get(socket.clientKey) === socket,
+                    policy: route.transportPolicy,
+                    onChange: action => {
+                        route.metrics?.increment(`redweb.room.${action}`);
+                        route.metrics?.gauge('redweb.rooms.active', this.rooms.size);
+                    },
+                });
+            this.sessions = sessions === undefined || sessions === false
+                ? null
+                : new SessionRegistry(sessions === true ? {} : sessions, route.logger);
+            if (distribution !== undefined && distribution !== false && typeof distribution?.onEvent !== 'function') {
+                throw new TypeError('`distribution.onEvent` must be a function.');
+            }
+            this.distribution = distribution === undefined || distribution === false
+                ? null
+                : new DistributionBridge(distribution, event => distribution.onEvent(event, route), route.logger);
+        } catch (error) {
+            this.heartbeat?.stop();
+            this.sessions?.stop();
+            throw error;
+        }
+    }
+
+    expose() {
+        return {
+            heartbeatMonitor: this.heartbeat,
+            rooms: this.rooms,
+            sessions: this.sessions,
+            distribution: this.distribution,
+            inFlight: this.inFlight,
+            abortController: this.abortController,
+        };
+    }
+
+    decorate(socket, request) {
+        if (request?.[ADMISSION_CONTEXT] || request?.[PROTOCOL_CONTEXT] || this.abortController) this.ensureContext(socket, request);
+        if (this.rooms || this.sessions || this.distribution) socket.__redwebRuntimeOwner = this;
+        if (this.rooms) {
+            socket.joinRoom = joinRoom;
+            socket.leaveRoom = leaveRoom;
+            socket.roomBroadcast = roomBroadcast;
+        }
+        if (this.sessions) {
+            socket.createSession = createSession;
+            socket.resumeSession = resumeSession;
+        }
+        if (this.distribution) socket.publishEvent = publishEvent;
+    }
+
+    ensureContext(socket, request) {
+        if (socket.context) return socket.context;
+        socket.context = {
+            connectionId: randomUUID(),
+            principal: request?.[ADMISSION_CONTEXT]?.principal,
+            session: null,
+            metadata: Object.create(null),
+            signal: this.abortController?.signal,
+            protocol: request?.[PROTOCOL_CONTEXT],
+        };
+        return socket.context;
+    }
+
+    attach(socket) {
+        this.heartbeat?.attach(socket);
+    }
+
+    detach(socket) {
+        this.rooms?.leaveAll(socket);
+        this.sessions?.release(socket);
+        this.heartbeat?.detach(socket);
+    }
+
+    run(task) {
+        if (!this.acceptingWork) return Promise.resolve(false);
+        if (!this.inFlight) return task();
+        const promise = Promise.resolve().then(task);
+        this.inFlight.add(promise);
+        const cleanup = () => this.inFlight.delete(promise);
+        void promise.then(cleanup, cleanup);
+        return promise;
+    }
+
+    beginDrain() {
+        this.abortController?.abort();
+        this.route.clients.forEach(socket => socket.__redwebRuntime?.queue?.close());
+    }
+
+    isReady() {
+        return !this.distribution?.required || this.distribution.isReady();
+    }
+
+    stopHeartbeat() {
+        this.heartbeat?.stop();
+    }
+
+    closeDistribution() {
+        return this.distribution?.close();
+    }
+
+    closeState() {
+        this.rooms?.close();
+        this.sessions?.stop();
+    }
+
+    clearInFlight() {
+        this.inFlight?.clear();
+    }
+
+    stopAcceptingWork() {
+        this.acceptingWork = false;
+    }
+}
+
+module.exports = RouteRuntime;

package/src/ws/SecureSocketServer.js

@@ -7,14 +7,14 @@ const { BaseSocketServer } = require('./BaseSocketServer');
  * @param {SocketServerOptions} options - Configuration options for SecureSocketServer.
  * @return {Object} WebSocket server instance.
  */
-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, ownsServer, 'SecureSocketServer');
-        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, ownsServer, 'SecureSocketServer');
+        return this;
+    }
+}
 
 module.exports = SecureSocketServer;

package/src/ws/SessionRegistry.js

@@ -0,0 +1,135 @@
+const { performance } = require('perf_hooks');
+
+class SessionRegistry {
+    constructor(options = {}, logger = console, clock = () => performance.now()) {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) {
+            throw new TypeError('`sessions` must be an object or true.');
+        }
+        const {
+            ttlMs = 30_000,
+            maxSessions = 10_000,
+            maxSessionIdLength = 256,
+            sweepIntervalMs = Math.min(ttlMs, 1000),
+        } = options;
+        for (const [name, value] of Object.entries({ ttlMs, maxSessions, maxSessionIdLength, sweepIntervalMs })) {
+            if (!Number.isInteger(value) || value < 1) throw new TypeError(`\`sessions.${name}\` must be a positive integer.`);
+        }
+        if (typeof clock !== 'function') throw new TypeError('`clock` must be a function.');
+        this.ttlMs = ttlMs;
+        this.maxSessions = maxSessions;
+        this.maxSessionIdLength = maxSessionIdLength;
+        this.logger = logger;
+        this.clock = clock;
+        this.sessions = new Map();
+        this.closed = false;
+        this.timer = setInterval(() => this.sweep(), sweepIntervalMs);
+        this.timer.unref();
+    }
+
+    validateId(sessionId) {
+        if (typeof sessionId !== 'string' || !sessionId || sessionId.length > this.maxSessionIdLength) {
+            throw new TypeError(`Session IDs must be non-empty strings of at most ${this.maxSessionIdLength} characters.`);
+        }
+    }
+
+    create(sessionId, data, socket) {
+        this.validateId(sessionId);
+        if (this.closed || this.sessions.has(sessionId)) return false;
+        if (this.sessions.size >= this.maxSessions) this.sweep();
+        if (this.sessions.size >= this.maxSessions) return false;
+        const record = { data, socket: null, expiresAt: this.clock() + this.ttlMs };
+        this.sessions.set(sessionId, record);
+        if (socket) this.assign(sessionId, record, socket);
+        return true;
+    }
+
+    resume(sessionId, socket) {
+        this.validateId(sessionId);
+        if (this.closed) return null;
+        const record = this.sessions.get(sessionId);
+        if (!record) return null;
+        if (!record.socket && record.expiresAt <= this.clock()) {
+            this.sessions.delete(sessionId);
+            return null;
+        }
+        this.assign(sessionId, record, socket);
+        return record.data;
+    }
+
+    assign(sessionId, record, socket) {
+        if (!socket) throw new TypeError('A socket is required to own a session.');
+        const previousSessionId = socket.__redwebSessionId;
+        if (previousSessionId && previousSessionId !== sessionId) this.release(socket);
+        const previousSocket = record.socket;
+        record.socket = socket;
+        record.expiresAt = Infinity;
+        socket.__redwebSessionId = sessionId;
+        if (socket.context) socket.context.session = { id: sessionId, data: record.data };
+        if (previousSocket && previousSocket !== socket) {
+            previousSocket.__redwebSessionId = undefined;
+            if (previousSocket.context) previousSocket.context.session = null;
+            try {
+                previousSocket.close?.(4000, 'Session resumed elsewhere');
+            } catch (error) {
+                this.logger?.error?.('Error closing replaced session socket:', error);
+            }
+        }
+    }
+
+    release(socket) {
+        const sessionId = socket?.__redwebSessionId;
+        if (!sessionId) return false;
+        const record = this.sessions.get(sessionId);
+        socket.__redwebSessionId = undefined;
+        if (socket.context) socket.context.session = null;
+        if (!record || record.socket !== socket) return false;
+        record.socket = null;
+        record.expiresAt = this.clock() + this.ttlMs;
+        return true;
+    }
+
+    remove(sessionId) {
+        this.validateId(sessionId);
+        if (this.closed) return false;
+        const record = this.sessions.get(sessionId);
+        if (!record) return false;
+        if (record.socket) {
+            record.socket.__redwebSessionId = undefined;
+            if (record.socket.context) record.socket.context.session = null;
+        }
+        return this.sessions.delete(sessionId);
+    }
+
+    get(sessionId) {
+        this.validateId(sessionId);
+        if (this.closed) return undefined;
+        return this.sessions.get(sessionId)?.data;
+    }
+
+    sweep() {
+        const now = this.clock();
+        this.sessions.forEach((record, sessionId) => {
+            if (!record.socket && record.expiresAt <= now) this.sessions.delete(sessionId);
+        });
+    }
+
+    stop() {
+        if (this.closed) return;
+        this.closed = true;
+        if (this.timer) clearInterval(this.timer);
+        this.timer = null;
+        this.sessions.forEach(record => {
+            if (record.socket) {
+                record.socket.__redwebSessionId = undefined;
+                if (record.socket.context) record.socket.context.session = null;
+            }
+        });
+        this.sessions.clear();
+    }
+
+    get size() {
+        return this.sessions.size;
+    }
+}
+
+module.exports = SessionRegistry;