redweb 0.13.5 → 0.15.0

package/src/Application.js

@@ -0,0 +1,239 @@
+'use strict';
+
+const LiveHtmlServer = require('./htmx/LiveHtmlServer');
+const HttpServer = require('./http/HttpServer');
+const HttpsServer = require('./http/HttpsServer');
+const SocketServer = require('./ws/SocketServer');
+const SocketService = require('./ws/SocketService');
+const OwnedServerLifecycle = require('./OwnedServerLifecycle');
+const { validateListenerOptions } = require('./serverLifecycle');
+const { awaitStartupCleanup } = require('./StartupCleanup');
+const { performance } = require('node:perf_hooks');
+
+function classes(value, name) {
+    if (!Array.isArray(value) || value.some(Type => typeof Type !== 'function')) {
+        throw new TypeError(`\`${name}\` must be an array of classes.`);
+    }
+    return [...value];
+}
+
+function bounded(operation, milliseconds, label, signal) {
+    let timer, abort;
+    return Promise.race([
+        Promise.resolve().then(() => {
+            if (signal?.aborted) throw new Error('Application startup was cancelled.');
+            return operation();
+        }),
+        new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`${label} exceeded its deadline.`)), milliseconds); }),
+        new Promise((_, reject) => {
+            abort = () => reject(new Error('Application startup was cancelled.'));
+            signal?.addEventListener('abort', abort, { once: true });
+            if (signal?.aborted) abort();
+        }),
+    ]).finally(() => { clearTimeout(timer); signal?.removeEventListener('abort', abort); });
+}
+
+/** One deferred application definition, one listener and one cleanup owner. */
+class Application {
+    constructor(options = {}) {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Application options must be an object.');
+        const { pages = [], sockets = [], services = [], port = 8181, bind = '0.0.0.0',
+            startupTimeoutMs = 5000, shutdownTimeoutMs = 5000, signals = true, ...rest } = options;
+        if ('static' in rest) throw new TypeError('Use exportStatic() for static output; defineApp() owns a live HTTP listener.');
+        for (const name of ['listen', 'routes', 'socketRoutes', 'closeServerOnShutdown']) {
+            if (name in rest) throw new TypeError(`defineApp owns \`${name}\`; use pages/sockets and run().`);
+        }
+        validateListenerOptions({ port, bind, listen: false, listenCallback: rest.listenCallback });
+        for (const value of [startupTimeoutMs, shutdownTimeoutMs]) {
+            if (!Number.isInteger(value) || value < 1 || value > 2147483647) throw new RangeError('Application deadlines must be positive timer-safe integers.');
+        }
+        if (typeof signals !== 'boolean') throw new TypeError('`signals` must be a boolean.');
+        this.options = { ...rest, pages: classes(pages, 'pages'), sockets: classes(sockets, 'sockets'),
+            services: classes(services, 'services'), port, bind, startupTimeoutMs, shutdownTimeoutMs, signals };
+        if (this.options.services.some(Type => Type === SocketService || Type.prototype instanceof SocketService)) {
+            throw new TypeError('SocketService belongs to a socket route, not application services.');
+        }
+        this.services = [];
+        this.server = null;
+        this.app = null;
+        this.http = null;
+        this.sockets = null;
+        this._live = null;
+        this._owner = null;
+        this._runPromise = null;
+        this._shutdownPromise = null;
+        this._cleanupPromise = null;
+        this._stopping = false;
+        this._abort = new AbortController();
+        this._onSignal = () => this._stopProcess();
+        this._onClose = () => {
+            if (this._stopping) return;
+            if (this.options.signals) this._stopProcess();
+            else void this.shutdown().catch(() => {});
+        };
+        this._onError = () => {
+            if (this.options.signals) process.exitCode = 1;
+            this._onClose();
+        };
+    }
+
+    run() {
+        if (this._stopping) return Promise.reject(new Error('An application cannot run after shutdown. Define a new application.'));
+        if (this._runPromise) return this._runPromise;
+        this._startupDeadline = performance.now() + this.options.startupTimeoutMs;
+        this._runPromise = this._start().catch(async error => {
+            this._stopping = true;
+            this._abort.abort();
+            try {
+                const results = await Promise.allSettled([
+                    this._withinShutdown(() => awaitStartupCleanup(error), 'Construction rollback'), this._cleanup(),
+                ]);
+                const errors = results.filter(result => result.status === 'rejected').map(result => result.reason);
+                if (errors.length) throw new AggregateError(errors, 'Application rollback failed.');
+            }
+            catch (cleanup) { throw new AggregateError([error, cleanup], 'Application startup and cleanup failed.', { cause: error }); }
+            throw error;
+        });
+        return this._runPromise;
+    }
+
+    async _start() {
+        const { pages, sockets, services, startupTimeoutMs, shutdownTimeoutMs, signals, httpServices = [], ...options } = this.options;
+        if (signals) {
+            process.on('SIGINT', this._onSignal);
+            process.on('SIGTERM', this._onSignal);
+        }
+        const httpOptions = { ...options, services: httpServices, listen: false, shutdownTimeoutMs };
+        if (pages.length) {
+            this._live = new LiveHtmlServer({ ...httpOptions, pages, socketRoutes: sockets });
+            this.http = this._live.http;
+            this.sockets = this._live.sockets;
+            this._owner = this._live._ownedServer;
+        } else {
+            const Server = options.ssl ? HttpsServer : HttpServer;
+            this.http = new Server(httpOptions);
+            this._owner = new OwnedServerLifecycle(this.http.server);
+        }
+        this.server = this.http.server;
+        this.app = this.http.app;
+        if (!pages.length && sockets.length) {
+            this.sockets = new SocketServer({ server: this.server, routes: sockets, listen: false,
+                closeServerOnShutdown: false, logger: options.logger });
+        }
+        for (const Service of services) {
+            this._checkStarting();
+            const service = new Service();
+            this.services.push(service);
+            if (typeof service.onInit !== 'function' || typeof service.onShutdown !== 'function') {
+                throw new TypeError('Application services require onInit(app, signal) and onShutdown().');
+            }
+            await this._withinStartup(() => service.onInit(this, this._abort.signal), 'Application service initialization');
+        }
+        this._checkStarting();
+        await this._listen();
+        this._checkStarting();
+        this.server.on('error', this._onError);
+        this.server.once('close', this._onClose);
+        if (options.listenCallback) await this._withinStartup(() => options.listenCallback(), 'Application listening callback');
+        else this.http.logger?.log?.(`Redweb application listening on ${options.bind}:${this.server.address().port}`);
+        this._checkStarting();
+        return this;
+    }
+
+    _checkStarting() {
+        if (this._stopping) throw new Error('Application startup was cancelled.');
+    }
+
+    _listen() {
+        const { server } = this;
+        return this._withinStartup(() => new Promise((resolve, reject) => {
+            // A cancelled or timed-out native lookup can still complete on
+            // Node 18. Only native settlement detaches these one-shot guards.
+            const detach = () => { server.off('listening', ready); server.off('error', failed); };
+            const failed = error => { detach(); reject(error); };
+            const ready = () => {
+                try {
+                    if (this._abort.signal.aborted) server.close();
+                    detach();
+                    resolve();
+                } catch (error) { failed(error); }
+            };
+            server.once('listening', ready);
+            server.once('error', failed);
+            try { server.listen({ port: this.options.port, host: this.options.bind, signal: this._abort.signal }); }
+            catch (error) { failed(error); }
+        }), 'Application listener startup');
+    }
+
+    shutdown() {
+        if (!this._shutdownPromise) {
+            this._stopping = true;
+            this._deadline ??= performance.now() + this.options.shutdownTimeoutMs;
+            this._abort.abort();
+            this._shutdownPromise = Promise.resolve(this._runPromise).catch(() => {}).then(() => this._cleanup());
+        }
+        return this._shutdownPromise;
+    }
+
+    revoke(principal) { return this._live ? this._live.revoke(principal) : Promise.resolve(0); }
+
+    inspect() { return this._live ? this._live.inspect() : null; }
+
+    _stopProcess() {
+        if (this._processStopping) return;
+        this._processStopping = true;
+        const timer = setTimeout(() => { process.exitCode = 1; process.exit(); }, this.options.shutdownTimeoutMs);
+        void this.shutdown().then(() => clearTimeout(timer), () => { process.exitCode = 1; timer.unref(); });
+    }
+
+    _withinShutdown(operation, label) {
+        this._deadline ??= performance.now() + this.options.shutdownTimeoutMs;
+        return bounded(operation, Math.max(0, this._deadline - performance.now()), label);
+    }
+
+    _withinStartup(operation, label) {
+        const remaining = this._startupDeadline - performance.now();
+        if (remaining <= 0) return Promise.reject(new Error(`${label} exceeded its deadline.`));
+        return bounded(operation, remaining, label, this._abort.signal);
+    }
+
+    _cleanup() {
+        if (!this._cleanupPromise) this._cleanupPromise = this._dispose();
+        return this._cleanupPromise;
+    }
+
+    async _dispose() {
+        const errors = [];
+        const close = async (operation, label) => {
+            try { await this._withinShutdown(operation, label); } catch (error) { errors.push(error); }
+        };
+        // Drain handlers and close listeners before releasing their dependencies.
+        if (this.server?.listening) {
+            try { this.server.close(); } catch (error) { errors.push(error); }
+        }
+        if (this.sockets) await close(() => this.sockets.shutdown(), 'Socket shutdown');
+        if (this._live) await close(() => this._live.manager.shutdown(), 'Page shutdown');
+        if (this._owner) {
+            // OwnedServerLifecycle applies this same remaining deadline and
+            // force-closes peers when it expires. A second racing timer could
+            // report failure just before that successful force-close.
+            try { await this._owner.close(Math.max(0, this._deadline - performance.now()), () => this.http.shutdown()); }
+            catch (error) { errors.push(error); }
+            errors.push(...this._owner.forceClose());
+        }
+        for (const service of [...this.services].reverse()) {
+            await close(() => service.onShutdown(), 'Application service shutdown');
+        }
+        this.server?.off('error', this._onError);
+        this.server?.off('close', this._onClose);
+        if (!errors.length || !this._processStopping) {
+            process.off('SIGINT', this._onSignal);
+            process.off('SIGTERM', this._onSignal);
+        }
+        if (errors.length) throw new AggregateError(errors, 'Application shutdown failed.');
+    }
+}
+
+function defineApp(options) { return new Application(options); }
+
+module.exports = { Application, defineApp };

