redweb 0.16.2 → 0.16.4

package/src/htmx/LiveResource.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const PAGE_BINDINGS = new WeakMap();
+const UNBOUND = Symbol('unbound');
+
+function key(value) {
+    if (value === undefined || value === null || value === '') return UNBOUND;
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'bigint' || typeof value === 'boolean') return value;
+    throw new TypeError('Live resource keys must be non-empty strings, finite numbers, bigints, booleans, null, or undefined.');
+}
+
+function safeProperty(value) {
+    if (typeof value !== 'string' || !value || value.length > 128 || ['__proto__', 'prototype', 'constructor'].includes(value)) {
+        throw new TypeError('Live resource properties must be safe non-empty names of at most 128 characters.');
+    }
+    return value;
+}
+
+class LiveResource {
+    constructor() {
+        this.subscribers = new Map();
+    }
+
+    publish(resourceKey, value) {
+        const resolved = key(resourceKey);
+        if (resolved === UNBOUND) throw new TypeError('Live resources cannot publish without a key.');
+        const subscribers = [...(this.subscribers.get(resolved) || [])];
+        subscribers.forEach(binding => {
+            if (!binding.active || binding.key !== resolved) return;
+            binding.page[binding.property] = value;
+        });
+        return subscribers.length;
+    }
+
+    bind(page, property, select) {
+        if (!page || typeof page !== 'object') throw new TypeError('Live resources bind to page instances.');
+        safeProperty(property);
+        if (typeof select !== 'function') throw new TypeError('Live resources require a key selector.');
+        const binding = { resource: this, page, property, select, key: UNBOUND, active: true };
+        const bindings = PAGE_BINDINGS.get(page) || new Set();
+        bindings.add(binding);
+        PAGE_BINDINGS.set(page, bindings);
+        try { this.refresh(binding); }
+        catch (error) {
+            this.release(binding);
+            throw error;
+        }
+        return binding;
+    }
+
+    refresh(binding) {
+        if (!binding.active) return false;
+        const next = key(binding.select(binding.page));
+        if (Object.is(next, binding.key)) return false;
+        if (binding.key !== UNBOUND) {
+            const subscribers = this.subscribers.get(binding.key);
+            subscribers?.delete(binding);
+            if (subscribers?.size === 0) this.subscribers.delete(binding.key);
+        }
+        binding.key = next;
+        if (next !== UNBOUND) {
+            const subscribers = this.subscribers.get(next) || new Set();
+            subscribers.add(binding);
+            this.subscribers.set(next, subscribers);
+        }
+        return true;
+    }
+
+    release(binding) {
+        if (!binding?.active) return false;
+        binding.active = false;
+        if (binding.key !== UNBOUND) {
+            const subscribers = this.subscribers.get(binding.key);
+            subscribers?.delete(binding);
+            if (subscribers?.size === 0) this.subscribers.delete(binding.key);
+        }
+        const bindings = PAGE_BINDINGS.get(binding.page);
+        bindings?.delete(binding);
+        if (bindings?.size === 0) PAGE_BINDINGS.delete(binding.page);
+        return true;
+    }
+
+    static refresh(page) {
+        PAGE_BINDINGS.get(page)?.forEach(binding => binding.resource.refresh(binding));
+    }
+
+    static release(page) {
+        [...(PAGE_BINDINGS.get(page) || [])].forEach(binding => binding.resource.release(binding));
+    }
+}
+
+function liveResource() { return new LiveResource(); }
+
+module.exports = { LiveResource, liveResource };

package/src/htmx/PageManager.js

@@ -1,4 +1,7 @@
 const { createHash, randomUUID } = require('crypto');
+const { Transform } = require('stream');
+const { finished } = require('stream/promises');
+const PageTaskLane = require('./PageTaskLane');
 const { RequestFailure } = require('../access/RequestFailure');
 const path = require('path');
 const { setMaxListeners } = require('events');
@@ -10,7 +13,7 @@ const LivePage = require('./LivePage');
 const ReactiveRenderer = require('./ReactiveRenderer');
 const browserRuntime = require('./browserRuntime');
 const { isHtml, renderValue, trustedHtml } = require('./Html');
-const { getPageMetadata, getPageStylesheetRoots, getPageTemplateRoot } = require('./metadata');
+const { getActionImplementation, getInjectMetadata, getPageMetadata, getPageStylesheetRoots, getPageTemplateRoot, getUploadMetadata } = require('./metadata');
 const synchronous = require('./synchronous');
 const { AccessDenied } = require('../access/AccessPolicy');
 const { PageIdentity, AuthenticationFailure, isPrincipal } = require('./PageIdentity');
