@ti-engine/core 1.3.13 → 1.6.0

package/utils/config.js

@@ -1,6 +1,6 @@
 /*
  * 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>
+ * Copyright © 2021-2026 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/>.
@@ -9,104 +9,6 @@
 const _ = require( "lodash" );
 const tools = require( "#tools" );
 
-/**
- * @typedef {string} EnvironmentVariable
- */
-
-/**
- * @typedef {NodeJS.Process} Environment
- * @property {ProcessEnv} env
- * @property {EnvironmentVariable} env.TI_GCLOUD_API_KEY
- * @property {EnvironmentVariable} env.TI_GCLOUD_ENABLED
- * @property {EnvironmentVariable} env.TI_GCLOUD_PROJECT_ID
- * @property {EnvironmentVariable} env.TI_INSTANCE_CLASS
- * @property {EnvironmentVariable} env.TI_INSTANCE_CONFIG
- * @property {EnvironmentVariable} env.TI_INSTANCE_ID
- * @property {EnvironmentVariable} env.TI_INSTANCE_NAME
- * @property {EnvironmentVariable} env.TI_AUDITING_LOG_CONSOLE_ENABLED
- * @property {EnvironmentVariable} env.TI_AUDITING_LOG_DETAILS
- * @property {EnvironmentVariable} env.TI_AUDITING_LOG_MIN_LEVEL
- * @property {EnvironmentVariable} env.TI_AUDITING_LOG_USES_JSON
- * @property {EnvironmentVariable} env.TI_LOCALIZATION_LABELS_PATH
- * @property {EnvironmentVariable} env.TI_LOCALIZATION_LANGUAGE
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_AUTH_KEY
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_DB
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_HOST
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_PORT
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL
- * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_USER
- * @property {EnvironmentVariable} env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED
- * @property {EnvironmentVariable} env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY
- * @property {EnvironmentVariable} env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED
- */
-
-/**
- * @typedef {string} CronString
- */
-
-/**
- * @typedef {Object} SettingsMain
- * @property {SettingsAuditing} auditing
- * @property {SettingsGcloudIntegration} gcloudIntegration
- * @property {SettingsLocalization} localization
- * @property {SettingsMemoryCache} memoryCache
- * @property {SettingsMessageExchange} messageExchange
- * @property {SettingsServiceConfig} serviceConfig
- * @property {string} operationMode
- */
-
-/**
- * @typedef {Object} SettingsAuditing
- * @property {boolean} logConsoleEnabled
- * @property {boolean} logDetails
- * @property {TiLogSeverity} logMinLevel
- * @property {boolean} logUsesJSON
- */
-
-/**
- * @typedef {Object} SettingsGcloudIntegration
- * @property {string} apiKey
- * @property {string} projectID
- */
-
-/**
- * @typedef {Object} SettingsLocalization
- * @property {Array<string>} labelsPath
- * @property {TiLocalizationLanguage} language
- */
-
-/**
- * @typedef {Object} SettingsMemoryCache
- * @property {string} authKey
- * @property {number} redisDB
- * @property {string} redisHost
- * @property {number} redisPort
- * @property {number} retryMaxAttempts
- * @property {number} retryMaxInterval
- * @property {string} user
- */
-
-/**
- * @typedef {Object} SettingsMessageExchange
- * @property {string} messageQueuePrefix
- * @property {string} messageStore
- * @property {boolean} securityHashEnabled
- * @property {string} securityHashKey
- * @property {number} traceExpirationTime
- * @property {boolean} traceLogEnabled
- * @property {string} traceRepository
- */
-
-/**
- * @typedef {Object} SettingsServiceConfig
- * @property {number} executionTimeout
- * @property {string} healthCheckAddress
- * @property {CronString} healthCheckInterval
- * @property {number} healthCheckTimeout
- * @property {string} serviceRegistryAddress
- */
-
 /**
  * Enum for listing all system settings.
  *
@@ -144,7 +46,6 @@ const settingsEnum = tools.enum( {
     SERVICE_REGISTRY_ADDRESS: [ "serviceConfig.serviceRegistryAddress", "serviceRegistryAddress", "" ],
     OPERATION_MODE: [ "operationMode", "operationMode", "" ]
 } );
-
 module.exports.setting = settingsEnum;
 
 /** @type {SettingsMain} */
