redweb 0.14.0 → 0.16.0

package/docs/topics.json

@@ -12,7 +12,8 @@
   { "id": "runtime-diagnostics", "title": "Understand runtime failures before retrying", "summary": "Safe authentication, authorization, validation and application errors, with actual retry and cancellation guarantees.", "source": "docs/RUNTIME_DIAGNOSTICS.md" },
   { "id": "agent-access", "title": "Optional read-only agent documentation access", "summary": "Configure local MCP search and exact recipe retrieval without adding dependencies to Redweb servers.", "source": "docs/AGENT_ACCESS.md" },
   { "id": "live-html", "title": "Pages, components, state, actions, and CSS", "summary": "Server-side TSX, automatic updates, keyed lists, lifecycle, and static export.", "source": "docs/LIVE_HTML.md" },
-  { "id": "socket-contracts", "title": "Typed socket routes and handlers", "summary": "Shared validation, client/server types, protocol errors, and join/move/resume.", "source": "docs/SOCKET_CONTRACTS.md" },
+  { "id": "socket-contracts", "title": "Typed socket routes and handlers", "summary": "Shared validation, client/server types, protocol errors, and join/move/resume.", "source": "docs/SOCKET_CONTRACTS.md" },
+  { "id": "socket-pages", "title": "Server-side TSX for custom socket routes", "summary": "Typed handler bindings, private page state and one generated client connection without handwritten browser glue.", "source": "docs/SOCKET_PAGES.md" },
   { "id": "room-authorization", "title": "Private rooms and shared request identity", "summary": "Explicit entry policies, bounded authorization, trusted context, publication and revocation.", "source": "docs/ROOM_AUTHORIZATION.md" },
   { "id": "operations", "title": "Deploy and operate socket services", "summary": "Readiness, shutdown, capacity, reconnection, and distributed boundaries.", "source": "docs/MULTIPLAYER_OPERATIONS.md" },
   { "id": "production-contract", "title": "Production guarantees and limits", "summary": "Resource ownership, delivery semantics, compatibility, and release gates.", "source": "docs/PRODUCTION_READINESS.md" },

package/index.d.ts

