@ti-engine/core 1.1.4 → 1.1.8

package/components/service-caller.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * 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 MessageObserver = require( "#message-observer" );
 const tools = require( "#tools" );
@@ -92,7 +95,7 @@ class ServiceCaller extends MessageObserver {
             this.#findServiceInRegistry( serviceAddress ).then( () => {
                 return this.#prepareServiceCall( serviceAddress, serviceParams, serviceExecContext );
             } ).then( ( serviceCall ) => {
-                return messageDispatcher.sendRequest( serviceCall );
+                return messageDispatcher.instance.sendRequest( serviceCall );
             } ).then( ( messageID ) => {
                 this.#addTaskHandler( messageID, ( serviceCall ) => {
                     this.#completeServiceCall( serviceCall ).then( ( serviceCall ) => {
@@ -184,7 +187,7 @@ class ServiceCaller extends MessageObserver {
     #findServiceInRegistry( serviceAddress ) {
         return new Promise( ( resolve, reject ) => {
             let serviceCatalog = config.getSetting( config.setting.SERVICE_REGISTRY_ADDRESS ) + serviceAddress.serviceDomainName;
-            cache.isSetMember( serviceCatalog, serviceAddress.serviceAlias ).then( ( result ) => {
+            cache.instance.isSetMember( serviceCatalog, serviceAddress.serviceAlias ).then( ( result ) => {
                 if ( result === true ) {
                     resolve();
                 } else {
@@ -207,7 +210,7 @@ class ServiceCaller extends MessageObserver {
      * @private
      */
     #prepareServiceCall( serviceAddress, serviceParams, serviceExecContext ) {
-        return new Promise( ( resolve, reject ) => {
+        return new Promise( ( resolve ) => {
             const ServiceInstance = require( "#service-instance" );
 
             // assemble the new service call:
@@ -255,7 +258,7 @@ class ServiceCaller extends MessageObserver {
      * @private
      */
     #completeServiceCall( serviceCall ) {
-        return new Promise( ( resolve, reject ) => {
+        return new Promise( ( resolve ) => {
             serviceCall.finishedOn = Date.now();
             serviceCall.executionTime = serviceCall.finishedOn - serviceCall.createdOn;
             serviceCall.isCompleted = true;
@@ -303,4 +306,4 @@ class ServiceCaller extends MessageObserver {
 
 }
 
-module.exports = ServiceCaller;
+module.exports = ServiceCaller;

package/components/service-consumer.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * 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 ServiceInstance = require( "#service-instance" );
 const exceptions = require( "#exceptions" );
@@ -10,7 +13,7 @@ const messageDispatcher = require( "#message-dispatcher" );
 /**
  * Abstract class used to define a Service Consumer behavior.
  * <br/>
- * NOTE: Inherit this to create an a module that can be started as a microservice consumer instance.
+ * NOTE: Inherit this to create a module that can be started as a microservice consumer instance.
  * <br/>
  * NOTE: A service consumer is a microservice that can invoke named business services in the APIs of other
  * microservices using {@link ServiceCall} objects. The consumer does not need to know the specifics of
@@ -62,7 +65,7 @@ class ServiceConsumer extends ServiceInstance {
             this.#serviceCaller = new ServiceCaller();
 
             super.onStart().then( () => {
-                messageDispatcher.addMessageObserverResponsesIn( this.#serviceCaller );
+                messageDispatcher.instance.addMessageObserverResponsesIn( this.#serviceCaller );
                 resolve();
             } ).catch( ( error ) => {
                 reject( exceptions.raise( error ) );
@@ -93,6 +96,22 @@ class ServiceConsumer extends ServiceInstance {
         } );
     }
 
+    /**
+     * Used to report health status of the service instance for external monitoring.
+     * This is a scheduled job that will be executed at SERVICE_HEALTH_CHECK_INTERVAL time.
+     * <br/>
+     * NOTE: By default this method will update a Redis key with an expiration timer. You can override this
+     * functionality with something custom like calling an HTTP endpoint.
+     *
+     * @method
+     * @override
+     * @virtual
+     * @public
+     */
+    reportHealthy() {
+        super.reportHealthy();
+    }
+
     /**
      * Used to invoke a business service in any {@link ServiceInstance}.
      *
@@ -109,4 +128,4 @@ class ServiceConsumer extends ServiceInstance {
 
 }
 
-module.exports = ServiceConsumer;
+module.exports = ServiceConsumer;

package/components/service-executor.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * 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-2023 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 MessageObserver = require( "#message-observer" );
 const ServiceInstance = require( "#service-instance" );
@@ -55,6 +58,8 @@ class ServiceExecutor extends MessageObserver {
     #serviceInterface = {};
     /** @type VerifyAccessMethod */
     #verifyAccess;
+    #registrationTasks = {};
+    #registrationRetryInterval = 500;
 
     /**
      * @constructor
@@ -62,11 +67,12 @@ class ServiceExecutor extends MessageObserver {
     constructor() {
         super();
 
+        // Setup a default empty verify access method:
         this.#verifyAccess = () => {
             return Promise.resolve();
         };
 
-        cache.addConnectionObserver( this );
+        cache.instance.addConnectionObserver( this );
     }
 
     /* Public interface */
@@ -78,7 +84,9 @@ class ServiceExecutor extends MessageObserver {
      * @returns {ServiceInterface}
      * @public
      */
-    get serviceInterface() { return this.#serviceInterface; }
+    get serviceInterface() {
+        return this.#serviceInterface;
+    }
 
     /**
      *
@@ -91,7 +99,7 @@ class ServiceExecutor extends MessageObserver {
      */
     onMessage( identifier, message ) {
         this.#processServiceCall( message ).then( ( serviceCall ) => {
-            return messageDispatcher.sendResponse( serviceCall );
+            return messageDispatcher.instance.sendResponse( serviceCall );
         } ).catch( ( error ) => {
             logger.log( `Failed to send service call response after processing! Service call ID was: '${ message.messageID }'`, logger.logSeverity.ERROR, error );
         } );
@@ -120,17 +128,15 @@ class ServiceExecutor extends MessageObserver {
     onConnectionRecovered( identifier ) {
         super.onConnectionRecovered( identifier );
 
-        if ( identifier !== cache.connectionIdentifier ) {
-            if ( cache.isOperational ) {
-                let serviceCatalog = config.getSetting( config.setting.SERVICE_REGISTRY_ADDRESS ) + ServiceInstance.serviceDomainName;
-                _.forOwn( this.#serviceInterface, ( versions, serviceAlias ) => {
-                    cache.addToSet( serviceCatalog, serviceAlias ).catch( ( error ) => {
-                        logger.log( `Record for service '${ serviceAlias }' could not be added to the service registry.`, logger.logSeverity.ERROR, error );
-                    } );
-                } );
-            } else {
-                //TODO: Retry service registration after 0.5 seconds.
-            }
+        if ( identifier !== cache.instance.connectionIdentifier ) {
+            let serviceCatalog = config.getSetting( config.setting.SERVICE_REGISTRY_ADDRESS ) + ServiceInstance.serviceDomainName;
+            _.forOwn( this.#serviceInterface, ( versions, serviceAlias ) => {
+                if ( !this.#registrationTasks[ serviceAlias ] ) {
+                    this.#registrationTasks[ serviceAlias ] = setInterval( () => {
+                        this.#registerServiceToCatalog( serviceCatalog, serviceAlias );
+                    }, this.#registrationRetryInterval );
+                }
+            } );
         }
     }
 
@@ -197,6 +203,25 @@ class ServiceExecutor extends MessageObserver {
         };
     }
 
+    /**
+     * Used to register a service in the service registry.
+     *
+     * @method
+     * @param {string} serviceCatalog
+     * @param {string} serviceAlias
+     * @private
+     */
+    #registerServiceToCatalog( serviceCatalog, serviceAlias ) {
+        if ( cache.instance.isOperational ) {
+            cache.instance.addToSet( serviceCatalog, serviceAlias ).then( () => {
+                clearTimeout( this.#registrationTasks[ serviceAlias ] );
+                delete this.#registrationTasks[ serviceAlias ];
+            } ).catch( ( error ) => {
+                logger.log( `Record for service '${ serviceAlias }' could not be added to the service registry. Will retry in '${ this.#registrationRetryInterval }' milliseconds.`, logger.logSeverity.ERROR, error );
+            } );
+        }
+    }
+
     /**
      * Used to process the actual service call.
      *
@@ -206,7 +231,7 @@ class ServiceExecutor extends MessageObserver {
      * @private
      */
     #processServiceCall( serviceCall ) {
-        return new Promise( ( resolve, reject ) => {
+        return new Promise( ( resolve ) => {
             this.#verifyAccess( serviceCall.authToken, serviceCall.serviceAddress ).then( () => {
                 return this.#identifyService( serviceCall.serviceAddress );
             } ).then( ( serviceHandler ) => {
@@ -253,4 +278,4 @@ class ServiceExecutor extends MessageObserver {
 
 }
 
-module.exports = ServiceExecutor;
+module.exports = ServiceExecutor;

package/components/service-instance.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * 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 _ = require( "lodash" );
 const schedule = require( "node-schedule" );
@@ -21,8 +24,6 @@ const messageDispatcher = require( "#message-dispatcher" );
  * Abstract class used to define a Service Instance behavior.
  * <br/>
  * NOTE: Inherit this to create a module that can be started as a microservice instance.
- * <br/>
- * NOTE: This class does not
  *
  * @class ServiceInstance
  * @abstract
@@ -43,12 +44,22 @@ class ServiceInstance {
      * @param {Object} [serviceConfig={}] The JSON configuration for this service.
      */
     constructor( serviceDomainName, serviceConfig = {} ) {
-        // make sure this abstract class cannot be instantiated:
+        // Ensure this abstract class cannot be instantiated:
         if ( new.target === ServiceInstance ) {
             throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
         }
 
-        ServiceInstance.#instanceID = process.env.TI_INSTANCE_ID || tools.getUUID();
+        // Guard against multiple instances in a single process (not supported):
+        if ( ServiceInstance.#instanceID && ServiceInstance.#serviceDomainName ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED, {
+                details: "Multiple ServiceInstance initializations per process are not supported."
+            } );
+        }
+
+        // Ensure uniform 'ti-' prefix even if env is missing or custom starter script is used:
+        const envID = process.env.TI_INSTANCE_ID;
+        ServiceInstance.#instanceID = ( envID && String( envID ).startsWith( "ti-" ) ) ? envID : ( "ti-" + ( envID || tools.getUUID() ) );
+
         ServiceInstance.#serviceDomainName = serviceDomainName;
         this.#serviceConfig = ( _.isObjectLike( serviceConfig ) ) ? serviceConfig : { services: [] };
     }
@@ -62,7 +73,9 @@ class ServiceInstance {
      * @returns {string}
      * @public
      */
-    static get instanceID() { return ServiceInstance.#instanceID; }
+    static get instanceID() {
+        return ServiceInstance.#instanceID;
+    }
 
     /**
      * Property returning the current service domain name.
@@ -71,7 +84,9 @@ class ServiceInstance {
      * @returns {string}
      * @public
      */
-    static get serviceDomainName() { return ServiceInstance.#serviceDomainName; }
+    static get serviceDomainName() {
+        return ServiceInstance.#serviceDomainName;
+    }
 
     /**
      * Property to indicate that this and every child class is a {@link ServiceInstance}.
@@ -80,7 +95,9 @@ class ServiceInstance {
      * @returns {boolean}
      * @public
      */
-    get isServiceInstance() { return true; }
+    get isServiceInstance() {
+        return true;
+    }
 
     /**
      * Property returning the service configuration JSON.
@@ -89,7 +106,9 @@ class ServiceInstance {
      * @returns {ServiceConfiguration}
      * @public
      */
-    get serviceConfig() { return this.#serviceConfig; }
+    get serviceConfig() {
+        return this.#serviceConfig;
+    }
 
     /**
      * Initializes the instance.
@@ -137,8 +156,7 @@ class ServiceInstance {
 
             let configureInbound = ( this instanceof ServiceProvider );
             let configureOutbound = ( this instanceof ServiceConsumer );
-
-            messageDispatcher.initialize( new DefaultMessageExchange( ServiceInstance.instanceID, ServiceInstance.serviceDomainName ), configureInbound, configureOutbound ).then( () => {
+            messageDispatcher.instance.initialize( new DefaultMessageExchange( ServiceInstance.instanceID, ServiceInstance.serviceDomainName ), configureInbound, configureOutbound ).then( () => {
                 resolve();
             } ).catch( ( error ) => {
                 reject( exceptions.raise( error ) );
@@ -157,6 +175,8 @@ class ServiceInstance {
         return new Promise( ( resolve, reject ) => {
             this.#preStop().then( () => {
                 return this.onStop();
+            } ).then( () => {
+                return cache.instance.shutDown();
             } ).then( () => {
                 return this.#postStop();
             } ).then( () => {
@@ -172,7 +192,7 @@ class ServiceInstance {
      * <br/>
      * NOTE: This method will be invoked automatically.
      * <br/>
-     * NOTE: If you need to add more onStop logic you can override this method but make sure to call it in the
+     * NOTE: If you need to add more onStop logic, you can override this method but make sure to call it in the
      * overriding method using: super.onStop()
      *
      * @method
@@ -182,7 +202,7 @@ class ServiceInstance {
      */
     onStop() {
         return new Promise( ( resolve, reject ) => {
-            messageDispatcher.shutDown().then( () => {
+            messageDispatcher.instance.shutDown().then( () => {
                 resolve();
             } ).catch( ( error ) => {
                 reject( exceptions.raise( error ) );
@@ -202,9 +222,9 @@ class ServiceInstance {
      * @public
      */
     reportHealthy() {
-        if ( cache.isOperational ) {
+        if ( cache.instance.isOperational ) {
             let timestamp = new Date();
-            cache.setValue( this.#serviceHealthCheck, timestamp.toISOString(), config.getSetting( config.setting.SERVICE_HEALTH_CHECK_TIMEOUT ) ).catch( ( error ) => {
+            cache.instance.setValue( this.#serviceHealthCheck, timestamp.toISOString(), config.getSetting( config.setting.SERVICE_HEALTH_CHECK_TIMEOUT ) ).catch( ( error ) => {
                 logger.log( `Error while trying to report for health check from '${ ServiceInstance.instanceID }'!`, logger.logSeverity.WARNING, error );
             } );
         }
@@ -222,8 +242,8 @@ class ServiceInstance {
      * @private
      */
     #preStart() {
-        return new Promise( ( resolve, reject ) => {
-            this.#serviceHealthCheck = config.getSetting( config.setting.SERVICE_HEALTH_CHECK_ADDRESS ) + process.env.TI_INSTANCE_NAME + ":" + ServiceInstance.instanceID;
+        return new Promise( ( resolve ) => {
+            this.#serviceHealthCheck = config.getSetting( config.setting.SERVICE_HEALTH_CHECK_ADDRESS ) + ServiceInstance.serviceDomainName + ":" + ServiceInstance.instanceID;
             resolve();
         } );
     }
@@ -238,8 +258,8 @@ class ServiceInstance {
      * @private
      */
     #postStart() {
-        return new Promise( ( resolve, reject ) => {
-            // schedule regular health check:
+        return new Promise( ( resolve ) => {
+            // Schedule regular health check:
             this.#reportHealthyJob = schedule.scheduleJob( config.getSetting( config.setting.SERVICE_HEALTH_CHECK_INTERVAL ), () => {
                 this.reportHealthy();
             } );
@@ -263,11 +283,10 @@ class ServiceInstance {
      * @private
      */
     #preStop() {
-        return new Promise( ( resolve, reject ) => {
+        return new Promise( ( resolve ) => {
             if ( this.#reportHealthyJob ) {
                 this.#reportHealthyJob.cancel();
             }
-
             resolve();
         } );
     }
@@ -282,13 +301,12 @@ class ServiceInstance {
      * @private
      */
     #postStop() {
-        return new Promise( ( resolve, reject ) => {
+        return new Promise( ( resolve ) => {
             logger.log( `Instance '${ ServiceInstance.instanceID }' shut down successfully.`, logger.logSeverity.NOTICE );
-
             resolve();
         } );
     }
 
 }
 
-module.exports = ServiceInstance;
+module.exports = ServiceInstance;

package/components/service-provider.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * 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 ServiceConsumer = require( "#service-consumer" );
 const _ = require( "lodash" );
@@ -71,7 +74,7 @@ class ServiceProvider extends ServiceConsumer {
                 let serviceDefinitions = this.serviceConfig.services;
                 return this.registerServices( serviceDefinitions );
             } ).then( () => {
-                messageDispatcher.addMessageObserverRequestsIn( this.#serviceExecutor );
+                messageDispatcher.instance.addMessageObserverRequestsIn( this.#serviceExecutor );
                 resolve();
             } ).catch( ( error ) => {
                 reject( exceptions.raise( error ) );
@@ -102,6 +105,22 @@ class ServiceProvider extends ServiceConsumer {
         } );
     }
 
+    /**
+     * Used to report health status of the service instance for external monitoring.
+     * This is a scheduled job that will be executed at SERVICE_HEALTH_CHECK_INTERVAL time.
+     * <br/>
+     * NOTE: By default this method will update a Redis key with an expiration timer. You can override this
+     * functionality with something custom like calling an HTTP endpoint.
+     *
+     * @method
+     * @override
+     * @virtual
+     * @public
+     */
+    reportHealthy() {
+        super.reportHealthy();
+    }
+
     /**
      * Used to verify whether the service caller has authorization to access the service.
      * <br/>
@@ -184,10 +203,10 @@ class ServiceProvider extends ServiceConsumer {
                     // If this happens, a corresponding log entry will be created but the loading process will continue. Therefore, the following
                     // promise will always resolve (unless a programming error occurs in it of course).
                     let registrationPromise = ( serviceDefinition, defaultServiceHandler ) => {
-                        return new Promise( ( resolve, reject ) => {
+                        return new Promise( ( resolve ) => {
                             this.registerService( serviceDefinition, defaultServiceHandler ).then( () => {
                                 resolve( true );
-                            } ).catch( ( error ) => {
+                            } ).catch( () => {
                                 resolve( false );
                             } );
                         } );
@@ -225,4 +244,4 @@ class ServiceProvider extends ServiceConsumer {
 
 }
 
-module.exports = ServiceProvider;
+module.exports = ServiceProvider;

package/integrations/gcloud-integration.js

@@ -1,9 +1,13 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * 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.
@@ -13,7 +17,7 @@ const config = require( "#config" );
  * @public
  */
 module.exports.isEnabled = () => {
-    return process.env.TI_GCLOUD_ENABLED === true;
+    return tools.toBool( process.env.TI_GCLOUD_ENABLED );
 };
 
 /**