@ti-engine/core 1.2.3 → 1.3.1

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 This document will contain the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.3.1
+* feat(service caller): refactor the entire service call execution flow for clarity and better performance
+* feat(service caller): create a new private class `ServiceCallProcessor` to handle individual service calls in a contained scope
+* feat(message observer): add new property `priority` to the message observer class. It is used to determine the order in which the observers are notified about the messages
+* feat(message observer)!: change method `onMessage` to now return the message it received. This allows for the message to be modified before it is passed to the next observer based on `priority`
+* feat(message handler)!: change method `onMessage` to `notifyMessageObservers` for clarity. It now implements the `MessageObserver` functionality for prioritization and message modification
+* fix(service caller): fix an issue which did not allow for a service call to be marked as completed thus being entered into the trace log as still pending
+* fix(redis integration): remove hardcoded `#retryMaxAttempts` value in `#setupClient` method
+* fix(redis integration): fix an issue which was setting the client status to `DISCONNECTED` during a normal shut down procedure
+
+## Version 1.3.0
+* feat(redis integration)!: change `reconnectOnError` behavior to also resubmit the failed command in case the error was of type `READONLY`
+* feat(redis integration): improve the reliability and usage of the event notification mechanism for connection observers
+* feat(redis integration): implement listener to the `end` event on Redis connection to capture when connection can no longer be recovered
+* feat(redis integration): notify connection observers `onConnectionLost` event
+* feat(redis integration): add redis client platform-specific status. It is used internally by the platform and can also be accessed via `redisClient.clientStatus` property
+* feat(connection observer): add new event handler `onConnectionLost` that will be invoked when the observed connection is irrevocably lost
+* feat(cache)!: implement `onConnectionLost` handler that will cause the service instance to immediately stop since it cannot work without the cache
+* fix(service caller): fix multiple promise reject condition when a service call timed out and the service handler still attempted to complete with subsequent error
+* fix(service instance): limit health check reporting to one attempt at a time to avoid unnecessary cache requests and log spam
+* fix(redis integration): fix a multiple promise resolve condition on Redis `reconnect` event
+* fix(redis integration): fix broken event propagation on `disrupted` events to some connection observers
+
+## Version 1.2.5
+* feat(cache): extend method `expireValue` to work with has set fields as well
+
+## Version 1.2.4
+* feat(cache): expose the cache module as export in `package.json`
+* feat(cache): add method `hashDeleteField` to remove a hash-set field. This implements the `hdel` Redis command
+* fix(tools): optimize method `stringifyJSON` not to call unnecessary decycling of the value if it's not an object
+* fix(cache): replace `hmset` with `hset` Redis command in both methods that set hash-set values. Also remove unnecessary `_.isObjectLike` call in `hashSetFields` method
+
 ## Version 1.2.3
 * feat(start instance): add support for providing a custom path to the `.env` file to be used at service startup as process argument. Accepted arguments are `--env`, `--env-file`, `--dotenv`, `--dotenv-path`, and `-e`. The path itself should be relative to the working directory and should include the file name
 

package/bin/localization/labels.json

