@ti-engine/web-framework 1.18.1 → 1.19.1

package/components/session-store.js

@@ -1,111 +1,111 @@
-/*
- * 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 cache = require( "@ti-engine/core/cache" );
-const logger = require( "@ti-engine/core/logger" );
-const exceptions = require( "@ti-engine/core/exceptions" );
-const _ = require( "lodash" );
-const session = require( "express-session" );
-
-// The name of the session store in the cache:
-const sessionStoreName = "ti:web:sessions";
-
-/**
- * A session store for the web server using the standard 'cache' module of the ti-engine.
- * <br/>
- * NOTE: This implementation is compatible with the 'express-session' module.
- *
- * @class SessionStore
- * @public
- */
-class SessionStore extends session.Store {
-
-    /**
-     * @constructor
-     */
-    constructor() {
-        super();
-    }
-
-    /**
-     * Used to store a user session in the cache.
-     *
-     * @method
-     * @param {string} sessionID
-     * @param {TiSession} session
-     * @param {function( (Error|TiException|null)= )} callback
-     * @public
-     */
-    set( sessionID, session, callback ) {
-        cache.instance.hashSetField( sessionStoreName, sessionID, session ).then( () => {
-            let expire = ( session.cookie && _.isNumber( session.cookie.maxAge ) ) ? session.cookie.maxAge / 1000 : null;
-            return ( expire ) ? cache.instance.expireValue( sessionID, expire, sessionStoreName ) : null;
-        } ).then( () => {
-            callback();
-        } ).catch( ( error ) => {
-            logger.log( `Error while trying to store user session in cache!`, logger.logSeverity.ERROR, error );
-            callback( exceptions.raise( error ) );
-        } );
-    }
-
-    /**
-     * Used to retrieve a user session from the cache.
-     *
-     * @method
-     * @param {string} sessionID
-     * @param {function( (Error|TiException|null)=, (TiSession)= )} callback
-     * @public
-     */
-    get( sessionID, callback ) {
-        cache.instance.hashGetField( sessionStoreName, sessionID ).then( ( session ) => {
-            callback( null, session );
-        } ).catch( ( error ) => {
-            logger.log( `Error while trying to fetch user session from cache!`, logger.logSeverity.ERROR, error );
-            callback( exceptions.raise( error ) );
-        } );
-    }
-
-    /**
-     * Used to remove a user session from the cache.
-     *
-     * @method
-     * @param {string} sessionID
-     * @param {function( (Error|TiException|null)= )} callback
-     * @public
-     */
-    destroy( sessionID, callback ) {
-        cache.instance.hashDeleteField( sessionStoreName, sessionID ).then( () => {
-            callback();
-        } ).catch( ( error ) => {
-            logger.log( `Error while trying to remove user session from cache!`, logger.logSeverity.ERROR, error );
-            callback( exceptions.raise( error ) );
-        } );
-    }
-
-    /**
-     * Used to update the expiration time of a user session in the cache.
-     *
-     * @method
-     * @param {string} sessionID
-     * @param {TiSession} session
-     * @param {function( (Error|TiException|null)= )} callback
-     * @public
-     */
-    touch( sessionID, session, callback ) {
-        let expire = ( session.cookie && _.isNumber( session.cookie.maxAge ) ) ? session.cookie.maxAge / 1000 : null;
-        cache.instance.expireValue( sessionID, expire, sessionStoreName ).then( () => {
-            callback();
-        } ).catch( ( error ) => {
-            logger.log( `Error while trying to refresh user session expiration in cache!`, logger.logSeverity.ERROR, error );
-            callback( exceptions.raise( error ) );
-        } );
-    }
-
-}
-
+/*
+ * 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 cache = require( "@ti-engine/core/cache" );
+const logger = require( "@ti-engine/core/logger" );
+const exceptions = require( "@ti-engine/core/exceptions" );
+const _ = require( "lodash" );
+const session = require( "express-session" );
+
+// The name of the session store in the cache:
+const sessionStoreName = "ti:web:sessions";
+
+/**
+ * A session store for the web server using the standard 'cache' module of the ti-engine.
+ * <br/>
+ * NOTE: This implementation is compatible with the 'express-session' module.
+ *
+ * @class SessionStore
+ * @public
+ */
+class SessionStore extends session.Store {
+
+    /**
+     * @constructor
+     */
+    constructor() {
+        super();
+    }
+
+    /**
+     * Used to store a user session in the cache.
+     *
+     * @method
+     * @param {string} sessionID
+     * @param {TiSession} session
+     * @param {function( (Error|TiException|null)= )} callback
+     * @public
+     */
+    set( sessionID, session, callback ) {
+        cache.instance.hashSetField( sessionStoreName, sessionID, session ).then( () => {
+            let expire = ( session.cookie && _.isNumber( session.cookie.maxAge ) ) ? session.cookie.maxAge / 1000 : null;
+            return ( expire ) ? cache.instance.expireValue( sessionID, expire, sessionStoreName ) : null;
+        } ).then( () => {
+            callback();
+        } ).catch( ( error ) => {
+            logger.log( `Error while trying to store user session in cache!`, logger.logSeverity.ERROR, error );
+            callback( exceptions.raise( error ) );
+        } );
+    }
+
+    /**
+     * Used to retrieve a user session from the cache.
+     *
+     * @method
+     * @param {string} sessionID
+     * @param {function( (Error|TiException|null)=, (TiSession)= )} callback
+     * @public
+     */
+    get( sessionID, callback ) {
+        cache.instance.hashGetField( sessionStoreName, sessionID ).then( ( session ) => {
+            callback( null, session );
+        } ).catch( ( error ) => {
+            logger.log( `Error while trying to fetch user session from cache!`, logger.logSeverity.ERROR, error );
+            callback( exceptions.raise( error ) );
+        } );
+    }
+
+    /**
+     * Used to remove a user session from the cache.
+     *
+     * @method
+     * @param {string} sessionID
+     * @param {function( (Error|TiException|null)= )} callback
+     * @public
+     */
+    destroy( sessionID, callback ) {
+        cache.instance.hashDeleteField( sessionStoreName, sessionID ).then( () => {
+            callback();
+        } ).catch( ( error ) => {
+            logger.log( `Error while trying to remove user session from cache!`, logger.logSeverity.ERROR, error );
+            callback( exceptions.raise( error ) );
+        } );
+    }
+
+    /**
+     * Used to update the expiration time of a user session in the cache.
+     *
+     * @method
+     * @param {string} sessionID
+     * @param {TiSession} session
+     * @param {function( (Error|TiException|null)= )} callback
+     * @public
+     */
+    touch( sessionID, session, callback ) {
+        let expire = ( session.cookie && _.isNumber( session.cookie.maxAge ) ) ? session.cookie.maxAge / 1000 : null;
+        cache.instance.expireValue( sessionID, expire, sessionStoreName ).then( () => {
+            callback();
+        } ).catch( ( error ) => {
+            logger.log( `Error while trying to refresh user session expiration in cache!`, logger.logSeverity.ERROR, error );
+            callback( exceptions.raise( error ) );
+        } );
+    }
+
+}
+
 module.exports = SessionStore;