package/src/StartupCleanup.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const pending = new WeakMap();
+const { isNativeError } = require('node:util').types;
+
+/** Preserve synchronous constructor errors while letting async owners await rollback. */
+function scheduleStartupCleanup(error, cleanup) {
+    const failure = error instanceof Error || isNativeError(error) ? error : new Error('Application construction failed.', { cause: error });
+    const previous = pending.get(failure);
+    // Each partially constructed owner must start releasing its resources even
+    // when another owner's cleanup stalls. Retain every failure for the caller.
+    const rollback = Promise.allSettled([previous, Promise.resolve().then(cleanup)]).then(results => {
+        const errors = results.filter(result => result.status === 'rejected').map(result => result.reason);
+        if (errors.length) throw new AggregateError(errors, 'Construction rollback failed.');
+    });
+    pending.set(failure, rollback);
+    // Synchronous callers cannot await a constructor; async owners inspect the original task.
+    rollback.catch(() => {});
+    return failure;
+}
+
+function awaitStartupCleanup(error) { return pending.get(error); }
+
+module.exports = { scheduleStartupCleanup, awaitStartupCleanup };

package/src/cli/SourceInspector.js

@@ -108,6 +108,11 @@ class SourceInspector {
             this.group(args[0], 'page', node, args[1]);
         } else if (api === 'LiveHtmlServer') {
             this.group(read.property(args[0], 'pages'), 'page', node, args[0]);
+        } else if (['defineApp', 'Application'].includes(api)) {
+            for (const [field, kind] of [['pages', 'page'], ['sockets', 'route']]) {
+                const registrations = read.property(args[0], field);
+                if (registrations !== undefined) this.group(registrations, kind, node, args[0]);
+            }
         } else if (['SocketServer', 'SecureSocketServer'].includes(api)) {
             const routes = read.property(args[0], 'routes');
             if (routes !== undefined) this.group(routes, 'route', node);

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',
@@ -16,15 +16,16 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             build: 'tsc && node scripts/copy-assets.cjs',
             start: 'node dist/app.js',
             dev: 'nodemon',
-            test: 'npm run build && node --test test/app.test.cjs test/run-app.test.cjs',
-            'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/run-app.test.cjs',
+            test: 'npm run build && node --test test/app.test.cjs test/lifecycle.test.cjs',
+            'test:coverage': 'npm run build && c8 --all --src=dist --include=dist/** --reporter=text --reporter=json node --test test/app.test.cjs test/lifecycle.test.cjs',
         },
         dependencies: {
             redweb: `^${version}`,
             ...(['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@', ''),
@@ -52,12 +53,11 @@ function projectFiles(version, template = 'realtime', root = path.resolve(__dirn
             include: ['src/**/*.ts', 'src/**/*.tsx'],
         }) },
         { path: 'src/app.tsx', content: read(`${template}/app.tsx`) },
-        { path: 'src/run-app.ts', content: read('shared/run-app.ts') },
         { path: 'src/app.css', content: read(`${template === 'dashboard' ? template : 'shared'}/app.css`) },
         { path: 'scripts/copy-assets.cjs', content: read('shared/copy-assets.cjs') },
         { path: 'test/network.cjs', content: read('shared/network.cjs') },
         { path: 'test/app.test.cjs', content: read(`${template}/app.test.cjs`) },
-        { path: 'test/run-app.test.cjs', content: read('shared/run-app.test.cjs') },
+        { path: 'test/lifecycle.test.cjs', content: read('shared/lifecycle.test.cjs') },
         { path: 'README.md', content: `${read('shared/README.md')}\n${read(`${template}/README.md`)}` },
         { path: '.gitignore', content: 'node_modules/\ndist/\ncoverage/\n.env\ndata/\n*.sqlite\n*.sqlite-wal\n*.sqlite-shm\n' },
     ];

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

