redweb 0.9.0 → 0.10.0

package/src/htmx/HtmlSyntax.js

@@ -0,0 +1,168 @@
+const RAW_TEXT = new Set(['iframe', 'noembed', 'noframes', 'noscript', 'plaintext', 'script', 'style', 'textarea', 'title', 'xmp']);
+
+function isHtmlSpace(character) {
+    return character === ' ' || character === '\t' || character === '\n' || character === '\f' || character === '\r';
+}
+
+function isNonStartMarkup(source, start) {
+    const marker = source[start + 1];
+    if (marker === '!' || marker === '?') return true;
+    return marker === '/' && /[A-Za-z]/.test(source[start + 2]);
+}
+
+function equalsAsciiCaseInsensitive(value, expected) {
+    if (value.length !== expected.length) return false;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        const folded = code >= 65 && code <= 90 ? code + 32 : code;
+        if (folded !== expected.charCodeAt(index)) return false;
+    }
+    return true;
+}
+
+function scanTag(source, position) {
+    let state = 'beforeAttribute';
+    let quote;
+    let attributeName = null;
+    let attributeStart = -1;
+    for (; position < source.length; position += 1) {
+        const character = source[position];
+        if (state === 'quotedValue') {
+            if (character === quote) state = 'beforeAttribute';
+            continue;
+        }
+        if (character === '>') return { end: position, state, attributeName };
+        if (state === 'beforeValue') {
+            if (isHtmlSpace(character)) continue;
+            if (character === '"' || character === "'") {
+                quote = character;
+                state = 'quotedValue';
+            } else state = 'unquotedValue';
+        } else if (state === 'beforeAttribute') {
+            if (!isHtmlSpace(character) && character !== '/') {
+                attributeStart = position;
+                state = 'attributeName';
+            }
+        } else if (state === 'attributeName') {
+            if (character === '=') {
+                attributeName = source.slice(attributeStart, position).toLowerCase();
+                state = 'beforeValue';
+            } else if (isHtmlSpace(character)) {
+                attributeName = source.slice(attributeStart, position).toLowerCase();
+                state = 'afterAttributeName';
+            }
+        } else if (state === 'afterAttributeName') {
+            if (character === '=') state = 'beforeValue';
+            else if (!isHtmlSpace(character) && character !== '/') {
+                attributeStart = position;
+                attributeName = null;
+                state = 'attributeName';
+            }
+        } else if (isHtmlSpace(character)) state = 'beforeAttribute';
+    }
+    return { end: -1, state, attributeName };
+}
+
+function tagEnd(source, position) {
+    return scanTag(source, position).end;
+}
+
+function rawClosingTag(source, name, position) {
+    while (true) {
+        const start = source.indexOf('</', position);
+        if (start < 0) return null;
+        const candidate = source.slice(start + 2, start + 2 + name.length);
+        const boundary = source[start + 2 + name.length];
+        if (equalsAsciiCaseInsensitive(candidate, name) && (boundary === '>' || boundary === '/' || isHtmlSpace(boundary))) {
+            const end = tagEnd(source, start + 2 + name.length);
+            if (end >= 0) return { start, end: end + 1 };
+        }
+        position = start + 2;
+    }
+}
+
+function tagLocation(source, target, kind) {
+    let position = 0;
+    while (position < source.length) {
+        const start = source.indexOf('<', position);
+        if (start < 0) return -1;
+        if (source.startsWith('<!--', start)) {
+            const commentEnd = source.indexOf('-->', start + 4);
+            position = commentEnd < 0 ? source.length : commentEnd + 3;
+            continue;
+        }
+        const recognizedMarkup = isNonStartMarkup(source, start);
+        if (!recognizedMarkup && !/[A-Za-z]/.test(source[start + 1])) {
+            position = start + 1;
+            continue;
+        }
+        const end = tagEnd(source, start + 1);
+        if (end < 0) return -1;
+        const tag = source.slice(start, end + 1);
+        const closing = /^<\/([A-Za-z][\w:-]*)/i.exec(tag)?.[1]?.toLowerCase();
+        if (kind === 'closing' && closing === target) return start;
+        const opening = /^<([A-Za-z][\w:-]*)/i.exec(tag)?.[1]?.toLowerCase();
+        if (kind === 'opening' && opening === target) return start;
+        if (opening && RAW_TEXT.has(opening)) {
+            if (opening === 'plaintext') return -1;
+            const close = rawClosingTag(source, opening, end + 1);
+            position = close ? close.end : source.length;
+        } else {
+            position = end + 1;
+        }
+    }
+    return -1;
+}
+
+function interpolationContext(source) {
+    let position = 0;
+    while (position < source.length) {
+        const start = source.indexOf('<', position);
+        if (start < 0) return { kind: 'text' };
+        if (source.startsWith('<!--', start)) {
+            const commentEnd = source.indexOf('-->', start + 4);
+            if (commentEnd < 0) return { kind: 'protected' };
+            position = commentEnd + 3;
+            continue;
+        }
+        const opening = /^<([A-Za-z][\w:-]*)/.exec(source.slice(start));
+        if (opening) {
+            const name = opening[1].toLowerCase();
+            const scanned = scanTag(source, start + opening[0].length);
+            if (scanned.end < 0) {
+                if (scanned.state === 'quotedValue' && scanned.attributeName) {
+                    return { kind: 'attribute', name: scanned.attributeName };
+                }
+                return { kind: 'protected' };
+            }
+            if (RAW_TEXT.has(name)) {
+                if (name === 'plaintext') return { kind: 'protected' };
+                const close = rawClosingTag(source, name, scanned.end + 1);
+                if (!close) return { kind: 'protected' };
+                position = close.end;
+            } else {
+                position = scanned.end + 1;
+            }
+            continue;
+        }
+        if (isNonStartMarkup(source, start)) {
+            const end = tagEnd(source, start + 1);
+            if (end < 0) return { kind: 'protected' };
+            position = end + 1;
+        } else {
+            position = start + 1;
+        }
+    }
+    return { kind: 'text' };
+}
+
+module.exports = {
+    RAW_TEXT,
+    closingTag: (source, target) => tagLocation(source, target, 'closing'),
+    interpolationContext,
+    isHtmlSpace,
+    isNonStartMarkup,
+    openingTag: (source, target) => tagLocation(source, target, 'opening'),
+    rawClosingTag,
+    tagEnd,
+};