package/components/user.js

@@ -1,133 +1,133 @@
-/*
- * 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/>.
-*/
-
-/**
- * Represents a user in the system.
- *
- * @class User
- * @public
- */
-class User {
-
-    #userID;
-    #username;
-    #email;
-    #name;
-    #language;
-    #roles;
-    #permissions;
-    #details;
-
-    /**
-     * @constructor
-     * @param {Object} userData
-     * @param {string} userData.userID
-     * @param {string} [userData.username]
-     * @param {string} [userData.email]
-     * @param {string} [userData.name]
-     * @param {TiLocalizationLanguage} [userData.language]
-     * @param {string[]} [userData.roles]
-     * @param {string[]} [userData.permissions]
-     * @param {Object} [userData.details]
-     */
-    constructor( userData = {} ) {
-        this.#userID = userData.userID;
-        this.#username = userData.username;
-        this.#email = userData.email;
-        this.#name = userData.name;
-        this.#language = userData.language;
-        this.#roles = Array.isArray( userData.roles ) ? userData.roles : [];
-        this.#permissions = Array.isArray( userData.permissions ) ? userData.permissions : [];
-        this.#details = userData.details || {};
-    }
-
-    /**
-     * @property
-     * @returns {string}
-     * @public
-     */
-    get userID() {
-        return this.#userID;
-    }
-
-    /**
-     * @property
-     * @returns {string}
-     * @public
-     */
-    get username() {
-        return this.#username;
-    }
-
-    /**
-     * @property
-     * @returns {string}
-     * @public
-     */
-    get email() {
-        return this.#email;
-    }
-
-    /**
-     * @property
-     * @returns {string}
-     * @public
-     */
-    get name() {
-        return this.#name;
-    }
-
-    /**
-     * @property
-     * @returns {TiLocalizationLanguage}
-     * @public
-     */
-    get language() {
-        return this.#language;
-    }
-
-    /**
-     * @method
-     * @returns {*}
-     * @public
-     */
-    getDetail( key ) {
-        return this.#details[ key ];
-    }
-
-    /**
-     * @method
-     * @param {string} key
-     * @param {*} value
-     * @public
-     */
-    setDetail( key, value ) {
-        this.#details[ key ] = value;
-    }
-
-    /**
-     * @method
-     * @returns {Object}
-     * @public
-     */
-    asJSON() {
-        return {
-            userID: this.#userID,
-            username: this.#username,
-            email: this.#email,
-            name: this.#name,
-            language: this.#language,
-            roles: this.#roles,
-            permissions: this.#permissions,
-            details: this.#details
-        };
-    }
-
-}
-
+/*
+ * 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/>.
+*/
+
+/**
+ * Represents a user in the system.
+ *
+ * @class User
+ * @public
+ */
+class User {
+
+    #userID;
+    #username;
+    #email;
+    #name;
+    #language;
+    #roles;
+    #permissions;
+    #details;
+
+    /**
+     * @constructor
+     * @param {Object} userData
+     * @param {string} userData.userID
+     * @param {string} [userData.username]
+     * @param {string} [userData.email]
+     * @param {string} [userData.name]
+     * @param {TiLocalizationLanguage} [userData.language]
+     * @param {string[]} [userData.roles]
+     * @param {string[]} [userData.permissions]
+     * @param {Object} [userData.details]
+     */
+    constructor( userData = {} ) {
+        this.#userID = userData.userID;
+        this.#username = userData.username;
+        this.#email = userData.email;
+        this.#name = userData.name;
+        this.#language = userData.language;
+        this.#roles = Array.isArray( userData.roles ) ? userData.roles : [];
+        this.#permissions = Array.isArray( userData.permissions ) ? userData.permissions : [];
+        this.#details = userData.details || {};
+    }
+
+    /**
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get userID() {
+        return this.#userID;
+    }
+
+    /**
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get username() {
+        return this.#username;
+    }
+
+    /**
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get email() {
+        return this.#email;
+    }
+
+    /**
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get name() {
+        return this.#name;
+    }
+
+    /**
+     * @property
+     * @returns {TiLocalizationLanguage}
+     * @public
+     */
+    get language() {
+        return this.#language;
+    }
+
+    /**
+     * @method
+     * @returns {*}
+     * @public
+     */
+    getDetail( key ) {
+        return this.#details[ key ];
+    }
+
+    /**
+     * @method
+     * @param {string} key
+     * @param {*} value
+     * @public
+     */
+    setDetail( key, value ) {
+        this.#details[ key ] = value;
+    }
+
+    /**
+     * @method
+     * @returns {Object}
+     * @public
+     */
+    asJSON() {
+        return {
+            userID: this.#userID,
+            username: this.#username,
+            email: this.#email,
+            name: this.#name,
+            language: this.#language,
+            roles: this.#roles,
+            permissions: this.#permissions,
+            details: this.#details
+        };
+    }
+
+}
+
 module.exports = User;

