redweb 0.14.0 → 0.16.0

package/src/ws/ConnectedClients.js

@@ -0,0 +1,207 @@
+'use strict';
+
+const { AccessPolicy, AccessDenied } = require('../access/AccessPolicy');
+const { guards } = require('./HandlerGuard');
+const { BoundedOperation } = require('../async/BoundedOperation');
+
+/** Deliberately public rejection text; unexpected exceptions remain private. */
+class ClientError extends Error {
+    constructor(message) {
+        if (typeof message !== 'string' || !message || message.length > 512) throw new TypeError('Client error text must contain 1–512 characters.');
+        super(message);
+    }
+}
+
+class ConnectedClient {
+    #owner;
+    constructor(owner, socket) {
+        this.#owner = owner;
+        Object.defineProperty(this, 'socket', { value: socket });
+        Object.freeze(this);
+    }
+    get identity() { this.#owner.assertActive(this.socket); return this.socket.context.principal; }
+    get rooms() { return this.#owner.rooms.roomsFor(this.socket); }
+    get room() {
+        const rooms = this.rooms;
+        if (rooms.length !== 1) throw new ClientError('Join a room first.');
+        return rooms[0];
+    }
+    get page() { this.#owner.assertActive(this.socket); return this.socket.page(this.#owner.options.page()); }
+    join(room, commit) { return this.#owner.join(this, room, commit); }
+    leave(room) { this.#owner.assertActive(this.socket); return this.#owner.rooms.leave(room, this.socket); }
+}
+
+/** One route-owned projection layer; RoomRegistry alone owns membership. */
+class ConnectedClients {
+    #route;
+    #clients = new WeakMap();
+    #joining = new WeakSet();
+    #queued = new Set();
+    #generations = new Map();
+
+    constructor(options) {
+        if (!options || typeof options !== 'object') throw new TypeError('Connected clients require options.');
+        for (const name of ['identity', 'page', 'project']) {
+            if (typeof options[name] !== 'function') throw new TypeError(`Connected clients require ${name}.`);
+        }
+        for (const name of ['reject', 'errorState']) {
+            if (options[name] !== undefined && typeof options[name] !== 'function') throw new TypeError(`${name} must be a function.`);
+        }
+        if (options.raw !== undefined && (!options.raw || typeof options.raw.update !== 'function' ||
+            (options.raw.reject !== undefined && typeof options.raw.reject !== 'function'))) {
+            throw new TypeError('A raw adapter requires update and an optional reject callback.');
+        }
+        this.options = Object.freeze({ ...options, raw: options.raw && Object.freeze({ ...options.raw }) });
+        this.policy = new AccessPolicy(async context => {
+            const identity = await this.options.identity(context);
+            return identity !== undefined && identity !== null && identity !== false && Object.is(identity, context.principal);
+        }, options.authorizationTimeoutMs);
+        this.projection = new BoundedOperation(options.projectionTimeoutMs);
+    }
+
+    attach(route, rooms) {
+        if (this.#route) throw new TypeError('Connected clients belong to one route instance. Create them inside your application factory.');
+        if (!rooms || !route.protocolPolicy) throw new TypeError('Connected clients require rooms and a socket protocol.');
+        this.#route = route;
+        this.rooms = rooms;
+    }
+
+    assertActive(socket) {
+        if (!this.#route || this.#route.draining || this.#route.clients.get(socket.clientKey) !== socket ||
+            socket.readyState !== 1 || socket.context.signal.aborted) throw new AccessDenied('ACCESS_CANCELLED');
+    }
+
+    get(socket) {
+        this.assertActive(socket);
+        let client = this.#clients.get(socket);
+        if (!client) { client = new ConnectedClient(this, socket); this.#clients.set(socket, client); }
+        return client;
+    }
+
+    async check(socket) {
+        this.assertActive(socket);
+        await this.policy.check(socket.context);
+        const guard = guards.get(socket);
+        if (guard) await guard();
+        this.assertActive(socket);
+        if (!socket.page && !this.options.raw) throw new AccessDenied();
+    }
+
+    async join(client, room, commit = () => {}) {
+        const socket = client.socket;
+        if (typeof commit !== 'function') throw new TypeError('Room commit must be synchronous.');
+        if (this.#joining.has(socket)) throw new ClientError('A room join is already pending.');
+        const existing = this.rooms.has(room, socket);
+        this.#joining.add(socket);
+        try {
+            await this.check(socket);
+            if (!await this.rooms.enter(room, socket)) throw new ClientError('Room capacity or access denied.');
+            await this.check(socket);
+            if (!this.rooms.has(room, socket)) throw new AccessDenied('ACCESS_CANCELLED');
+            const result = commit();
+            if (result && typeof result.then === 'function') {
+                Promise.resolve(result).catch(() => {});
+                throw new TypeError('Room commit must be synchronous.');
+            }
+        } catch (error) {
+            if (!existing) this.rooms.leave(room, socket);
+            throw error;
+        } finally { this.#joining.delete(socket); this.changed(room); }
+    }
+
+    changed(room) {
+        if (this.#route.draining) return;
+        this.#generations.set(room, Symbol());
+        if (this.#queued.has(room)) return;
+        this.#queued.add(room);
+        queueMicrotask(() => {
+            if (!this.#queued.delete(room)) return;
+            void this.refresh(room).catch(error => this.#route.logger.error('Connected client refresh failed:', error));
+        });
+    }
+
+    refresh(room) {
+        this.rooms.validateRoomId(room);
+        this.#queued.delete(room);
+        return this.#route.runtime.run(() => this.project(room));
+    }
+
+    async project(room) {
+        const generation = Symbol();
+        this.#generations.set(room, generation);
+        const current = socket => this.#generations.get(room) === generation && this.rooms.has(room, socket) && !this.#joining.has(socket);
+        const eligible = [];
+        try {
+            await Promise.all(this.rooms.members(room).map(async socket => {
+                if (!current(socket)) return;
+                try {
+                    await this.check(socket);
+                    if (current(socket)) { const client = this.get(socket); eligible.push({ client, identity: client.identity }); }
+                }
+                catch (error) { if (current(socket)) this.exclude(socket, error); }
+            }));
+            const online = Object.freeze([...new Set(eligible.map(entry => entry.identity))]);
+            await Promise.all(eligible.map(async ({ client }) => {
+                const socket = client.socket;
+                try {
+                    if (!current(socket)) return;
+                    const { state, frame } = await this.projection.run(async () => {
+                        const state = await this.options.project(client, room, online);
+                        const frame = socket.page ? null : await this.options.raw.update(state);
+                        return { state, frame };
+                    }, socket.context.signal);
+                    await this.check(socket);
+                    if (!current(socket)) return;
+                    if (socket.page) Object.assign(client.page, state);
+                    else socket.sendEvent(frame.type, frame.payload);
+                } catch (error) { if (current(socket)) this.exclude(socket, error); }
+            }));
+        } finally {
+            if (this.#generations.get(room) === generation) this.#generations.delete(room);
+        }
+    }
+
+    exclude(socket, error) {
+        this.rooms.leaveAll(socket);
+        if (!(error instanceof AccessDenied)) this.#route.handleError(socket, error);
+        socket.close(error instanceof AccessDenied ? 1008 : 1011, 'Connection unavailable.');
+    }
+
+    bind(contract) {
+        return Object.freeze({
+            protocol: contract.protocol,
+            handler: (type, callback) => {
+                if (typeof callback !== 'function') throw new TypeError('A client handler requires a callback.');
+                return contract.handler(type, async (socket, payload, message) => {
+                    const client = this.get(socket);
+                    await this.check(socket);
+                    try {
+                        const result = await callback(client, payload);
+                        if (result === false) return false;
+                        await Promise.all(client.rooms.map(room => this.refresh(room)));
+                        if (!socket.page && message.requestId !== undefined) {
+                            await this.check(socket);
+                            socket.sendEvent('redweb:result', null, { requestId: message.requestId });
+                        }
+                        return result;
+                    } catch (error) {
+                        const text = error instanceof ClientError ? error.message : this.options.reject?.(error);
+                        if (typeof text !== 'string' || !text || text.length > 512) throw error;
+                        const metadata = { requestId: message.requestId };
+                        const frame = socket.page || !this.options.raw.reject ? null :
+                            await this.projection.run(() => this.options.raw.reject(text), socket.context.signal);
+                        await this.check(socket);
+                        if (socket.page) {
+                            if (this.options.errorState) Object.assign(client.page, this.options.errorState(text));
+                        } else if (frame) socket.sendEvent(frame.type, frame.payload);
+                        socket.sendProtocolError('COMMAND_REJECTED', text, metadata);
+                        return false;
+                    }
+                });
+            },
+        });
+    }
+}
+
+const connectedClients = options => new ConnectedClients(options);
+module.exports = { connectedClients, ConnectedClients, ConnectedClient, ClientError };

package/src/ws/HandlerGuard.js

@@ -0,0 +1,4 @@
+'use strict';
+// A private hook, never a field supplied by an incoming message.
+const guards = new WeakMap();
+module.exports = { guards };

package/src/ws/RoomRegistry.js

@@ -102,10 +102,12 @@ class RoomRegistry {
         return roomIds.length;
     }
 
-    members(roomId) {
+    members(roomId) {
         this.validateRoomId(roomId);
         return [...(this.rooms.get(roomId) || [])];
-    }
+    }
+
+    roomsFor(socket) { return [...(this.memberships.get(socket) || [])]; }
 
     has(roomId, socket) {
         this.validateRoomId(roomId);

package/src/ws/RouteRuntime.js

@@ -5,7 +5,8 @@ const HeartbeatMonitor = require('./HeartbeatMonitor');
 const RoomRegistry = require('./RoomRegistry');
 const SessionRegistry = require('./SessionRegistry');
 const DistributionBridge = require('./DistributionBridge');
-const requestSnapshot = require('../context/RequestSnapshot');
+const requestSnapshot = require('../context/RequestSnapshot');
+const { ConnectedClients } = require('./ConnectedClients');
 
 function joinRoom(roomId) { return this.__redwebRuntimeOwner.rooms.join(roomId, this); }
 function enterRoom(roomId) { return this.__redwebRuntimeOwner.rooms.enter(roomId, this); }
@@ -23,7 +24,7 @@ function publishEvent(type, payload) { return this.__redwebRuntimeOwner.route.pu
 function connectionContext() { return this.__redwebRuntimeOwner.ensureContext(this); }
 
 class RouteRuntime {
-    constructor(route, { heartbeat, rooms, sessions, distribution, drainHandlers }) {
+    constructor(route, { heartbeat, rooms, sessions, distribution, drainHandlers, connections }) {
         this.route = route;
         this.inFlight = drainHandlers ? new Set() : null;
         this.abortController = drainHandlers ? new AbortController() : null;
@@ -31,7 +32,8 @@ class RouteRuntime {
         this.contexts = new WeakMap();
         this.requests = new WeakMap();
         this.needsContext = Boolean(route.admissionPolicy || route.protocolPolicy || rooms || sessions || drainHandlers);
-        try {
+        try {
+            if (connections !== undefined && !(connections instanceof ConnectedClients)) throw new TypeError('connections must be created with connectedClients().');
             this.heartbeat = heartbeat === undefined ? null : new HeartbeatMonitor(heartbeat, route.logger);
             this.rooms = rooms === undefined || rooms === false
                 ? null
@@ -40,9 +42,10 @@ class RouteRuntime {
                         socket.readyState === 1 && this.contexts.get(socket)?.active !== false,
                     contextFor: socket => this.ensureContext(socket),
                     policy: route.transportPolicy,
-                    onChange: action => {
+                    onChange: (action, roomId) => {
                         route.metrics?.increment(`redweb.room.${action}`);
-                        route.metrics?.gauge('redweb.rooms.active', this.rooms.size);
+                        route.metrics?.gauge('redweb.rooms.active', this.rooms.size);
+                        connections?.changed(roomId);
                     },
                 });
             this.sessions = sessions === undefined || sessions === false
@@ -51,9 +54,10 @@ class RouteRuntime {
             if (distribution !== undefined && distribution !== false && typeof distribution?.onEvent !== 'function') {
                 throw new TypeError('`distribution.onEvent` must be a function.');
             }
-            this.distribution = distribution === undefined || distribution === false
+            this.distribution = distribution === undefined || distribution === false
                 ? null
-                : new DistributionBridge(distribution, event => distribution.onEvent(event, route), route.logger);
+                : new DistributionBridge(distribution, event => distribution.onEvent(event, route), route.logger);
+            connections?.attach(route, this.rooms);
         } catch (error) {
             this.heartbeat?.stop();
             this.sessions?.stop();

package/src/ws/SocketAction.js

@@ -0,0 +1,16 @@
+'use strict';
+
+// Browser-safe metadata keeps the standalone contract entry free of Node rendering dependencies.
+const bindings = new WeakMap();
+function register(Handler, type) {
+    bindings.set(Handler, { Handler, type });
+    Object.defineProperty(Handler, 'with', { value(payload) {
+        const serialized = JSON.stringify(payload);
+        if (serialized === undefined || serialized.length > 65536) throw new TypeError('Socket action payload must be bounded JSON.');
+        const binding = Object.freeze({});
+        bindings.set(binding, { Handler, type, payload: JSON.parse(serialized) });
+        return binding;
+    } });
+    return Handler;
+}
+module.exports = { register, bindings };

package/src/ws/SocketContract.js

@@ -83,7 +83,7 @@ class SocketContract {
         if (!this.#validators.has(type)) throw new TypeError('Handler message type is not defined in the contract.');
         if (typeof callback !== 'function') throw new TypeError('A contract handler requires a callback.');
         const contract = this;
-        return class ContractHandler extends BaseHandler {
+        class ContractHandler extends BaseHandler {
             constructor() { super(type); }
             async handleMessage(socket, message) {
                 if (socket.context?.protocol?.version !== contract.version) throw new TypeError('The route must negotiate this contract version before handling messages.');
@@ -93,7 +93,8 @@ class SocketContract {
                 return super.handleMessage(socket, { ...message, payload });
             }
             onMessage(socket, message) { return callback(socket, message.payload, message); }
-        };
+        }
+        return require('./SocketAction').register(ContractHandler, type);
     }
 
     client(socket) { return new ContractClient(this, socket); }

package/src/ws/SocketRoute.js

@@ -93,11 +93,12 @@ class SocketRoute {
         limits,
         orderedMessages = false,
         heartbeat,
-        rooms,
+        connections,
+        rooms = connections ? true : undefined,
         sessions,
         metrics,
         distribution,
-        drainHandlers = false,
+        drainHandlers = Boolean(connections),
         protocol,
         maxPendingUpgrades = 64,
     } = {}) {
@@ -192,7 +193,7 @@ class SocketRoute {
             throw error;
         }
         try {
-            this.runtime = new RouteRuntime(this, { heartbeat, rooms, sessions, distribution, drainHandlers });
+            this.runtime = new RouteRuntime(this, { heartbeat, rooms, sessions, distribution, drainHandlers, connections });
             Object.assign(this, this.runtime.expose());
         } catch (error) {
             this.disposeServices();
@@ -452,8 +453,9 @@ class SocketRoute {
             return false;
         } else {
             try {
-                await handler.handleMessage(sock, data);
-                return true;
+                // A handler may send a recoverable protocol error and explicitly decline
+                // success. Undefined remains successful for existing command handlers.
+                return await handler.handleMessage(sock, data) !== false;
             } catch (error) {
                 if (this.sendAccessFailure(sock, error, { requestId: data.requestId })) return false;
                 if (error instanceof InboundContractValidationError) {