package/src/htmx/LiveHtmlServer.js

@@ -0,0 +1,91 @@
+const express = require('express');
+const HttpServer = require('../http/HttpServer');
+const HttpsServer = require('../http/HttpsServer');
+const SocketServer = require('../ws/SocketServer');
+const { PageManager } = require('./PageManager');
+
+class LiveHtmlServer {
+    constructor(options = {}) {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) {
+            throw new TypeError('Live HTML server options must be an object.');
+        }
+        const {
+            pages,
+            templateRoot,
+            livePaths,
+            sessionTtlMs,
+            maxSessions,
+            maxConcurrentRenders,
+            shutdownTimeoutMs = 1000,
+            heartbeat,
+            authenticate,
+            origins,
+            server: suppliedApp,
+            ...httpOptions
+        } = options;
+        const app = suppliedApp === undefined ? express() : suppliedApp;
+        if (!app || typeof app.get !== 'function' || typeof app.use !== 'function') {
+            throw new TypeError('`server` must be an Express-compatible application.');
+        }
+        this.manager = new PageManager({
+            pages,
+            templateRoot,
+            paths: livePaths,
+            sessionTtlMs,
+            maxSessions,
+            maxConcurrentRenders,
+            shutdownTimeoutMs,
+            heartbeat,
+            authenticate,
+            origins,
+            logger: httpOptions.logger,
+        });
+        this.manager.mount(app);
+        const listen = httpOptions.listen ?? true;
+        const ServerClass = httpOptions.ssl ? HttpsServer : HttpServer;
+        this.http = new ServerClass({ ...httpOptions, server: app, listen: this.manager.hasLivePages ? false : listen });
+        if (this.manager.hasLivePages) {
+            const Route = this.manager.route();
+            this.sockets = new SocketServer({
+                server: this.http.server,
+                routes: [Route],
+                listen,
+                port: this.http.port,
+                bind: this.http.bind,
+                listenCallback: this.http.listenCallback,
+                logger: this.http.logger,
+                closeServerOnShutdown: false,
+            });
+        } else {
+            this.sockets = null;
+        }
+        this.app = this.http.app;
+        this.server = this.http.server;
+        this._shutdownPromise = null;
+    }
+
+    shutdown() {
+        if (!this._shutdownPromise) {
+            this._shutdownPromise = this.performShutdown();
+        }
+        return this._shutdownPromise;
+    }
+
+    async performShutdown() {
+        const errors = [];
+        if (this.sockets) {
+            try { await this.sockets.shutdown(); }
+            catch (error) { errors.push(error); }
+        }
+        try { await this.manager.shutdown(); }
+        catch (error) {
+            errors.push(error);
+            if (error?.code === 'LIVE_HTML_SHUTDOWN_TIMEOUT') this.server.closeAllConnections?.();
+        }
+        try { await this.http.shutdown(); }
+        catch (error) { errors.push(error); }
+        if (errors.length) throw new AggregateError(errors, 'Live HTML shutdown failed.');
+    }
+}
+
+module.exports = LiveHtmlServer;