package/components/web-config-env.js

@@ -15,8 +15,8 @@ const tools = require( "@ti-engine/core/tools" );
  * Each override is applied ONLY when its environment variable is defined, so an absent variable leaves the
  * configured/default value untouched (fully backward compatible). This gives ti-engine web servers 12-factor,
  * container-friendly control over network binding, TLS, the session cookie secret, the enabled authentication
- * methods, the admin allowlist, and the trusted request origins without editing config files. Note `TI_WEB_AUTH_METHODS`,
- * `TI_WEB_AUTH_ADMINS`, and `TI_WEB_TRUSTED_ORIGINS` fully REPLACE their config arrays (`auth.enabledMethods` / `auth.admins` / `trustedOrigins`) rather than
+ * methods, the admin allowlist, the trusted request origins, and the `/static` cache policy without editing config files. Note `TI_WEB_AUTH_METHODS`,
+ * `TI_WEB_AUTH_ADMINS`, `TI_WEB_TRUSTED_ORIGINS`, and `TI_WEB_STATIC_IMMUTABLE_PATHS` fully REPLACE their config arrays (`auth.enabledMethods` / `auth.admins` / `trustedOrigins` / `staticCache.immutablePaths`) rather than
  * merging — the config-file merge is by-index and cannot cleanly override an array.
  *
  * @method
@@ -62,6 +62,23 @@ function applyWebConfigEnvOverrides( config, env = process.env ) {
     if ( env.TI_WEB_TRUSTED_ORIGINS !== undefined ) {
         config.trustedOrigins = env.TI_WEB_TRUSTED_ORIGINS.split( "," ).map( ( origin ) => origin.trim() ).filter( ( origin ) => origin.length > 0 );
     }
+    if ( env.TI_WEB_STATIC_MAX_AGE !== undefined ) {
+        // Seconds, matching the `Cache-Control` directive itself. A non-integer is left to the config value rather
+        // than coerced, exactly as TI_WEB_PORT is — `TiWebServer.resolveStaticCachePolicy` reports the bad value.
+        const maxAge = Number( env.TI_WEB_STATIC_MAX_AGE );
+        if ( Number.isInteger( maxAge ) && maxAge >= 0 ) {
+            config.staticCache = config.staticCache || {};
+            config.staticCache.maxAge = maxAge;
+        }
+    }
+    if ( env.TI_WEB_STATIC_IMMUTABLE !== undefined ) {
+        config.staticCache = config.staticCache || {};
+        config.staticCache.immutable = tools.toBool( env.TI_WEB_STATIC_IMMUTABLE );
+    }
+    if ( env.TI_WEB_STATIC_IMMUTABLE_PATHS !== undefined ) {
+        config.staticCache = config.staticCache || {};
+        config.staticCache.immutablePaths = env.TI_WEB_STATIC_IMMUTABLE_PATHS.split( "," ).map( ( prefix ) => prefix.trim() ).filter( ( prefix ) => prefix.length > 0 );
+    }
     return config;
 }