@@ -158,7 +59,9 @@ if ( settings.auditing ) {
     settings.auditing.logUsesJSON = ( process.env.TI_AUDITING_LOG_USES_JSON !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_USES_JSON ) : settings.auditing.logUsesJSON;
 }
 if ( settings.localization ) {
-    settings.localization.labelsPath = ( process.env.TI_LOCALIZATION_LABELS_PATH !== undefined ) ? [ process.env.TI_LOCALIZATION_LABELS_PATH ] : settings.localization.labelsPath;
+    settings.localization.labelsPath = ( process.env.TI_LOCALIZATION_LABELS_PATH !== undefined )
+        ? process.env.TI_LOCALIZATION_LABELS_PATH.split( "," ).map( ( p ) => p.trim() ).filter( Boolean )
+        : settings.localization.labelsPath;
     settings.localization.language = ( process.env.TI_LOCALIZATION_LANGUAGE !== undefined ) ? process.env.TI_LOCALIZATION_LANGUAGE : settings.localization.language;
 }
 if ( settings.memoryCache ) {

package/utils/exceptions.js

@@ -29,6 +29,7 @@ const exceptionCodeEnum = tools.enum( {
     E_GEN_INVALID_ARGUMENT_TYPE: [ 1007, "invalid argument type", "The provided argument is not of the expected type." ],
     E_GEN_NOT_INITIALIZED: [ 1008, "not initialized", "The invoked framework component is not initialized." ],
     E_GEN_UNALLOWED_OVERRIDE: [ 1009, "unallowed override", "Attempt to override a protected or private method or property detected." ],
+    E_GEN_NOT_IMPLEMENTED: [ 1010, "not implemented", "The requested functionality is not yet implemented." ],
     /** Security & Administration exceptions - codes under 2xxx */
     E_SEC_INVALID_AUTH_TOKEN: [ 2000, "invalid auth token", "Invalid authorization token provided." ],
     E_SEC_INVALID_EXPIRED_SESSION: [ 2001, "invalid or expired session", "Invalid or expired session encountered." ],
@@ -56,9 +57,12 @@ const exceptionCodeEnum = tools.enum( {
     E_WEB_INVALID_REQUEST_FORMAT: [ 4006, "invalid request format", "The request format is not recognized or not supported." ],
     E_WEB_INVALID_REQUEST_CONTENT_TYPE: [ 4007, "invalid request content type", "The request content type is not recognized or not supported." ],
     E_WEB_INVALID_REQUEST_CONTENT_LENGTH: [ 4008, "invalid request content length", "The request content length is not recognized or not supported." ],
-    E_WEB_INVALID_REQUEST_CONTENT_ENCODING: [ 4009, "invalid request content encoding", "The request content encoding is not recognized or not supported." ]
+    E_WEB_INVALID_REQUEST_CONTENT_ENCODING: [ 4009, "invalid request content encoding", "The request content encoding is not recognized or not supported." ],
+    /** Application exceptions - codes under 5xxx */
+    E_APP_RESOURCE_NOT_FOUND: [ 5004, "resource not found", "The requested resource cannot be found. See details for more information." ],
+    E_APP_SERVICE_ERROR: [ 5005, "app service error", "The application service encountered an error. See details for more information." ],
+    E_APP_RESOURCE_ALREADY_EXISTS: [ 5006, "resource already exists", "The resource cannot be created because it already exists. See details for more information." ]
 } );
-
 module.exports.exceptionCode = exceptionCodeEnum;
 
 /**
@@ -134,18 +138,17 @@ const httpCodeEnum = tools.enum( {
     C_510: [ 510, "Not Extended", "Further extensions to the request are required for the server to fulfil it." ],
     C_511: [ 511, "Network Authentication Required", "The client needs to authenticate to gain network access. Intended for use by intercepting proxies used to control access to the network." ]
 } );
-
 module.exports.httpCode = httpCodeEnum;
 
 const labelPath = "system.exceptions.";
 
 /**
- * Represents an exception.
+ * Represents an any-purpose exception.
  *
- * @class Exception
+ * @class TiException
  * @public
  */
-class Exception {
+class TiException {
 
     #id;
     #code;
@@ -266,7 +269,7 @@ class Exception {
     }
 
     /**
-     * Extracts the essential information about the Exception and returns it as JSON.
+     * Extracts the essential information about the {@link TiException} and returns it as JSON.
      *
      * @method
      * @param {boolean} [includeData=true] Whether to include the data property in the output.
@@ -292,38 +295,48 @@ class Exception {
 
 /**
  * Used to raise an exception from the provided source.
+ * <br/>
+ * NOTE: Custom numeric exception IDs are not supported when 'httpCode' is omitted!
  *
  * @method
- * @param {Error|TiExceptionCode|Exception} source Could be a standard JS Error, an ExceptionCode, or another Exception (in which case it will be raised further).
+ * @param {Error|TiExceptionCode|TiException} source Could be a standard JS Error, an ExceptionCode, or another TiException (in which case it will be raised further).
  * @param {Object} [data] Additional JSON data that can go with the exception. If more data is added on later Raise calls, it will be merged with the existing one.
- * @param {string} [exceptionID] Should be used only in cases when we have a recognizable exception ID beforehand. Should not be entered otherwise!
- * @returns {Exception}
+ * @param {string} [exceptionID=undefined] Should be used only in cases when we have a recognizable exception ID beforehand. Should not be entered otherwise!
+ * @param {TiHttpCode} [httpCode=undefined] An optional HTTP code in case this exception needs to be propagated to a web-application frontend. If provided, this will
+ * override any preexisting HTTP code in 'source'!
+ * @returns {TiException}
  * @public
  */
-module.exports.raise = ( source, data, exceptionID ) => {
-    /** @type Exception */
+module.exports.raise = ( source, data, exceptionID = undefined, httpCode = undefined ) => {
+    /** @type TiException */
     let exception;
 
+    // Support flexible argument passing: if exceptionID is a number (likely an HTTP code) and httpCode is missing, swap them:
+    if ( typeof exceptionID === "number" && httpCode === undefined ) {
+        httpCode = exceptionID;
+        exceptionID = undefined;
+    }
+
     if ( source instanceof Error ) {
-        exception = new Exception( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, tools.errorToJSON( source ) );
-    } else if ( source instanceof Exception ) {
+        exception = new TiException( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, tools.errorToJSON( source ) );
+    } else if ( source instanceof TiException ) {
         exception = source;
     } else if ( _.isString( source ) ) {
-        exception = new Exception( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, {
+        exception = new TiException( exceptionID || tools.getUUID(), exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR, {
             message: source
         } );
     } else if ( _.isObjectLike( source ) ) {
-        exception = new Exception(
+        exception = new TiException(
             exceptionID || ( source.id || tools.getUUID() ),
             source.code || exceptionCodeEnum.E_GEN_JS_INTERNAL_ERROR,
             source.data,
             source.description
         );
-        if ( httpCodeEnum.contains( source.httpCode ) ) {
+        if ( source.httpCode && httpCodeEnum.contains( source.httpCode ) ) {
             exception.httpCode = source.httpCode;
         }
     } else {
-        exception = new Exception( exceptionID || tools.getUUID(), ( exceptionCodeEnum.contains( source ) ) ? source : exceptionCodeEnum.E_UNKNOWN_ERROR );
+        exception = new TiException( exceptionID || tools.getUUID(), ( exceptionCodeEnum.contains( source ) ) ? source : exceptionCodeEnum.E_UNKNOWN_ERROR );
     }
 
     // Merge the default exception data with the additional one if it's provided:
@@ -336,11 +349,15 @@ module.exports.raise = ( source, data, exceptionID ) => {
         exception.data = tools.decycle( exception.data );
     }
 
+    if ( httpCode && httpCodeEnum.contains( httpCode ) ) {
+        exception.httpCode = httpCode;
+    }
+
     return exception;
 };
 
 /**
- * Verifies if the passed object is an Exception.
+ * Verifies if the passed object is a {@link TiException}.
  *
  * @method
  * @param {*} object
@@ -348,5 +365,5 @@ module.exports.raise = ( source, data, exceptionID ) => {
  * @public
  */
 module.exports.isException = ( object ) => {
-    return ( object instanceof Exception );
+    return ( object instanceof TiException );
 };

package/utils/localization.js

@@ -1,6 +1,6 @@
 /*
  * 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>
+ * Copyright © 2021-2026 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/>.
@@ -18,6 +18,7 @@ const defaultEmptyLabel = "!!! label not found !!!";
  *
  * @readonly
  * @enum {string}
+ * @typedef {string} TiLocalizationLanguage
  */
 const localizationLanguageEnum = tools.enum( {
     // A:
@@ -227,24 +228,8 @@ const localizationLanguageEnum = tools.enum( {
     ZHUANG: [ "za", "Zhuang", "Zhuang" ],
     ZULU: [ "zu", "Zulu", "Zulu" ]
 } );
-
-/**
- * @typedef {string} TiLocalizationLanguage
- */
 module.exports.localizationLanguage = localizationLanguageEnum;
 
-/**
- * The key of this object is the language code, and the value is the textual representation of the label.
- *
- * @typedef {Object<TiLocalizationLanguage, string>} TiLocalizedLabel
- */
-
-/**
- * A nested labels tree where intermediate nodes are objects and leaf nodes are language-to-text maps.
- *
- * @typedef {Object<string, TiLocalizedLabel | TiLabelsTree>} TiLabelsTree
- */
-
 /** @type {TiLabelsTree} */
 const labels = require( "#labels" );
 

package/utils/logger.js

@@ -16,6 +16,7 @@ const localization = require( "#localization" );
  *
  * @readonly
  * @enum {number}
+ * @typedef {number} TiLogSeverity
  */
 const logSeverityEnum = tools.enum( {
     DEFAULT: [ 0, "default", "The log entry has no assigned severity level." ],
@@ -28,10 +29,6 @@ const logSeverityEnum = tools.enum( {
     ALERT: [ 700, "alert", "A person must take an action immediately." ],
     EMERGENCY: [ 800, "emergency", "One or more systems are unusable." ]
 } );
-
-/**
- * @typedef {number} TiLogSeverity
- */
 module.exports.logSeverity = logSeverityEnum;
 
 /**
@@ -46,10 +43,10 @@ module.exports.getSeverityName = ( severity ) => {
 };
 
 /**
- * Used to extract information from an Exception and convert it to a loggable data object.
+ * Used to extract information from a {@link TiException} and convert it to a loggable data object.
  *
  * @method
- * @param {Exception} exception
+ * @param {TiException} exception
  * @returns {{description, details: (*|undefined), exceptionID}}
  * @private
  */
@@ -66,8 +63,8 @@ const exceptionToLog = ( exception ) => {
  *
  * @method
  * @param {string} message The primary log message.
- * @param {TiLogSeverity} [level=DEFAULT] The log severity level. If the current log filtering setting is higher than this then the log entry will be ignored.
- * @param {Object|Error|Exception} [data={}] Optional JSON data containing details of the log entry.
+ * @param {TiLogSeverity} [level=DEFAULT] The log severity level. If the current log filtering setting is higher than this, then the log entry will be ignored.
+ * @param {Object|Error|TiException} [data={}] Optional JSON data containing details of the log entry.
  * @param {string} [thread='main'] The logging thread to which the log entry belongs.
  * @public
  */

package/utils/tools.js

@@ -1,6 +1,6 @@
 /*
  * 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>
+ * Copyright © 2021-2026 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/>.
@@ -9,21 +9,6 @@
 const _ = require( "lodash" );
 const crypto = require( "node:crypto" );
 
-/**
- * @typedef {Object} TiEnumValue
- * @property {number|string} value
- * @property {string} name
- * @property {string} [description]
- */
-
-/**
- * @typedef {Object} TiEnum
- * @property {Object.<number|string,TiEnumValue>} properties
- * @property {function( (number|string), [string] ): (string|undefined)} name
- * @property {function( (number|string), [string] ): (string|undefined)} description
- * @property {function( (number|string) ): boolean} contains
- */
-
 /**
  * Used to generate and return new UUID.
  *
@@ -41,7 +26,7 @@ module.exports.getUUID = () => {
  * @method
  * @param {Object} object
  * @param {WeakSet} [seen]
- * @return {Object}
+ * @returns {Object}
  * @public
  */
 module.exports.deepFreeze = ( object, seen = new WeakSet() ) => {
@@ -367,7 +352,7 @@ module.exports.decycle = ( object, replacer ) => {
  * replaced with references to the value found by the PATH. This will restore cycles. The object will be mutated.
  *
  * The eval function is used to locate the values described by a PATH. The root object is kept in a $ variable. A
- * regular expression is used to assure that the PATH is extremely well-formed. The regexp contains nested quantifiers.
+ * regular expression is used to ensure that the PATH is extremely well-formed. The regexp contains nested quantifiers.
  * That has been known to have extremely bad performance problems on some browsers for very long strings. A PATH is
  * expected to be reasonably short. A PATH is allowed to belong to a very restricted subset of Goessner's JSONPath.
  *
@@ -455,7 +440,7 @@ module.exports.isJsonString = ( string ) => {
 };
 
 /**
- * Use this to parse any JSON string into JSON object for internal system purposes as it ensures to restore any
+ * Use this to parse any JSON string into a JSON object for internal system purposes as it ensures to restore any
  * circular dependencies obscured with 'stringifyJSON'.
  *
  * @method
@@ -474,7 +459,7 @@ module.exports.parseJSON = ( value ) => {
 
 /**
  * Use this to decompose a JSON object into a sorted string. The values will be ordered alphabetically and combined with
- * their keys, where applicable, starting from the bottom and moving up. Null or undefined values will be ignored and
+ * their keys, where applicable, starting from the bottom and moving up. Null or undefined values will be ignored, and
  * their keys will not be included in the final string.
  *
  * @param {Object} input
@@ -514,6 +499,26 @@ module.exports.decomposeJSON = ( input ) => {
     return decomposed;
 };
 
+/**
+ * Constant-time string comparison. Mirrors the web-framework safe-compare idiom: coerces inputs to
+ * utf8 buffers, short-circuits on length mismatch, and never throws on hostile/non-string input.
+ *
+ * @method
+ * @param {*} a
+ * @param {*} b
+ * @returns {boolean} True only when both inputs coerce to equal-length, byte-identical strings.
+ * @public
+ */
+module.exports.constantTimeEquals = ( a, b ) => {
+    try {
+        const ba = Buffer.from( String( a || "" ), "utf8" );
+        const bb = Buffer.from( String( b || "" ), "utf8" );
+        return ( ba.length !== bb.length ) ? false : crypto.timingSafeEqual( ba, bb );
+    } catch {
+        return false;
+    }
+};
+
 /**
  * Used to create retry policy for the execution of an operation.
  *

package/integrations/gcloud-integration.js

@@ -1,65 +0,0 @@
-/*
- * 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 config = require( "#config" );
-const tools = require( "#tools" );
-
-/**
- * Used to verify if the GCloud integration is enabled.
- *
- * @method
- * @returns {boolean}
- * @public
- */
-module.exports.isEnabled = () => {
-    return tools.toBool( process.env.TI_GCLOUD_ENABLED );
-};
-
-/**
- * Will be used to gracefully shut down the instance.
- * <br/>
- * NOTE: Will be overridden below after the instance creation.
- *
- * @method
- * @param {Error} error
- * @abstract
- * @public
- */
-module.exports.reportError = ( error ) => {
-    console.error( "Attempting to report error to GCloud while integration to it is disabled!" );
-};
-
-if ( process.env.TI_GCLOUD_ENABLED === true ) {
-    const { ErrorReporting } = require( "@google-cloud/error-reporting" );
-
-    const errorReporting = new ErrorReporting( {
-        projectId: config.getSetting( config.setting.GCLOUD_PROJECT_ID ),
-        key: config.getSetting( config.setting.GCLOUD_API_KEY ),
-        reportMode: "production",
-        logLevel: 2,
-        reportUnhandledRejections: true
-    } );
-
-    /**
-     * Reports an error to the GCloud error reporting system.
-     *
-     * @method
-     * @param {Error} error
-     * @override
-     * @public
-     */
-    module.exports.reportError = ( error ) => {
-        errorReporting.report( {
-            eventTime: ( new Date() ).toISOString(),
-            message: error.stack,
-            serviceContext: {
-                service: process.env.TI_INSTANCE_ID
-            }
-        } );
-    };
-}