package/src/htmx/LivePage.js

@@ -0,0 +1,232 @@
+const { AsyncLocalStorage } = require('async_hooks');
+const HtmlRenderer = require('./HtmlRenderer');
+const TemplateRenderer = require('./TemplateRenderer');
+const { isHtml, markHtml, renderValue } = require('./Html');
+const { forEachState, getActionImplementation, getStateConfig, isComponentClass } = require('./metadata');
+
+const RUNTIME = new WeakMap();
+const COMPONENT_RENDER_CONTEXT = new AsyncLocalStorage();
+const RUNTIME_METHODS = Object.freeze([
+    '_activateState',
+    '_component',
+    '_loadComponents',
+    '_attach',
+    '_detach',
+    '_stateChanged',
+    '_setFromClient',
+    '_invoke',
+    'dispose',
+]);
+
+function initializeRuntime(page) {
+    RUNTIME.set(page, {
+        connections: new Set(),
+        disposed: false,
+        stateActive: false,
+        stateValues: new Map(),
+        disposePromise: null,
+        children: new Map(),
+        componentId: null,
+        components: new Map(),
+        root: page,
+    });
+}
+
+function runtime(page) {
+    return RUNTIME.get(page);
+}
+
+class LivePage {
+    constructor() {
+        initializeRuntime(this);
+    }
+
+    static adopt(page) {
+        if (!page || typeof page !== 'object') throw new TypeError('Page construction must return an object.');
+        if (RUNTIME.has(page)) return page;
+        if (!(page instanceof LivePage)) {
+            RUNTIME_METHODS.forEach(name => {
+                if (name in page) throw new TypeError(`Plain page classes cannot define reserved member "${name}".`);
+                Object.defineProperty(page, name, {
+                    configurable: false,
+                    enumerable: false,
+                    writable: false,
+                    value: LivePage.prototype[name],
+                });
+            });
+        }
+        initializeRuntime(page);
+        return page;
+    }
+
+    static isDisposed(page) {
+        return runtime(page).disposed;
+    }
+
+    static activate(page) { return LivePage.prototype._activateState.call(page); }
+    static attach(page, socket, context) { return LivePage.prototype._attach.call(page, socket, context); }
+    static detach(page, socket, context) { return LivePage.prototype._detach.call(page, socket, context); }
+    static dispose(page) { return LivePage.prototype.dispose.call(page); }
+    static invoke(page, name, args, context) { return LivePage.prototype._invoke.call(page, name, args, context); }
+    static loadComponents(page, context) { return LivePage.prototype._loadComponents.call(page, context); }
+    static setFromClient(page, name, value) { return LivePage.prototype._setFromClient.call(page, name, value); }
+
+    static statePayload(page, name, value) {
+        const internal = runtime(page);
+        const payload = HtmlRenderer.statePayload(name, value, page);
+        if (!internal.componentId) return payload;
+        payload.component = internal.componentId;
+        if (payload.html) payload.value = TemplateRenderer.component(payload.value, internal.componentId);
+        return payload;
+    }
+
+    static withRenderContext(context, render) {
+        return COMPONENT_RENDER_CONTEXT.run(context, render);
+    }
+
+    static adoptComponent(owner, name, value) {
+        if (!value || typeof value !== 'object' || !isComponentClass(value.constructor)) return null;
+        if (!/^[A-Za-z_$][\w$-]{0,127}$/.test(name) || ['__proto__', 'prototype', 'constructor'].includes(name)) {
+            throw new TypeError(`Component field "${name}" must be a safe identifier of at most 128 characters.`);
+        }
+        const parent = runtime(owner);
+        const component = value;
+        if (!RUNTIME.has(component)) initializeRuntime(component);
+        const internal = runtime(component);
+        const id = parent.componentId ? `${parent.componentId}.${name}` : name;
+        if (id.length > 128) throw new TypeError('Nested component identifiers must be at most 128 characters.');
+        if (internal.componentId && (internal.componentId !== id || internal.root !== parent.root)) {
+            throw new Error('A component instance can belong to only one component field.');
+        }
+        internal.componentId = id;
+        internal.root = parent.root;
+        parent.children.set(name, component);
+        runtime(parent.root).components.set(id, component);
+        if (!isHtml(component)) markHtml(component, LivePage.prototype._renderComponent);
+        LivePage.activate(component);
+        return component;
+    }
+
+    get _connections() { return runtime(this).connections; }
+    get _disposed() { return runtime(this).disposed; }
+    get _disposePromise() { return runtime(this).disposePromise; }
+
+    _activateState() {
+        const internal = runtime(this);
+        if (internal.stateActive) return false;
+        forEachState(this.constructor, (_options, name) => {
+            internal.stateValues.set(name, this[name]);
+            Object.defineProperty(this, name, {
+                configurable: true,
+                enumerable: true,
+                get: () => internal.stateValues.get(name),
+                set: value => {
+                    const previous = internal.stateValues.get(name);
+                    internal.stateValues.set(name, value);
+                    if (previous !== value) LivePage.prototype._stateChanged.call(this, name, value);
+                },
+            });
+        });
+        internal.stateActive = true;
+        Object.keys(this).forEach(name => {
+            const value = this[name];
+            if (isComponentClass(value?.constructor) && getStateConfig(this.constructor, name)) {
+                throw new TypeError(`Component field "${name}" cannot also be decorated with state().`);
+            }
+            LivePage.adoptComponent(this, name, value);
+        });
+        return true;
+    }
+
+    _renderComponent() {
+        const internal = runtime(this);
+        if (!internal.componentId) throw new Error('Components must be owned by a page field before rendering.');
+        const source = this.render?.(COMPONENT_RENDER_CONTEXT.getStore());
+        if (source && typeof source.then === 'function') throw new TypeError('Component render() must be synchronous.');
+        if (source === undefined) throw new Error(`${this.constructor.name || 'Component'} must provide render().`);
+        const markup = isHtml(source) ? renderValue(source) : HtmlRenderer.render(source.toString(), this);
+        return TemplateRenderer.component(markup, internal.componentId);
+    }
+
+    _component(id) {
+        return runtime(this).root === this ? runtime(this).components.get(id) : undefined;
+    }
+
+    async _loadComponents(context) {
+        for (const component of runtime(this).children.values()) {
+            await component.loading?.(context);
+            await LivePage.loadComponents(component, context);
+        }
+    }
+
+    _attach(socket, context) {
+        const internal = runtime(this);
+        if (internal.disposed) throw new Error('Cannot connect a disposed page.');
+        internal.connections.add(socket);
+        forEachState(this.constructor, (_options, name) => {
+            const payload = LivePage.statePayload(this, name, this[name]);
+            socket.sendEvent?.('redweb:state', payload);
+        });
+        const connected = this.connected?.(context);
+        return Promise.resolve(connected).then(async result => {
+            for (const component of internal.children.values()) {
+                await LivePage.attach(component, socket, context);
+            }
+            return result;
+        });
+    }
+
+    async _detach(socket, context) {
+        const internal = runtime(this);
+        const removed = internal.connections.delete(socket);
+        if (!removed) return false;
+        const tasks = [...internal.children.values()].reverse().map(component => LivePage.detach(component, socket, context));
+        tasks.push(Promise.resolve().then(() => this.disconnected?.(context)));
+        const results = await Promise.allSettled(tasks);
+        LivePage._throwLifecycleFailures(results, 'Live HTML component disconnect failed.');
+        return true;
+    }
+
+    _stateChanged(name, value) {
+        if (!getStateConfig(this.constructor, name)) return false;
+        const payload = LivePage.statePayload(this, name, value);
+        runtime(this).connections.forEach(socket => socket.sendEvent?.('redweb:state', payload));
+        return true;
+    }
+
+    _setFromClient(name, value) {
+        const config = getStateConfig(this.constructor, name);
+        if (!config?.writable) throw new Error(`State "${name}" is not browser-writable.`);
+        this[name] = value;
+    }
+
+    async _invoke(name, args, context) {
+        const implementation = getActionImplementation(this.constructor, name);
+        if (!implementation || this[name] !== implementation) throw new Error(`Unknown page action "${name}".`);
+        if (!Array.isArray(args)) throw new TypeError('Action arguments must be an array.');
+        return implementation.call(this, ...args, context);
+    }
+
+    async dispose() {
+        const internal = runtime(this);
+        if (internal.disposePromise) return internal.disposePromise;
+        internal.disposed = true;
+        internal.connections.clear();
+        internal.disposePromise = Promise.resolve().then(async () => {
+            const tasks = [...internal.children.values()].map(component => LivePage.dispose(component));
+            tasks.push(Promise.resolve().then(() => this.disposed?.()));
+            const results = await Promise.allSettled(tasks);
+            LivePage._throwLifecycleFailures(results, 'Live HTML component cleanup failed.');
+            return true;
+        });
+        return internal.disposePromise;
+    }
+
+    static _throwLifecycleFailures(results, message) {
+        const failures = results.filter(result => result.status === 'rejected').map(result => result.reason);
+        if (failures.length === 1) throw failures[0];
+        if (failures.length > 1) throw new AggregateError(failures, message);
+    }
+}
+
+module.exports = LivePage;

package/src/htmx/PageAssetLoader.js

@@ -0,0 +1,34 @@
+const fs = require('fs');
+const path = require('path');
+
+function outside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+}
+
+class PageAssetLoader {
+    constructor() {
+        this.cache = new Map();
+    }
+
+    load(filePath, rootDir, kind) {
+        const root = path.resolve(rootDir);
+        const resolved = path.resolve(root, filePath);
+        if (outside(root, resolved)) throw new Error(`Page ${kind} is outside the configured template root.`);
+        if (!fs.existsSync(resolved)) throw new Error(`Page ${kind} not found: ${resolved}`);
+        const canonicalRoot = fs.realpathSync(root);
+        const canonicalFile = fs.realpathSync(resolved);
+        if (outside(canonicalRoot, canonicalFile)) {
+            throw new Error(`Page ${kind} is outside the configured template root.`);
+        }
+        if (!this.cache.has(canonicalFile)) {
+            this.cache.set(canonicalFile, Object.freeze({
+                path: canonicalFile,
+                content: fs.readFileSync(canonicalFile, 'utf8'),
+            }));
+        }
+        return this.cache.get(canonicalFile);
+    }
+}
+
+module.exports = PageAssetLoader;