@@ -1,65 +1,65 @@
-{
-  "labels": {
-    "general": {
-      "exceptions": {
-        "0": {
-          "en": "Unidentified error encountered or unrecognized exception code provided."
-        },
-        "1000": {
-          "en": "Error thrown by internal JS source."
-        },
-        "1001": {
-          "en": "Attempt to construct an abstract class detected."
-        },
-        "1002": {
-          "en": "Attempt to call an abstract method detected."
-        },
-        "1003": {
-          "en": "Invalid or no service domain name provided at microservice startup."
-        },
-        "1004": {
-          "en": "The system cache required for proper engine operation is unavailable."
-        },
-        "1005": {
-          "en": "The provided service handler is not a proper function."
-        },
-        "1006": {
-          "en": "The requested feature is not supported by current configuration or version."
-        },
-        "2000": {
-          "en": "Invalid authorization token provided."
-        },
-        "2001": {
-          "en": "Invalid or expired session encountered."
-        },
-        "2002": {
-          "en": "Attempt for unauthorized access detected."
-        },
-        "2003": {
-          "en": "The system detected tampering with the message received via message exchange."
-        },
-        "3000": {
-          "en": "General error during cross-application communication."
-        },
-        "3001": {
-          "en": "The message sender instance is currently unavailable."
-        },
-        "3002": {
-          "en": "The execution of a service could not complete within the allowed timeout."
-        },
-        "3003": {
-          "en": "The specified service is not found in the service registry."
-        },
-        "3004": {
-          "en": "The specified service is not found in the service definition interface."
-        },
-        "3005": {
-          "en": "No handler found in the interface for the specified service or service version."
-        },
-        "3010": {
-          "en": "Connection retry attempts exceeded the configured limit."
-        }
-      }
-    }
-  }
+{
+  "labels": {
+    "general": {
+      "exceptions": {
+        "0": {
+          "en": "Unidentified error encountered or unrecognized exception code provided."
+        },
+        "1000": {
+          "en": "Error thrown by internal JS source."
+        },
+        "1001": {
+          "en": "Attempt to construct an abstract class detected."
+        },
+        "1002": {
+          "en": "Attempt to call an abstract method detected."
+        },
+        "1003": {
+          "en": "Invalid or no service domain name provided at microservice startup."
+        },
+        "1004": {
+          "en": "The system cache required for proper engine operation is unavailable."
+        },
+        "1005": {
+          "en": "The provided service handler is not a proper function."
+        },
+        "1006": {
+          "en": "The requested feature is not supported by current configuration or version."
+        },
+        "2000": {
+          "en": "Invalid authorization token provided."
+        },
+        "2001": {
+          "en": "Invalid or expired session encountered."
+        },
+        "2002": {
+          "en": "Attempt for unauthorized access detected."
+        },
+        "2003": {
+          "en": "The system detected tampering with the message received via message exchange."
+        },
+        "3000": {
+          "en": "General error during cross-application communication."
+        },
+        "3001": {
+          "en": "The message sender instance is currently unavailable."
+        },
+        "3002": {
+          "en": "The execution of a service could not complete within the allowed timeout."
+        },
+        "3003": {
+          "en": "The specified service is not found in the service registry."
+        },
+        "3004": {
+          "en": "The specified service is not found in the service definition interface."
+        },
+        "3005": {
+          "en": "No handler found in the interface for the specified service or service version."
+        },
+        "3010": {
+          "en": "Connection retry attempts exceeded the configured limit."
+        }
+      }
+    }
+  }
 }

package/bin/start-instance.js

@@ -151,7 +151,7 @@ try {
             setImmediate( () => process.exit( 1 ) );
         } );
     } else {
-        logger.log( `Attempting to start a module that does not implement the ServiceInstance abstract class!`, logger.logSeverity.ERROR );
+        logger.log( `Attempting to start a module that does not implement the ServiceInstance abstract class!`, logger.logSeverity.CRITICAL );
         setImmediate( () => process.exit( 1 ) );
     }
 } catch ( error ) {

package/components/connection-observer.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-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * 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/>.
@@ -37,7 +37,8 @@ class ConnectionObserver {
      * @virtual
      * @public
      */
-    onConnectionDisrupted( identifier ) { }
+    onConnectionDisrupted( identifier ) {
+    }
 
     /**
      * Needs to be invoked by the connection handler when the connection is recovered.
@@ -49,8 +50,22 @@ class ConnectionObserver {
      * @virtual
      * @public
      */
-    onConnectionRecovered( identifier ) { }
+    onConnectionRecovered( identifier ) {
+    }
+
+    /**
+     * Needs to be invoked by the connection handler when the connection is irrevocably lost.
+     * <br/>
+     * NOTE: Override this to add custom functionality.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @virtual
+     * @public
+     */
+    onConnectionLost( identifier ) {
+    }
 
 }
 
-module.exports = ConnectionObserver;
+module.exports = ConnectionObserver;

package/components/exchange/message-exchange.js

@@ -74,7 +74,7 @@ class MessageExchange extends MessageObserver {
      * @param {string} serviceDomainName The domain name of the microservice using the message exchange.
      */
     constructor( instanceID, serviceDomainName ) {
-        super();
+        super( 9 );
 
         // make sure this abstract class cannot be instantiated:
         if ( new.target === MessageExchange ) {
@@ -394,12 +394,25 @@ class MessageExchange extends MessageObserver {
         _.pull( this.#disruptedConnections, identifier );
     }
 
+    /**
+     * Used to mark the connection with the provided identifier as disrupted.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionLost( identifier ) {
+        // TODO: implement triggering of a graceful shutdown of the service instance
+    }
+
     /**
      * Used only for the purposes of the message tracer.
      *
      * @method
      * @param {string} identifier The identifier of the observed connection.
      * @param {Message} message The message for processing.
+     * @returns {Message} The message that was received.
      * @override
      * @public
      */
@@ -411,6 +424,8 @@ class MessageExchange extends MessageObserver {
         } else if ( MessageExchange.connectionNameResponsesIn === identifier ) {
             messageTracer.instance.recordTraceEntry( message, messageTracer.messageType.MESSAGE_RESPONSE, messageTracer.dispatchEvent.RECEIVED, messageTracer.messageState.PROCESSED );
         }
+
+        return message;
     }
 
     /**

package/components/exchange/message-handler.js

@@ -54,7 +54,9 @@ class MessageHandler extends ConnectionObserver {
      * @returns {boolean}
      * @public
      */
-    get isAvailable() { return this.#isAvailable; }
+    get isAvailable() {
+        return this.#isAvailable;
+    }
 
     /**
      * Used to set the isAvailable flag.
@@ -65,7 +67,9 @@ class MessageHandler extends ConnectionObserver {
      * @param {boolean} value
      * @public
      */
-    set isAvailable( value ) { this.#isAvailable = value; }
+    set isAvailable( value ) {
+        this.#isAvailable = value;
+    }
 
     /**
      * Returns the connection identifier.
@@ -74,7 +78,9 @@ class MessageHandler extends ConnectionObserver {
      * @returns {string}
      * @public
      */
-    get connectionIdentifier() { return this.#connectionIdentifier; }
+    get connectionIdentifier() {
+        return this.#connectionIdentifier;
+    }
 
     /**
      * Used to initialize and enable the communication capabilities of the handler.
@@ -128,9 +134,9 @@ class MessageHandler extends ConnectionObserver {
      */
     addMessageObserver( messageObserver ) {
         const MessageObserver = require( "#message-observer" );
-
         if ( messageObserver instanceof MessageObserver ) {
             this.#messageObservers.push( messageObserver );
+            this.#messageObservers = _.orderBy( this.#messageObservers, [ "priority" ], [ "desc" ] );
         } else {
             logger.log( `Attempting to add '${ messageObserver.constructor.name }' as message observer but it's not a child-class of 'MessageObserver'!`, logger.logSeverity.WARNING );
         }
@@ -138,19 +144,23 @@ class MessageHandler extends ConnectionObserver {
 
     /**
      * An event-triggered method that will notify any observers about a new message for handling.
+     * <br/>
+     * NOTE: Each observer will be notified in the order of their priority via their {@link MessageObserver.onMessage} method. Additionally, the message will be
+     * passed through each observer in the order of their priority. If the observer returns a modified message, it will be used instead of the original message!
      *
      * @method
      * @param {Message} message
      * @public
      */
-    onMessage( message ) {
+    notifyMessageObservers( message ) {
+        let modifiedMessage = message;
         _.forEach( this.#messageObservers, ( messageObserver ) => {
-            messageObserver.onMessage( this.#connectionIdentifier, message );
+            modifiedMessage = messageObserver.onMessage( this.#connectionIdentifier, modifiedMessage );
         } );
     }
 
     /**
-     * An event-triggered method that will notify any observers about primary connection recovered state.
+     * An event-triggered method that will notify any observers about the primary connection recovered state.
      * <br/>
      * NOTE: You can override this to add custom functionality but make sure to also call the base method
      * using: super.onConnectionRecovered( identifier )
@@ -189,6 +199,26 @@ class MessageHandler extends ConnectionObserver {
         }
     }
 
+    /**
+     * An event-triggered method that will notify any observers about the primary connection having been lost.
+     * <br/>
+     * NOTE: You can override this to add custom functionality but make sure to also call the base method
+     * using: super.onConnectionLost( identifier )
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @private
+     */
+    onConnectionLost( identifier ) {
+        if ( identifier === this.#connectionIdentifier ) {
+            this.#isAvailable = false;
+            _.forEach( this.#messageObservers, ( messageObserver ) => {
+                messageObserver.onConnectionLost( this.#connectionIdentifier );
+            } );
+        }
+    }
+
 }
 
 module.exports = MessageHandler;

package/components/exchange/message-observer.js

@@ -1,12 +1,13 @@
 /*
  * 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>
+ * 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 ConnectionObserver = require( "#connection-observer" );
+const _ = require( "lodash" );
 const exceptions = require( "#exceptions" );
 
 /**
@@ -21,16 +22,45 @@ const exceptions = require( "#exceptions" );
  */
 class MessageObserver extends ConnectionObserver {
 
+    #priority = 0;
+
     /**
+     * @param {number} [priority=0] The priority of this observer. Higher values indicate higher priority.
      * @constructor
      */
-    constructor() {
+    constructor( priority = 0 ) {
         super();
 
         // make sure this abstract class cannot be instantiated:
         if ( new.target === MessageObserver ) {
             throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
         }
+
+        this.#priority = _.isNumber( priority ) ? priority : 0;
+    }
+
+    /**
+     * Returns the priority of this observer.
+     * <br/>
+     * NOTE: Higher values indicate higher priority.
+     *
+     * @property
+     * @returns {number}
+     */
+    get priority() {
+        return this.#priority;
+    }
+
+    /**
+     * Used to set the priority of this observer.
+     * <br/>
+     * NOTE: Higher values indicate higher priority.
+     *
+     * @property
+     * @param {number} value
+     */
+    set priority( value ) {
+        this.#priority = _.isNumber( value ) ? value : 0;
     }
 
     /**
@@ -41,10 +71,13 @@ class MessageObserver extends ConnectionObserver {
      * @method
      * @param {string} identifier The identifier of the observed connection.
      * @param {Message} message The message for processing.
+     * @returns {Message} The message that was received.
      * @virtual
      * @public
      */
-    onMessage( identifier, message ) { }
+    onMessage( identifier, message ) {
+        return message;
+    }
 
     /**
      * Needs to be invoked by the connection handler when the connection is disrupted.
@@ -74,6 +107,20 @@ class MessageObserver extends ConnectionObserver {
         super.onConnectionRecovered( identifier );
     }
 
+    /**
+     * Needs to be invoked by the connection handler when the connection is irrevocably lost.
+     * <br/>
+     * NOTE: Override this to add custom functionality.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @virtual
+     * @public
+     */
+    onConnectionLost( identifier ) {
+        super.onConnectionLost( identifier );
+    }
+
 }
 
-module.exports = MessageObserver;
+module.exports = MessageObserver;

package/components/exchange/message-receiver.js

@@ -117,7 +117,7 @@ class MessageReceiver extends MessageHandler {
             this.onReceive().then( ( message ) => {
                 return this.#postReceive( message );
             } ).then( ( message ) => {
-                this.onMessage( message );
+                this.notifyMessageObservers( message );
             } ).catch( ( error ) => {
                 if ( error.code !== exceptions.exceptionCode.E_COM_MESSAGE_RECEIVER_UNAVAILABLE ) {
                     logger.log( `Error while trying to receive the next pending message from memory cache in receiver '${ this.connectionIdentifier }'! Resuming operation...`, logger.logSeverity.ERROR, error );