@@ -25,6 +28,7 @@ const DEFAULT_PATHS = Object.freeze({
     client: '/__redweb/client.js',
     runtime: '/__redweb/runtime.js',
     css: '/__redweb/css',
+    upload: '/__redweb/upload',
 });
 
 function boundedName(value, label) {
@@ -70,7 +74,7 @@ function matchesIfNoneMatch(header, etag) {
 }
 
 class PageManager {
-    constructor({ pages, templateRoot, paths = {}, sessionTtlMs = 30_000, maxSessions = 1000, maxConcurrentRenders = maxSessions, shutdownTimeoutMs = 1000, heartbeat = DEFAULT_HEARTBEAT, authenticate, authenticationTimeoutMs, origins, logger = console }, reservedPaths = {}) {
+    constructor({ pages, templateRoot, paths = {}, sessionTtlMs = 30_000, maxSessions = 1000, maxConcurrentRenders = maxSessions, shutdownTimeoutMs = 1000, uploadTimeoutMs = 30_000, heartbeat = DEFAULT_HEARTBEAT, authenticate, authenticationTimeoutMs, origins, providers = {}, logger = console }, reservedPaths = {}) {
         if (!Array.isArray(pages) || pages.length === 0) throw new TypeError('`pages` must be a non-empty array.');
         if (templateRoot !== undefined && (typeof templateRoot !== 'string' || !templateRoot)) throw new TypeError('`templateRoot` must be a non-empty string.');
         if (!Number.isInteger(sessionTtlMs) || sessionTtlMs < 0) throw new TypeError('`sessionTtlMs` must be a non-negative integer.');
@@ -79,11 +83,18 @@ class PageManager {
             throw new TypeError('`maxConcurrentRenders` must be a positive integer.');
         }
         if (!Number.isInteger(shutdownTimeoutMs) || shutdownTimeoutMs < 0) throw new TypeError('`shutdownTimeoutMs` must be a non-negative integer.');
+        if (!Number.isInteger(uploadTimeoutMs) || uploadTimeoutMs < 1 || uploadTimeoutMs > 300_000) throw new TypeError('`uploadTimeoutMs` must be an integer between 1 and 300000.');
         if (!paths || typeof paths !== 'object' || Array.isArray(paths)) throw new TypeError('`paths` must be an object.');
         if (origins !== undefined && typeof origins !== 'function' &&
             (!Array.isArray(origins) || origins.some(origin => typeof origin !== 'string' || !origin))) {
             throw new TypeError('`origins` must be a function or an array of non-empty origins.');
         }
+        if (!providers || typeof providers !== 'object' || Array.isArray(providers) || Object.getPrototypeOf(providers) !== Object.prototype) {
+            throw new TypeError('`providers` must be a plain object.');
+        }
+        if (Object.keys(providers).some(name => !/^[A-Za-z_$][\w$-]{0,127}$/.test(name) || ['__proto__', 'prototype', 'constructor'].includes(name))) {
+            throw new TypeError('Provider names must be safe identifiers of at most 128 characters.');
+        }
         this.paths = { ...DEFAULT_PATHS, ...paths, ...reservedPaths };
         Object.entries(this.paths).forEach(([name, value]) => {
             internalPath(value, name);
@@ -103,8 +114,10 @@ class PageManager {
         this.maxSessions = maxSessions;
         this.maxConcurrentRenders = maxConcurrentRenders;
         this.shutdownTimeoutMs = shutdownTimeoutMs;
+        this.uploadTimeoutMs = uploadTimeoutMs;
         this.heartbeat = heartbeat;
         this.logger = logger || { log() {}, warn() {}, error() {} };
+        this.providers = Object.freeze({ ...providers });
         this.authenticateRequest = authenticate;
         this.identity = new PageIdentity(authenticate, authenticationTimeoutMs);
         this.lifetimes = new Set();
@@ -167,6 +180,11 @@ class PageManager {
     instantiate(record) {
         const instance = new record.PageClass();
         if (!(instance instanceof record.PageClass)) throw new TypeError('Page construction returned an incompatible object.');
+        getInjectMetadata(record.PageClass).forEach((provider, property) => {
+            if (!Object.hasOwn(this.providers, provider)) throw new Error(`Page requires missing provider "${provider}".`);
+            if (instance[property] !== undefined) throw new Error(`Injected property "${property}" must not have an initializer.`);
+            Object.defineProperty(instance, property, { configurable: false, enumerable: true, writable: false, value: this.providers[provider] });
+        });
         const page = LivePage.adopt(instance);
         page._activateState();
         return page;
@@ -177,6 +195,11 @@ class PageManager {
             const clientFile = path.join(path.dirname(require.resolve('redweb-client/live-html')), 'live-html.js');
             app.get(this.paths.client, (_request, response) => response.sendFile(clientFile));
             app.get(this.paths.runtime, (_request, response) => response.type('text/javascript').send(browserRuntime(this.paths.client)));
+            app.post(this.paths.upload, (request, response) => this.receiveUpload(request, response).catch(error => {
+                if (response.headersSent) return response.destroy();
+                const failure = RequestFailure.from(error, 'UPLOAD_FAILED');
+                response.status(failure.status).json({ error: { code: failure.code, message: failure.message } });
+            }));
         }
         this.stylesheets.forEach((content, url) => app.get(url, (_request, response) => {
             response.set('Cache-Control', 'public, max-age=31536000, immutable').type('text/css').send(content);
@@ -265,10 +288,10 @@ class PageManager {
                 if (!isHtml(result)) throw new TypeError('Page layouts must return html.');
                 return renderValue(result);
             };
-            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 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);
@@ -279,8 +302,9 @@ class PageManager {
             session.renderLifetime = renderer;
             const config = {
                 pageId: session.id,
-                socketPath: record.socketPath || this.paths.socket,
+                socketPath: record.socketPath || this.paths.socket,
                 runtimePath: this.paths.runtime,
+                uploadPath: this.paths.upload,
                 version: PROTOCOL_VERSION,
             };
             if (renderer.enabled) {
@@ -309,7 +333,8 @@ class PageManager {
 
     createSession(page, ownsPage, principal, context = {}, record, lifetime = this.createLifetime(principal)) {
         const id = randomUUID();
-        const session = { id, page, ownsPage, principal, context, record, lifetime, socket: null, timer: null, detaching: null };
+        const session = { id, page, ownsPage, principal, context, record, lifetime, socket: null, timer: null, detaching: null,
+            tasks: new PageTaskLane() };
         lifetime.session = session;
         this.pending.set(id, session);
         this.expire(session);
@@ -324,7 +349,7 @@ class PageManager {
         session.timer.unref?.();
     }
 
-    async authenticate(request, RouteClass) {
+    async authenticate(request, RouteClass) {
         let id;
         try {
             id = new URL(request.url, `http://${request.headers.host || 'localhost'}`).searchParams.get('pageId');
@@ -332,9 +357,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;
-        if (session.record?.metadata.socket !== RouteClass) 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;
@@ -388,7 +413,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 || (socket.readyState !== undefined && socket.readyState !== 1)) 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();
     }
 
@@ -416,6 +441,7 @@ class PageManager {
 
     async release(session) {
         session.lifetime.revoked = true;
+        session.tasks.close(new AccessDenied('ACCESS_CANCELLED'));
         const cleanup = [];
         if (session.socket) {
             session.socket.terminate?.();
@@ -459,9 +485,19 @@ class PageManager {
         return affected.length;
     }
 
+    enqueue(session, task) {
+        const result = session.tasks.enqueue(task);
+        if (!result) throw new RequestFailure('ACCESS_CAPACITY');
+        return result;
+    }
+
     async receive(socket, message) {
         const session = socket.__redwebPageSession;
         if (!session) throw new Error('Page session is not connected.');
+        return this.enqueue(session, () => this.receiveMessage(session, socket, message));
+    }
+
+    async receiveMessage(session, socket, message) {
         this.checkConnected(session, socket);
         const payload = message.payload;
         if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new TypeError('Live HTML payload must be an object.');
@@ -487,6 +523,83 @@ class PageManager {
         throw new TypeError('Live HTML message kind must be "action" or "state".');
     }
 
+    async receiveUpload(request, response) {
+        const address = new URL(request.url, `http://${request.headers.host || 'localhost'}`);
+        const id = address.searchParams.get('pageId');
+        const name = boundedName(address.searchParams.get('action'), 'Upload action name');
+        const component = address.searchParams.get('component');
+        const session = typeof id === 'string' ? this.pending.get(id) || this.active.get(id) : null;
+        if (!session || !this.available(session)) throw new AccessDenied('ACCESS_DENIED');
+        if (request.headers.origin !== undefined && !await this.acceptsOrigin(request.headers.origin, request)) throw new RequestFailure('ORIGIN_DENIED');
+        if (request.headers['sec-fetch-site'] !== undefined && !['same-origin', 'none'].includes(request.headers['sec-fetch-site'])) {
+            throw new RequestFailure('ORIGIN_DENIED');
+        }
+        return this.enqueue(session, () => this.receiveUploadTask(session, request, response, name, component));
+    }
+
+    async receiveUploadTask(session, request, response, name, component) {
+        session.lifetime.check();
+        let stream;
+        let timer;
+        let cancelled = request.destroyed || response.destroyed || session.lifetime.signal.aborted;
+        const cancel = () => { cancelled = true; stream?.destroy(new AccessDenied('ACCESS_CANCELLED')); };
+        request.once('aborted', cancel);
+        request.once('error', cancel);
+        response.once('close', cancel);
+        session.lifetime.signal.addEventListener('abort', cancel, { once: true });
+        try {
+            if (cancelled) throw new AccessDenied('ACCESS_CANCELLED');
+            const principal = await this.identity.resolve(request, session.lifetime.signal);
+            if (!Object.is(principal, session.principal)) throw new AccessDenied('ACCESS_DENIED');
+            const snapshot = requestSnapshot(request);
+            const context = Object.freeze({ ...session.context, request: snapshot, params: snapshot.params, query: snapshot.query,
+                body: snapshot.body, principal, signal: session.lifetime.signal });
+            await session.record.metadata.policy?.check(context);
+            session.lifetime.check();
+            if (cancelled || request.destroyed || response.destroyed) throw new AccessDenied('ACCESS_CANCELLED');
+            const target = component === null || component === '' ? session.page : session.page._component(boundedName(component, 'Upload component name'));
+            if (!target) throw new AccessDenied('ACCESS_DENIED');
+            const config = getUploadMetadata(target.constructor).get(name);
+            const implementation = getActionImplementation(target.constructor, name);
+            if (!config || !implementation || target[name] !== implementation) throw new AccessDenied('ACCESS_DENIED');
+            const contentLength = Number(request.headers['content-length']);
+            if (Number.isFinite(contentLength) && contentLength > config.maxBytes) throw new RequestFailure('UPLOAD_TOO_LARGE');
+            const contentType = String(request.headers['content-type'] || '').split(';', 1)[0].toLowerCase();
+            if (config.accept.length && !config.accept.some(type => type === contentType || type.endsWith('/*') && contentType.startsWith(type.slice(0, -1)))) {
+                throw new RequestFailure('UPLOAD_TYPE_REJECTED');
+            }
+            let bytes = 0;
+            stream = request.pipe(new Transform({ transform(chunk, _encoding, done) {
+                bytes += chunk.length;
+                if (bytes > config.maxBytes) return done(new RequestFailure('UPLOAD_TOO_LARGE'));
+                done(null, chunk);
+            } }));
+            stream.once('error', () => {});
+            timer = setTimeout(() => stream.destroy(new RequestFailure('UPLOAD_TIMEOUT')), this.uploadTimeoutMs);
+            timer.unref?.();
+            const uploadedName = request.headers['x-redweb-upload-name'];
+            let decodedName = null;
+            if (typeof uploadedName === 'string' && uploadedName.length > 0 && uploadedName.length <= 768) {
+                try { decodedName = decodeURIComponent(uploadedName); }
+                catch { decodedName = null; }
+            }
+            const file = Object.freeze({ stream, type: contentType,
+                name: decodedName && decodedName.length <= 256 ? decodedName : null });
+            await implementation.call(target, file, context);
+            if (!stream.readableEnded) {
+                stream.resume();
+                await finished(stream);
+            }
+            response.status(204).end();
+        } finally {
+            request.off('aborted', cancel);
+            request.off('error', cancel);
+            response.off('close', cancel);
+            session.lifetime.signal.removeEventListener('abort', cancel);
+            clearTimeout(timer);
+        }
+    }
+
     route() {
         const manager = this;
         class LiveHtmlHandler extends BaseHandler {

package/src/htmx/PageSocketRoute.js

@@ -1,132 +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 };
+'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 };