@@ -7,14 +7,21 @@ const { createInspection } = require('../development/Inspection');
 const developmentSettings = require('../development/settings');
 const OwnedServerLifecycle = require('../OwnedServerLifecycle');
 const { listenServer, validateListenerOptions } = require('../serverLifecycle');
+const { scheduleStartupCleanup } = require('../StartupCleanup');
 
 class LiveHtmlServer {
     constructor(options = {}) {
+        try { this.initialize(options); }
+        catch (error) { throw scheduleStartupCleanup(error, () => this.shutdown()); }
+    }
+
+    initialize(options) {
         if (!options || typeof options !== 'object' || Array.isArray(options)) {
             throw new TypeError('Live HTML server options must be an object.');
         }
         const {
             pages,
+            socketRoutes = [],
             templateRoot,
             livePaths,
             sessionTtlMs,
@@ -29,6 +36,9 @@ class LiveHtmlServer {
             server: suppliedApp,
             ...httpOptions
         } = options;
+        if (!Array.isArray(socketRoutes) || socketRoutes.some(Route => typeof Route !== 'function')) {
+            throw new TypeError('`socketRoutes` must be an array of route classes.');
+        }
         const settings = developmentSettings(development, ['inspect', 'refresh'], { refresh: process.env.REDWEB_DEV_REFRESH === '1' });
         this._inspection = createInspection({ inspect: settings.inspect });
         const app = suppliedApp === undefined ? express() : suppliedApp;
@@ -58,11 +68,10 @@ class LiveHtmlServer {
         validateListenerOptions({ ...this.http, listen });
         this._ownedServer = new OwnedServerLifecycle(this.http.server);
         try {
-            if (this.manager.hasLivePages) {
-                const Route = this.manager.route();
+            if (this.manager.hasLivePages || socketRoutes.length) {
                 this.sockets = new SocketServer({
                     server: this.http.server,
-                    routes: [Route],
+                    routes: [...(this.manager.hasLivePages ? [this.manager.route()] : []), ...require('./PageSocketRoute').bindRoutes(this.manager, socketRoutes)],
                     listen,
                     port: this.http.port,
                     bind: this.http.bind,
@@ -100,11 +109,11 @@ class LiveHtmlServer {
             try { await this.sockets.shutdown(); }
             catch (error) { errors.push(error); }
         }
-        try { await this.manager.shutdown(); }
+        try { await this.manager?.shutdown(); }
         catch (error) {
             errors.push(error);
         }
-        try { await this._ownedServer.close(this.manager.shutdownTimeoutMs, () => this.http.shutdown()); }
+        try { await this._ownedServer?.close(this.manager.shutdownTimeoutMs, () => this.http.shutdown()); }
         catch (error) { errors.push(error); }
         if (errors.length) throw new AggregateError(errors, 'Live HTML shutdown failed.');
     }

package/src/htmx/PageManager.js

@@ -16,6 +16,7 @@ const { AccessDenied } = require('../access/AccessPolicy');
 const { PageIdentity, AuthenticationFailure, isPrincipal } = require('./PageIdentity');
 const PageLifetime = require('./PageLifetime');
 const requestSnapshot = require('../context/RequestSnapshot');
+const { scheduleStartupCleanup } = require('../StartupCleanup');
 
 const PROTOCOL_VERSION = '1';
 const DEFAULT_HEARTBEAT = Object.freeze({ intervalMs: 15_000, timeoutMs: 10_000 });
@@ -122,7 +123,8 @@ class PageManager {
         this.renderAbortController = new AbortController();
         setMaxListeners(maxSessions + maxConcurrentRenders + 1, this.renderAbortController.signal);
         this.closing = false;
-        pages.forEach(PageClass => this.register(PageClass));
+        try { pages.forEach(PageClass => this.register(PageClass)); }
+        catch (error) { throw scheduleStartupCleanup(error, () => this.shutdown()); }
         this.hasLivePages = [...this.records.values()].some(record => record.metadata.live !== false);
     }
 
@@ -263,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);
@@ -275,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,
             };
@@ -320,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');
@@ -328,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;
@@ -383,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) };