@ti-engine/web-framework 1.13.1

package/bin/web-app-manager.js

@@ -0,0 +1,564 @@
+/*
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+const exceptions = require( "@ti-engine/core/exceptions" );
+const tools = require( "@ti-engine/core/tools" );
+const localization = require( "@ti-engine/core/localization" );
+const path = require( "node:path" );
+const fs = require( "node:fs" );
+const configRegistry = require( "#config-registry" );
+const configService = require( "#config-service" );
+const authorization = require( "#authorization" );
+
+const RE_NONCE_ATTR = /\{ti-nonce-placeholder}/g;
+const RE_CSRF_ATTR = /\{ti-csrf-placeholder}/g;
+const RE_HTMX_CONFIG = /\{ti-htmx-config-placeholder}/g;
+const RE_CSP_NONCE = /^[A-Za-z0-9+/=_-]{16,}$/;
+const TI_NESTED_FRAME_PLACEHOLDER = "ti-nested-frame-placeholder";
+
+/**
+ * A generic web application manager that handles the rendering and behavior of web application views. It is designed to be extended by specific web application
+ * managers for each web application you want to implement with the ti-engine web framework.
+ * <br/>
+ * NOTE: You should not instantiate this class directly. Instead, extend it and override the abstract methods as needed. Additionally, you should configure your
+ * ti-engine web server 'TiWebApplicationConfig' settings by specifying the 'classPath' that corresponds to your web application manager. The path should be
+ * relative to the intended process's working directory.
+ *
+ * @class TiWebAppManager
+ * @abstract
+ * @public
+ */
+class TiWebAppManager {
+
+    #webAppIdentifier;
+    #fragments = {};
+    #staticFileCache = {};
+    #staticFileCacheEnabled;
+
+    /**
+     * @constructor
+     * @param {string} identifier The identifier for this web application. Should be unique and recognizable.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor( identifier ) {
+        // Make sure this abstract class cannot be instantiated:
+        if ( new.target === TiWebAppManager ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
+        }
+
+        this.#webAppIdentifier = identifier;
+        this.#staticFileCacheEnabled = ( process.env.TI_WEB_APP_STATIC_CACHE_DISABLED !== "true" );
+
+        // Define the default HTML fragments for the application:
+        this.#fragments[ 'home' ] = {
+            path: "index.html",
+            components: [ "component-notification-bar" ]
+        };
+        this.#fragments[ 'application-main' ] = {
+            title: "Application",
+            path: "fragments/frame-application.html",
+            components: [ "component-topbar", "component-sidebar", "component-notification-bar", "component-sidebar-flyout" ]
+        };
+        this.#fragments[ 'login' ] = {
+            title: "Login",
+            path: "fragments/frame-login.html"
+        };
+        this.#fragments[ 'dashboard' ] = {
+            title: "Dashboard",
+            path: "fragments/frame-dashboard.html"
+        };
+        this.#fragments[ 'administration' ] = {
+            title: "Administration",
+            path: "fragments/frame-administration.html"
+        };
+        this.#fragments[ 'profile' ] = {
+            title: "Profile",
+            path: "fragments/frame-profile.html"
+        };
+        this.#fragments[ 'not-found' ] = {
+            title: "Not Found",
+            path: "fragments/frame-not-found.html"
+        };
+    }
+
+    /* Public interface */
+
+    /**
+     * Returns the identifier for this web application.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get webAppIdentifier() {
+        return this.#webAppIdentifier;
+    }
+
+    /**
+     * Adds a new HTML fragment to the web application.
+     * <br/>
+     * NOTE: This method should only be called during the initialization phase of your web application manager.
+     *
+     * @method
+     * @param {string} identifier
+     * @param {Object} fragment The fragment descriptor (`{ title, path, components }`). May also carry an optional
+     * `roles` array (`Array<string|number>`): when present, the default {@link TiWebAppManager#verifyAccess} serves
+     * the fragment only to sessions holding at least one of those roles; omit it (or leave empty) for a public screen.
+     * @throws {TiException.E_GEN_UNALLOWED_OVERRIDE} If a fragment with the same identifier already exists.
+     * @public
+     */
+    addFragment( identifier, fragment ) {
+        if ( this.#fragments[ identifier ] === undefined ) {
+            this.#fragments[ identifier ] = fragment;
+        } else {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_UNALLOWED_OVERRIDE, { identifier: identifier } );
+        }
+    }
+
+    /**
+     * Registers an editable configuration document with the framework config registry (JSON Schema + semantic
+     * validators + default value + editor metadata). Call during initialization. See {@link ConfigRegistry#register}.
+     *
+     * @method
+     * @param {string} configKey
+     * @param {Object} definition
+     * @returns {TiWebAppManager} this (chainable)
+     * @public
+     */
+    registerConfigDocument( configKey, definition ) {
+        configRegistry.instance.register( configKey, definition );
+        return this;
+    }
+
+    /**
+     * Registers a JSON Schema that is referenced (via `$ref`) by config-document schemas but is not itself a document.
+     *
+     * @method
+     * @param {Object} schema
+     * @returns {TiWebAppManager} this (chainable)
+     * @public
+     */
+    registerConfigSchema( schema ) {
+        configRegistry.instance.addSchema( schema );
+        return this;
+    }
+
+    /**
+     * Registers a composite (entity) editor with the framework config service — a `compose(docs)`/`decompose(edited,docs)`
+     * pair over one or more documents. Call during initialization. See {@link ConfigService#registerEditor}.
+     *
+     * @method
+     * @param {string} editorKey
+     * @param {Object} definition
+     * @returns {TiWebAppManager} this (chainable)
+     * @public
+     */
+    registerConfigEditor( editorKey, definition ) {
+        configService.instance.registerEditor( editorKey, definition );
+        return this;
+    }
+
+    /**
+     * Used to clear the static file cache. This is useful for testing purposes to ensure that the web server is always serving fresh content.
+     *
+     * @method
+     * @public
+     */
+    clearStaticFileCache() {
+        this.#staticFileCache = {};
+    }
+
+    /**
+     * Optional HTML transformation hook.
+     * <br/>
+     * NOTE: Override in subclasses to add nonces or other dynamic data to outgoing HTML.
+     *
+     * @method
+     * @param {string} html
+     * @param {Object} [options]
+     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
+     * @param {boolean} [options.isHome] Optional flag to indicate whether the requested route is the home page.
+     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
+     * @param {string} [options.title] Optional title to replace the placeholder in the HTML.
+     * @returns {Promise<string>}
+     * @virtual
+     * @public
+     */
+    transformHtml( html, options = {} ) {
+        return new Promise( ( resolve, reject ) => {
+            let transformedHtml = String( html );
+
+            // Insert nonce in all placeholder locations. If nonce is not provided or is invalid, this will use an empty string instead to remove the placeholder:
+            const nonce = ( typeof options?.nonce === "string" && RE_CSP_NONCE.test( options?.nonce ) ) ? options?.nonce : "";
+            transformedHtml = transformedHtml.replaceAll( RE_NONCE_ATTR, nonce );
+            if ( options.isHome ) {
+                let htmxConfig = {
+                    inlineScriptNonce: nonce,
+                    inlineStyleNonce: nonce,
+                    allowEval: false,
+                    refreshOnHistoryMiss: true,
+                    historyCacheSize: 0
+                };
+                transformedHtml = transformedHtml.replace( RE_HTMX_CONFIG, JSON.stringify( htmxConfig ) );
+            }
+
+            const csrfToken = ( typeof options?.csrfToken === "string" ) ? options?.csrfToken : "";
+            transformedHtml = transformedHtml.replaceAll( RE_CSRF_ATTR, csrfToken );
+
+            transformedHtml = transformedHtml.replace( "{ti-title-placeholder}", options.title || "" );
+
+            resolve( transformedHtml );
+        } );
+    }
+
+    /**
+     * Used to assemble the complete HTML view for the requested route, including nested HTML fragments.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string[]} staticContentPaths
+     * @param {string} route
+     * @param {Object} [options]
+     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
+     * @param {boolean} [options.isPartial] Optional flag to indicate whether the requested route is a partial load of a fragment.
+     * @param {string} [options.view] Optional view name to load within this route.
+     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
+     * @returns {Promise<string>}
+     * @public
+     */
+    assembleHtmlView( session, staticContentPaths, route, options = {} ) {
+        return new Promise( ( resolve, reject ) => {
+            let fragment;
+            let getHtmlPromises = [];
+            let localOptions = ( options && typeof options === "object" ) ? { ...options } : {};
+
+            if ( route === "/" ) {
+                fragment = this.#fragments[ 'home' ];
+                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, fragment, { ...localOptions, isHome: true } ) );
+            } else if ( route === "/app/error" ) {
+                // TODO: This endpoint is for testing purposes only. Remove later.
+                return reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_METHOD ) );
+            } else if ( route === "/app" || route === "/app/enter" ) {
+                fragment = ( session && session.user ) ? this.#fragments[ 'application-main' ] : this.#fragments[ 'login' ];
+                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, fragment, localOptions ) );
+            } else if ( route === "/not-found" ) {
+                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'home' ], { ...localOptions, isHome: true, title: this.#fragments[ 'not-found' ].title } ) );
+                getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'not-found' ], localOptions ) );
+            } else {
+                fragment = this.#fragments[ options.view ];
+                if ( !fragment ) {
+                    // Abort execution if the requested view is not found:
+                    return reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI ) );
+                } else {
+                    // This handles application refreshes from nested frames:
+                    if ( options.isPartial !== true ) {
+                        getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'home' ], {
+                            ...localOptions,
+                            isHome: true,
+                            title: fragment.title
+                        } ) );
+                        getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, this.#fragments[ 'application-main' ], localOptions ) );
+                    }
+                    getHtmlPromises.push( this.#getHtmlFragment( session, staticContentPaths, fragment, localOptions ) );
+                }
+            }
+
+            Promise.all( getHtmlPromises ).then( ( filesData ) => {
+                let assembledHtml = undefined;
+                filesData.forEach( ( fileData ) => {
+                    // There should always be at most one ti-nested-frame-placeholder element in each HTML fragment:
+                    assembledHtml = ( assembledHtml ) ? this.#replacePlaceholderElement( assembledHtml, TI_NESTED_FRAME_PLACEHOLDER, fileData ) : fileData;
+                } );
+                resolve( assembledHtml );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to process a request for a data resource.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string} view
+     * @param {Object} [options]
+     * @returns {Promise<Object>}
+     * @virtual
+     * @public
+     */
+    processDataRequest( session, view, options = {} ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( view === "config" ) {
+                resolve( {
+                    labels: localization.getAllLabels( session?.language ),
+                    auth: {
+                        isAuthenticated: Boolean( session && session.user )
+                    }
+                } );
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, { view: view } ) );
+            }
+        } );
+    }
+
+    /**
+     * Used to process an application service request.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string} service
+     * @param {Object} params
+     * @returns {Promise<Object>}
+     * @virtual
+     * @public
+     */
+    processServiceRequest( session, service, params ) {
+        return new Promise( ( resolve, reject ) => {
+            reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI, { service: service } ) );
+        } );
+    }
+
+    /**
+     * Used to verify whether the current user has access to the requested resource. The default implementation gates
+     * HTML fragments by their declared `roles`: a fragment registered via {@link TiWebAppManager#addFragment} with a
+     * `roles` array is served only to sessions holding at least one of those roles (see {@link addFragment}); a
+     * fragment with no `roles` is public to any authenticated user. This makes role-restricted screens unreachable by
+     * direct URL, not merely hidden in the UI. Override in subclasses only to implement additional/alternative checks.
+     *
+     * @method
+     * @virtual
+     * @param {TiSession} session
+     * @param {Object} resource The fragment descriptor; its optional `resource.roles` lists the roles permitted to load it.
+     * @returns {Promise}
+     * @exception {TiException.E_SEC_UNAUTHORIZED_ACCESS} (403) When the session holds none of the fragment's required roles.
+     * @public
+     */
+    verifyAccess( session, resource ) {
+        return new Promise( ( resolve, reject ) => {
+            const requiredRoles = ( resource && resource.roles ) ? resource.roles : null;
+            const userRoles = ( session && session.user && session.user.roles ) || [];
+            if ( authorization.isAccessAllowed( requiredRoles, userRoles ) ) {
+                return resolve();
+            }
+            reject( exceptions.raise( exceptions.exceptionCode.E_SEC_UNAUTHORIZED_ACCESS, null, exceptions.httpCode.C_403 ) );
+        } );
+    }
+
+    /* Private interface */
+
+    /**
+     * Returns the HTML fragment for the requested route.
+     *
+     * @method
+     * @param {TiSession} session
+     * @param {string[]} staticContentPaths
+     * @param {Object} fragment
+     * @param {Object} [options]
+     * @param {string} [options.csrfToken] Optional CSRF token to inject into the HTML.
+     * @param {boolean} [options.isHome] Optional flag to indicate whether the requested route is the home page.
+     * @param {string} [options.nonce] Optional CSP nonce to inject into inline scripts/styles.
+     * @returns {Promise<string>}
+     * @private
+     */
+    #getHtmlFragment( session, staticContentPaths, fragment, options = {} ) {
+        return new Promise( ( resolve, reject ) => {
+            this.verifyAccess( session, fragment ).then( () => {
+                return this.#locateStaticFile( staticContentPaths, fragment.path );
+            } ).then( ( fileData ) => {
+                return this.#replaceComponentPlaceholders( fileData, staticContentPaths, fragment.components );
+            } ).then( ( fileData ) => {
+                return this.transformHtml( fileData, { ...options, title: fragment.title || options.title } );
+            } ).then( ( fileData ) => {
+                resolve( fileData );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Attempts to locate the requested static file in the provided static content paths.
+     *
+     * @method
+     * @param {string[]} staticContentPaths A list of directories to search for static content. If sent as expected by the web server, the first item in the array should be the system default path.
+     * @param {string} filePath Relative path to the static file to locate.
+     * @returns {Promise<string>}
+     * @private
+     */
+    #locateStaticFile( staticContentPaths, filePath ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#staticFileCacheEnabled === true && this.#staticFileCache[ filePath ] !== undefined ) {
+                resolve( this.#staticFileCache[ filePath ] );
+            } else {
+                let fullFilePath;
+                // Search for the file in the static content paths in reverse order so that the default system path is checked last. This will ensure that
+                // any fragment overrides are loaded first (i.e., fragments with the same relative path):
+                for ( let idx = staticContentPaths.length - 1; idx >= 0; idx-- ) {
+                    const staticContentPath = staticContentPaths[ idx ];
+                    let potentialFilePath = path.join( staticContentPath, filePath );
+                    if ( fs.existsSync( potentialFilePath ) ) {
+                        fullFilePath = potentialFilePath;
+                        break;
+                    }
+                }
+
+                if ( fullFilePath !== undefined ) {
+                    fs.promises.readFile( fullFilePath, "utf8" ).then( ( fileData ) => {
+                        if ( this.#staticFileCacheEnabled === true ) {
+                            this.#staticFileCache[ filePath ] = fileData;
+                        }
+                        resolve( fileData );
+                    } ).catch( ( error ) => {
+                        reject( exceptions.raise( error ) );
+                    } );
+                } else {
+                    reject( exceptions.raise( exceptions.exceptionCode.E_WEB_INVALID_REQUEST_URI ) );
+                }
+            }
+        } );
+    }
+
+    /**
+     * Used to replace the component placeholders in the HTML with the actual component HTML.
+     *
+     * @method
+     * @param {string} html
+     * @param {string[]} staticContentPaths
+     * @param {Array<string>} components
+     * @returns {Promise<string>}
+     * @private
+     */
+    #replaceComponentPlaceholders( html, staticContentPaths, components ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( components === undefined || components.length === 0 ) {
+                resolve( html );
+            } else {
+                let transformedHtml = String( html );
+                let promises = [];
+                const componentData = {};
+                tools.arrayUniques( components ).forEach( ( component ) => {
+                    promises.push( this.#locateStaticFile( staticContentPaths, `fragments/components/${ component }.html` ).then( ( fileData ) => {
+                        componentData[ component ] = fileData;
+                    } ) );
+                } );
+
+                Promise.all( promises ).then( () => {
+                    components.forEach( ( component ) => {
+                        transformedHtml = this.#replacePlaceholderElement( transformedHtml, `ti-${ component }-placeholder`, componentData[ component ] );
+                    } );
+                    resolve( transformedHtml );
+                } ).catch( ( error ) => {
+                    reject( exceptions.raise( error ) );
+                } );
+            }
+        } );
+    }
+
+    /**
+     * Used to replace a placeholder element in the HTML with the provided replacement.
+     * <br/>
+     * The placeholder's attributes are exposed to the replacement HTML as `{ti-<attr-name>}` tokens, allowing the
+     * component template to consume initial data without changing its `x-data` factory.
+     * <br/>
+     * If the replacement HTML contains a `<ti-slot></ti-slot>` (or self-closing `<ti-slot/>`) marker, the placeholder's
+     * inner content replaces it precisely; otherwise, inner content is appended before the replacement's last closing
+     * tag (legacy behaviour) so existing components keep working.
+     *
+     * @method
+     * @param {string} html
+     * @param {string} tagName
+     * @param {string} replacement
+     * @returns {string}
+     * @private
+     */
+    #replacePlaceholderElement( html, tagName, replacement ) {
+        const start = html.indexOf( `<${ tagName }` );
+        if ( start === -1 ) {
+            return html;
+        }
+        const gt = html.indexOf( ">", start );
+        if ( gt === -1 ) {
+            return html;
+        }
+        // Tolerate whitespace(s) before '/>' and attributes on the tag:
+        let p = gt - 1;
+        while ( p > start && /\s/.test( html[ p ] ) ) p--;
+        const isSelfClosing = html[ p ] === "/";
+        let end;
+        let inner = "";
+        if ( isSelfClosing ) {
+            end = gt + 1;
+        } else {
+            const close = `</${ tagName }>`;
+            end = html.indexOf( close, gt + 1 );
+            if ( end === -1 ) {
+                return html;
+            }
+            inner = html.slice( gt + 1, end );
+            end += close.length;
+        }
+
+        // Substitute the placeholder's attributes as `{ti-<name>}` tokens inside the replacement HTML:
+        const placeholderAttributes = this.#parsePlaceholderAttributes( html.slice( start, gt + 1 ) );
+        let processedReplacement = replacement;
+        Object.keys( placeholderAttributes ).forEach( ( name ) => {
+            const value = placeholderAttributes[ name ];
+            const token = `{ti-${ name }}`;
+            // Use split/join for a literal replaceAll without regex escaping concerns:
+            processedReplacement = processedReplacement.split( token ).join( value );
+        } );
+
+        let replacementWithInner = processedReplacement;
+        const slotMatch = processedReplacement.match( /<ti-slot\b[^>]*>[\s\S]*?<\/ti-slot>|<ti-slot\b[^>]*\/>/ );
+        if ( slotMatch ) {
+            // If a slot marker exists, the placeholder's inner content (when present) replaces it. When inner is
+            // empty, the slot's own default content (between <ti-slot> and </ti-slot>) is kept by unwrapping it:
+            if ( inner ) {
+                replacementWithInner = processedReplacement.replace( slotMatch[ 0 ], inner );
+            } else {
+                replacementWithInner = processedReplacement.replace( slotMatch[ 0 ], ( match ) => {
+                    const defaultMatch = match.match( /<ti-slot\b[^>]*>([\s\S]*?)<\/ti-slot>/ );
+                    return defaultMatch ? defaultMatch[ 1 ] : "";
+                } );
+            }
+        } else if ( inner ) {
+            const insertAt = processedReplacement.lastIndexOf( "</" );
+            if ( insertAt !== -1 ) {
+                replacementWithInner = processedReplacement.slice( 0, insertAt ) + inner + processedReplacement.slice( insertAt );
+            } else {
+                replacementWithInner = processedReplacement + inner;
+            }
+        }
+
+        return html.slice( 0, start ) + replacementWithInner + html.slice( end );
+    }
+
+    /**
+     * Parses the attribute name/value pairs declared on a placeholder element's opening tag.
+     *
+     * @method
+     * @param {string} openingTag The full opening tag text, e.g. `<ti-foo-placeholder bar="baz">`.
+     * @returns {Object<string, string>}
+     * @private
+     */
+    #parsePlaceholderAttributes( openingTag ) {
+        const attributes = {};
+        // Strip the element name and the surrounding angle brackets so only the attribute string remains:
+        const trimmed = openingTag.replace( /^<[^\s>/]+/, "" ).replace( /\/?>\s*$/, "" );
+        const regex = /([a-zA-Z_][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/g;
+        let match;
+        while ( ( match = regex.exec( trimmed ) ) !== null ) {
+            attributes[ match[ 1 ] ] = match[ 2 ] ?? match[ 3 ] ?? match[ 4 ] ?? "";
+        }
+        return attributes;
+    }
+
+}
+
+module.exports = TiWebAppManager;