@@ -35,7 +35,9 @@ declare module 'redweb' {
         isAssigned: boolean;
         sendJson(data: unknown): boolean;
         broadcast(data: unknown): number;
-        context?: RedWebConnectionContext;
+        context?: RedWebConnectionContext;
+        /** Present on an attached page connection; checks the actual page class and connection lifetime. */
+        page?<Page extends object>(PageClass: new () => Page): Page;
         joinRoom?(roomId: string): boolean;
         /** Bounded permission check followed by atomic membership insertion. */
         enterRoom?(roomId: string): Promise<boolean>;
@@ -49,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;
@@ -282,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>;
@@ -412,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;
@@ -554,7 +603,9 @@ declare module 'redweb' {
         dispose(): Promise<boolean>;
     }
 
-    export type PageOptions = {
+    export type PageOptions = {
+        /** Use a registered custom route for this private live page's typed TSX commands and rendering. */
+        socket?: new () => SocketRoute;
         template?: string;
         css?: string | readonly string[];
         live?: boolean;

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.14.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",
@@ -159,10 +159,13 @@
     "@types/ws": "^8.18.1",
     "cors": "^2.8.5",
     "express": "^4.22.2",
-    "redweb-client": "^0.2.0",
+    "redweb-client": "^0.3.0",
     "ws": "^8.21.3"
   },
-  "devDependencies": {
+  "overrides": {
+    "express": { "qs": "6.16.0" }
+  },
+  "devDependencies": {
     "@types/jest": "^29.5.12",
     "c8": "^10.1.3",
     "expect": "29.7.0",

package/recipes/shared/README.md

@@ -40,3 +40,10 @@ and application-specific rate limits. These starters are demonstrations, not a h
 Never commit secrets; `.env` is ignored but is not loaded automatically.
 
 `npx --no-install redweb doctor --json` reports configuration problems without changing your files.
+## Dependency security
+
+This starter includes an application-root npm override for Express 4's `qs`
+dependency, selecting patched `qs@6.16.0`. Keep the override when merging this
+starter into an existing application, refresh its lockfile and run `npm audit`.
+Overrides in Redweb's own package do not apply to installed consumers. Recheck
+upstream Express/body-parser releases before removing this temporary mitigation.

package/src/cli/templates.js

@@ -8,7 +8,7 @@ const TEMPLATES = Object.freeze(['realtime', 'chat', 'site', 'socket', 'dashboar
 
 function projectFiles(version, template = 'realtime', root = path.resolve(__dirname, '../..')) {
     if (!TEMPLATES.includes(template)) throw new Error('Unknown starter template.');
-    const { devDependencies, dependencies } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    const { devDependencies, dependencies, overrides } = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
     const read = relative => fs.readFileSync(path.join(root, 'recipes', relative), 'utf8');
     const manifest = {
         name: 'redweb-app', private: true, version: '0.0.0',
@@ -24,7 +24,8 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             ...(['chat', 'socket', 'dashboard'].includes(template) ? { zod: devDependencies.zod } : {}),
             ...(template === 'dashboard' ? { express: dependencies.express } : {}),
         },
-        devDependencies: {
+        overrides,
+        devDependencies: {
             typescript: devDependencies.typescript, nodemon: devDependencies.nodemon, ws: dependencies.ws, c8: devDependencies.c8,
             ...(template === 'dashboard' ? {
                 '@types/node': devDependencies['redweb-dashboard-types'].replace('npm:@types/node@', ''),

package/src/htmx/Jsx.js

@@ -83,13 +83,13 @@ function renderComponent(Component, properties) {
 
 function createElement(type, properties, key) {
     const reactive = ReactiveRenderer.jsx();
-    const props = properties == null ? {} : properties;
+    const props = properties == null ? {} : properties;
     if (!props || typeof props !== 'object' || Array.isArray(props)) {
         throw new TypeError('JSX properties must be an object.');
     }
     let result;
     if (type === Fragment) result = trustedHtml(renderChild(props.children));
-    else if (typeof type === 'string') result = renderIntrinsic(type, props);
+    else if (typeof type === 'string') result = renderIntrinsic(type, require('./SocketAction').attributes(props));
     else if (typeof type === 'function') result = renderComponent(type, props);
     else throw new TypeError('JSX element types must be intrinsic names or function components.');
     const elementKey = key ?? props.key;

package/src/htmx/LiveHtmlServer.js

@@ -71,7 +71,7 @@ class LiveHtmlServer {
             if (this.manager.hasLivePages || socketRoutes.length) {
                 this.sockets = new SocketServer({
                     server: this.http.server,
-                    routes: [...(this.manager.hasLivePages ? [this.manager.route()] : []), ...socketRoutes],
+                    routes: [...(this.manager.hasLivePages ? [this.manager.route()] : []), ...require('./PageSocketRoute').bindRoutes(this.manager, socketRoutes)],
                     listen,
                     port: this.http.port,
                     bind: this.http.bind,

package/src/htmx/PageManager.js

@@ -265,8 +265,10 @@ class PageManager {
                 if (!isHtml(result)) throw new TypeError('Page layouts must return html.');
                 return renderValue(result);
             };
-            const withContext = callback => LivePage.withRenderContext(context, callback);
-            const markup = await lifetime.wait(() => renderer ? renderer.initialize(render, withContext) : withContext(render));
+            const withContext = callback => require('./SocketAction').withRoute(record.socketHandlers,
+                () => LivePage.withRenderContext(context, callback));
+            const markup = await lifetime.wait(() => renderer ? renderer.initialize(render, withContext) : withContext(render));
+            if (record.metadata.socket && !renderer.enabled) throw new TypeError('Socket-bound pages must render TSX.');
             const document = this.createDocument(record, request);
             if (record.metadata.live === false) {
                 const result = document(markup, null);
@@ -277,7 +279,7 @@ class PageManager {
             session.renderLifetime = renderer;
             const config = {
                 pageId: session.id,
-                socketPath: this.paths.socket,
+                socketPath: record.socketPath || this.paths.socket,
                 runtimePath: this.paths.runtime,
                 version: PROTOCOL_VERSION,
             };
@@ -322,7 +324,7 @@ class PageManager {
         session.timer.unref?.();
     }
 
-    async authenticate(request) {
+    async authenticate(request, RouteClass) {
         let id;
         try {
             id = new URL(request.url, `http://${request.headers.host || 'localhost'}`).searchParams.get('pageId');
@@ -330,8 +332,9 @@ class PageManager {
             return false;
         }
         if (typeof id !== 'string' || id.length > 128) return false;
-        const session = this.pending.get(id) || this.active.get(id);
-        if (!session || session.socket || session.detaching) return false;
+        const session = this.pending.get(id) || this.active.get(id);
+        if (!session || session.socket || session.detaching) return false;
+        if (session.record?.metadata.socket !== RouteClass) return false;
         try {
             const principal = await this.identity.resolve(request, session.lifetime.signal);
             if (!Object.is(principal, session.principal)) return false;
@@ -385,7 +388,7 @@ class PageManager {
     connectionContext(session, socket) { return Object.freeze({ ...session.context, socket, signal: session.connection.signal, principal: session.principal }); }
 
     checkConnected(session, socket) {
-        if (!this.available(session) || session.socket !== socket) throw new AccessDenied('ACCESS_CANCELLED');
+        if (!this.available(session) || session.socket !== socket || (socket.readyState !== undefined && socket.readyState !== 1)) throw new AccessDenied('ACCESS_CANCELLED');
         session.connection.check();
     }
 

package/src/htmx/PageSocketRoute.js

@@ -0,0 +1,132 @@
+'use strict';
+
+const { AdmissionPolicy, ADMISSION_CONTEXT } = require('../ws/AdmissionPolicy');
+const { AccessDenied } = require('../access/AccessPolicy');
+const TransportPolicy = require('../ws/TransportPolicy');
+const { guards } = require('../ws/HandlerGuard');
+const { scheduleStartupCleanup } = require('../StartupCleanup');
+
+/** Adds page ownership to a route without replacing its admission, handlers or transport. */
+function bindRoute(manager, RouteClass, records) {
+    const sessions = new WeakMap();
+    const ready = new WeakMap();
+    return class PageSocketRoute extends RouteClass {
+        constructor() {
+            super();
+            try {
+                if (!this.protocolPolicy?.versions.includes('1') || this.protocolPolicy.queryParameter !== 'redwebVersion') {
+                    throw new TypeError('Page socket routes must support protocol version 1 and the default version query parameter.');
+                }
+                if (this.handlers.some(handler => handler.name.startsWith('redweb:'))) throw new TypeError('Page socket routes reserve redweb:* message types.');
+                if (!this.allowDuplicateConnections) throw new TypeError('Page socket routes require allowDuplicateConnections: true for independent browser tabs.');
+                this.transportPolicy = new TransportPolicy(this.transportPolicy || {}, true);
+                this.runtime.inFlight ||= new Set();
+                this.inFlight = this.runtime.inFlight;
+                for (const handler of this.handlers) {
+                    const initial = handler.onInitialContact;
+                    handler.onInitialContact = async (socket, request) => {
+                        await ready.get(socket).promise;
+                        if (socket.context.signal.aborted) throw new AccessDenied('ACCESS_CANCELLED');
+                        return initial?.call(handler, socket, request);
+                    };
+                }
+                this.pageAdmission = new AdmissionPolicy({
+                    origins: (origin, request) => manager.acceptsOrigin(origin, request),
+                    authenticate: async request => {
+                        const session = await manager.authenticate(request, RouteClass);
+                        if (!session) return false;
+                        sessions.set(request, session);
+                        return request[ADMISSION_CONTEXT]?.principal ?? true;
+                    },
+                });
+                for (const record of records) {
+                    record.socketPath = this.path;
+                    record.socketHandlers = new Set(this.handlers.map(handler => handler.constructor));
+                }
+            } catch (error) {
+                throw scheduleStartupCleanup(error, () => this.shutdown());
+            }
+        }
+
+        handleConnection(socket, request) {
+            let resolve, reject;
+            const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+            promise.catch(() => {});
+            ready.set(socket, { promise, resolve, reject });
+            return super.handleConnection(socket, request);
+        }
+
+        async authorizeUpgrade(request, rawSocket, signal) {
+            if (!await super.authorizeUpgrade(request, rawSocket, signal)) return false;
+            if (!new URL(request.url, 'http://localhost').searchParams.has('pageId')) return true;
+            return this.pageAdmission.authorize(request, rawSocket, this, signal);
+        }
+
+        async connectionOpenCallback(socket, request) {
+            try {
+                const session = sessions.get(request);
+                if (session) {
+                    Object.defineProperty(socket, 'page', { value: PageClass => {
+                        manager.checkConnected(session, socket);
+                        if (!(session.page instanceof PageClass)) throw new TypeError('This connection does not own the requested page.');
+                        return session.page;
+                    } });
+                    guards.set(socket, () => manager.authorize(session, socket));
+                    session.renderer.authorize = () => manager.authorize(session, socket);
+                    await manager.connect(session, socket);
+                }
+                await super.connectionOpenCallback(socket, request);
+                ready.get(socket).resolve();
+            } catch (error) { ready.get(socket).reject(error); throw error; }
+        }
+
+        async handleMessage(socket, message) {
+            try {
+                await ready.get(socket).promise;
+                const session = socket.__redwebPageSession;
+                if (!session) return super.handleMessage(socket, message);
+                await manager.authorize(session, socket);
+                // Only the bound route's registered commands are accepted. Live action/state
+                // envelopes cannot bypass its handlers or mutate page fields.
+                const accepted = await super.handleMessage(socket, message);
+                if (accepted && message.requestId !== undefined) {
+                    manager.checkConnected(session, socket);
+                    socket.sendEvent('redweb:result', null, { requestId: message.requestId });
+                }
+                return accepted;
+            } catch (error) {
+                if (!(error instanceof AccessDenied)) throw error;
+                this.sendAccessFailure(socket, error, { requestId: message?.requestId });
+                return false;
+            }
+        }
+
+        async connectionCloseCallback(socket) {
+            // Keep the weak guard: validators already in flight must still fail after close.
+            try { await manager.disconnect(socket); }
+            finally { await super.connectionCloseCallback?.(socket); }
+        }
+
+        async handleBinaryMessage(socket, buffer) {
+            await ready.get(socket).promise;
+            if (socket.__redwebPageSession) {
+                socket.close(1008, 'Page sockets accept JSON commands only');
+                return false;
+            }
+            return super.handleBinaryMessage(socket, buffer);
+        }
+    };
+}
+
+function bindRoutes(manager, RouteClasses) {
+    const attached = [...manager.records.values()].filter(record => record.metadata.socket);
+    for (const record of attached) {
+        if (!RouteClasses.includes(record.metadata.socket)) throw new TypeError('Every page socket route must be registered in the application.');
+    }
+    return RouteClasses.map(RouteClass => {
+        const records = attached.filter(record => record.metadata.socket === RouteClass);
+        return records.length ? bindRoute(manager, RouteClass, records) : RouteClass;
+    });
+}
+
+module.exports = { bindRoutes };

package/src/htmx/ReactiveRenderer.js

@@ -222,8 +222,14 @@ class ReactiveRenderer {
             const node = this.nodes.get(ownerId(payload.component));
             return node && [...node.html.matchAll(/\b(?:data-rw-state|rw-bind)\s*=\s*["']([^"']+)["']/g)].some(match => match[1] === payload.name);
         });
-        if (!this.disposed && generation === this.generation && socket && (patches.length || explicit.length)) {
-            socket.sendEvent('redweb:patch', { patches, states: explicit });
+        if (!this.disposed && generation === this.generation && socket && (patches.length || explicit.length)) {
+            try { if (this.authorize) await this.authorize(); }
+            catch (error) {
+                if (this.disposed || generation !== this.generation) return;
+                throw error;
+            }
+            if (this.disposed || generation !== this.generation) return;
+            socket.sendEvent('redweb:patch', { patches, states: explicit });
         }
     }
 

package/src/htmx/SocketAction.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const { AsyncLocalStorage } = require('async_hooks');
+const { bindings } = require('../ws/SocketAction');
+const routes = new AsyncLocalStorage();
+
+function attributes(properties) {
+    let result = properties;
+    for (const name of ['rw-click', 'rw-submit']) {
+        const binding = bindings.get(properties[name]);
+        if (!binding) continue;
+        if (!routes.getStore()?.has(binding.Handler)) throw new TypeError('Socket action handler must belong to this page socket route.');
+        if (Object.keys(result).some(key => key.toLowerCase() === 'data-rw-command')) throw new TypeError('Only one socket action may bind a control.');
+        result = { ...result, [name]: binding.type, 'data-rw-command': JSON.stringify({ type: binding.type, payload: binding.payload }) };
+    }
+    return result;
+}
+
+module.exports = { attributes, withRoute: (handlers, render) => routes.run(handlers, render) };

package/src/htmx/metadata.js

@@ -178,7 +178,10 @@ function page(routePath, options = {}) {
     if (!['connection', 'shared'].includes(scope)) {
         throw new TypeError('Page scope must be "connection" or "shared".');
     }
-    if (typeof live !== 'boolean') throw new TypeError('Page live must be a boolean.');
+    if (typeof live !== 'boolean') throw new TypeError('Page live must be a boolean.');
+    if (options.socket !== undefined && (typeof options.socket !== 'function' || !live || scope !== 'connection')) {
+        throw new TypeError('Page socket requires a route class and a live connection-scoped page.');
+    }
     if (layout !== undefined && typeof layout !== 'function') throw new TypeError('Page layout must be a function.');
     const head = pageHead(options.head);
     const cache = pageCache(options.cache, live);
@@ -189,7 +192,8 @@ function page(routePath, options = {}) {
         PAGE_METADATA.set(PageClass, Object.freeze({
             path: routePath,
             template,
-            scope,
+            scope,
+            ...(options.socket && { socket: options.socket }),
             ...(live === false && { live: false }),
             ...(head && { head }),
             ...(cache && { cache }),

package/src/ws/BaseHandler.js

@@ -20,10 +20,12 @@ class BaseHandler {
      */
     async handleMessage(socket, message) {
         const validationResult = await this.validateMessage(message, socket);
-        if (validationResult === false) {
-            throw new Error('Invalid message');
-        }
-        return this.onMessage(socket, message);
+        if (validationResult === false) {
+            throw new Error('Invalid message');
+        }
+        const guard = require('./HandlerGuard').guards.get(socket);
+        if (guard) await guard();
+        return this.onMessage(socket, message);
     }
 
     validateMessage() {