redweb 0.15.0 → 0.16.0

package/index.d.ts

@@ -51,13 +51,57 @@ declare module 'redweb' {
         sendBinaryEvent?(value: unknown): Promise<boolean>;
     };
 
-    export interface RedWebConnectionContext extends RequestContext {
+    export interface RedWebConnectionContext extends RequestContext {
         readonly connectionId: string;
         readonly principal: unknown;
         session: unknown | null;
         metadata: Record<string, unknown>;
         readonly protocol?: Readonly<{ version: string }>;
-    }
+    }
+
+    /** A deliberate, safe command rejection, unlike an unexpected application error. */
+    export class ClientError extends Error { constructor(message: string); }
+    export interface ClientEvent { type: string; payload: unknown; }
+    export interface ConnectedClientsOptions<Page extends object, Identity> {
+        /** Must still equal the admitted principal. Returning another identity never transfers a connection. */
+        identity(context: RedWebConnectionContext): Identity | undefined | false | Promise<Identity | undefined | false>;
+        page(): new () => Page;
+        project(client: ConnectedClient<Page, Identity>, room: string, online: readonly Identity[]): Partial<Page> | Promise<Partial<Page>>;
+        authorizationTimeoutMs?: number;
+        projectionTimeoutMs?: number;
+        /** Explicitly classify domain errors safe to display; all other failures remain private. */
+        reject?(error: unknown): string | undefined;
+        errorState?(message: string): Partial<Page>;
+        /** Optional non-HTML client support. Redweb performs the final checked send. */
+        raw?: {
+            update(state: Partial<Page>): ClientEvent | Promise<ClientEvent>;
+            reject?(message: string): ClientEvent | Promise<ClientEvent>;
+        };
+    }
+    export class ConnectedClient<Page extends object, Identity = unknown> {
+        private constructor();
+        readonly socket: RedWebSocket;
+        readonly identity: Identity;
+        readonly page: Page;
+        readonly rooms: readonly string[];
+        /** Requires exactly one current room; use rooms for multi-room applications. */
+        readonly room: string;
+        /** Reserve room capacity, run a synchronous domain commit, and roll back new membership if it rejects. */
+        join(room: string, commit?: () => unknown): Promise<void>;
+        leave(room: string): boolean;
+    }
+    export class ConnectedClients<Page extends object, Identity = unknown> {
+        constructor(options: ConnectedClientsOptions<Page, Identity>);
+        get(socket: RedWebSocket): ConnectedClient<Page, Identity>;
+        refresh(room: string): Promise<unknown>;
+        bind<Schemas extends import('redweb/contract').SocketSchemas>(contract: import('redweb/contract').SocketContract<Schemas>): {
+            readonly protocol: { readonly versions: readonly string[] };
+            handler<Type extends keyof Schemas & string>(type: Type, callback: (
+                client: ConnectedClient<Page, Identity>, payload: import('redweb/contract').ContractOutput<Schemas[Type]>,
+            ) => unknown): import('redweb/contract').SocketHandler<import('redweb/contract').ContractInput<Schemas[Type]>>;
+        };
+    }
+    export function connectedClients<Page extends object, Identity>(options: ConnectedClientsOptions<Page, Identity>): ConnectedClients<Page, Identity>;
 
     export interface AdmissionContext {
         signal: AbortSignal;
@@ -284,7 +328,9 @@ declare module 'redweb' {
 
     /** ─────────────────── ROUTES & HANDLERS ─────────────────── */
 
-    export interface SocketRouteConfig {
+    export interface SocketRouteConfig {
+        /** Opt-in server-side clients, with RoomRegistry membership and private page projection. */
+        connections?: ConnectedClients<any, any>;
         path: string;
         handlers: Array<new () => BaseHandler>;
         services?: Array<new () => SocketService>;
@@ -414,7 +460,8 @@ declare module 'redweb' {
         enter(roomId: string, socket: RedWebSocket): Promise<boolean>;
         leave(roomId: string, socket: RedWebSocket): boolean;
         leaveAll(socket: RedWebSocket): number;
-        members(roomId: string): RedWebSocket[];
+        members(roomId: string): RedWebSocket[];
+        roomsFor(socket: RedWebSocket): string[];
         has(roomId: string, socket: RedWebSocket): boolean;
         broadcast(roomId: string, data: unknown, options?: { except?: RedWebSocket }): number;
         broadcastFrom(socket: RedWebSocket, roomId: string, data: unknown, options?: { except?: RedWebSocket }): number;

package/index.js

@@ -15,13 +15,18 @@ const {
 } = require('./src/ws');
 const { BaseHandler } = require('./src/ws/BaseHandler');
 const { defineSocketContract } = require('./contract');
-const { Application, defineApp } = require('./src/Application');
+const { Application, defineApp } = require('./src/Application');
+const { connectedClients, ConnectedClients, ConnectedClient, ClientError } = require('./src/ws/ConnectedClients');
 const HttpServer = require('./src/http/HttpServer');
 const HttpsServer = require('./src/http/HttpsServer');
 const { action, attribute, codeBlock, component, defineSite, each, exportStatic, html, HtmlRenderer, LiveHtmlServer, LivePage, page, start, state, url, view } = require('./src/htmx');
 module.exports = {
     Application,
-    defineApp,
+    defineApp,
+    connectedClients,
+    ConnectedClients,
+    ConnectedClient,
+    ClientError,
     HttpServer,
     HttpsServer,
     BaseHttpServer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "redweb",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "A small Node.js foundation for HTTP, WebSockets, multiplayer services, and server-rendered HTML",
   "main": "index.js",
   "types": "index.d.ts",

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/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/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();