@ti-engine/core 1.0.11 → 1.1.0

package/CHANGELOG.md

@@ -1,7 +1,51 @@
-##Version 1.0.11
+# ti-engine changelog
+
+## Version 1.1.0
+
+* feat(redis integration): implement better process for fetching and storing the remote Redis server settings and enabled features
+* feat(redis integration): add getter method `serverVersion` that returns the Redis server version
+* feat(redis integration): add support for RedisJSON functionality
+* feat(redis integration): add getter method `isJSONSupported` to verify if this module is enabled/supported in Redis server
+* feat(redis integration): add separate enum for override modes `TiRedisOverrideMode`
+* feat(redis integration): add support for executing any single command in Redis that is otherwise unsupported by the underlying framework. Use method `callCommand` for that in case you need to access something more exotic or currently unimplemented
+* feat(cache): add support for working with JSON values. Currently supporting operations `set`, `get`, and `append array` with more coming in future versions
+* feat(cache): add support for setting manual expiration of values
+* feat(message tracer): change log level of trace entries from `DEBUG` to `NOTICE` for all events
+* feat(message tracer): add functionality for storing the trace entries in the `cache` in JSON format. This is the default behavior and will always work. Traces can later be retrieved from the `cache` for further processing by specialized application
+* feat(message tracer): add new property `traceTimestamp` to the trace entries as it may differ from the actual message timestamp
+* feat(config): add new setting `messageExchange.traceExpirationTime` that controls the preservation time for all trace entries. Default is one hour and will be refreshed every time a new trace is generated. Setting this to `0` will disable
+  expiration altogether
+* feat(config): add new setting `messageExchange.traceRepository` that specifies the name of the key in `cache` that will store the trace entries. The default one should be sufficient for most cases
+* feat(config): change default of setting `messageExchange.traceLogEnabled` to `false`. With this change trace entries will not be written to the standard log output
+* feat(exceptions): add new exception code `1006` as `E_GEN_FEATURE_UNSUPPORTED` to indicate functionality that is unsupported by the system or integrated application
+* refactor(config)!: correct the name of the ENV variable controlling `memoryCache.user` to `TI_MEMORY_CACHE_USER` from previous `MEMORY_CACHE_USER`
+* build(npm): update npm development dependencies to their latest versions
+* docs: update some JSDoc types and other entries to reflect the current state of the code
+
+## Version 1.0.14
+
+* feat(message exchange): improve the behavior of `onConnectionRecovered` and `onConnectionDisrupted` events in modules `cache`, `message-handler` and `service-executor` to prevent cross-activation or deactivation
+* feat(redis integration): improve Redis integration for greater stability, support of Redis Cloud, and support for Redis 7
+* feat(config): enable setting `auditing.logDetails` by default for all logs
+* docs: update general documentation
+
+## Version 1.0.13
+
+* build(npm): update npm dependencies to their latest versions
+
+## Version 1.0.12
+
+* build(npm): update npm dependencies to their latest versions
+
+## Version 1.0.11
+
 * feat(message exchange): implement message tampering and insertion protection
 * feat(config): provide option to turn on/off the message tampering and insertion protection
 * feat(config): provide option to turn on/off message tracing
-* feat: upgrade all used packages to their latest versions
+* build(npm): update npm dependencies to their latest versions
 * refactor(config)!: rename all environment variables that set configuration settings to match their related setting
-* docs: add a change log
+* docs: add a change log
+
+## Version 1.0.0
+
+* feat: create initial version of the framework

package/README.md

@@ -1,14 +1,14 @@
 # ti-engine core
 Flexible framework for the creation of microservices with [node.js](https://nodejs.org/).
 
-## introduction
+## Introduction
 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**. The architectural concept of the framework is based on a standard _messaging system_ that allows for certain customization but also provides predictability and traceability of its behavior.
 
-Being a messaging system, the **ti-engine** relies on a message broker for the actual exchange of messages between microservice instances. The default implementation of the framework uses [Redis](https://redis.io/) cache, however, you could create your own implementation using something like [Rabbit MQ](https://www.rabbitmq.com/). See the [advanced topics](#advanced-topics) section of this documentation for guides on how to do this.
+Being a messaging system, the **ti-engine** relies on a message broker for the actual exchange of messages between microservice instances. The default implementation of the framework uses [Redis](https://redis.io/) cache, however, you could create your own implementation using something like [Rabbit MQ](https://www.rabbitmq.com/). See the [Advanced topics](#advanced-topics) section of this documentation for guides on how to do this.
 
 Please be aware, that this framework is under active development and will expand in the near future. Also, this documentation is still in the process of being created and refined. Make sure to keep an eye on the changes in case you want to use it in the meantime.
 
-## why ti-engine?
+## Why ti-engine?
 The framework is created based on a decade of professional experience with the utilized technologies and architectural approach. It's primary goal is to provide you with a lightweight and flexible solution that can help you build quickly a microservice ecosystem with any degree of size and complexity.
 
 This is what you gain by using **ti-engine** in your project:
@@ -21,16 +21,16 @@ This is what you gain by using **ti-engine** in your project:
 
 These are just some benefits **ti-engine** offers. Get to know it better to find out more ways in which it can help you improve productivity.
 
-## prerequisites & installation
+## Prerequisites & installation
 In order to run the basic ti-engine framework you will need a couple of things:
 * A local [node.js installation](https://nodejs.org/en/download/) with a minimum version of **14.17.0**
 * A local or remote [Redis cache installation](https://redis.io/download) with a minimum version of **5.0.14**
 
-If you are working under Windows OS and you need to install Redis, take a look at this [guide](https://redis.com/blog/redis-on-windows-10/).
+If you are working under Windows 10+ OS and you need to install Redis, take a look at this [guide](https://redis.com/blog/redis-on-windows-10/). You could also use [Redis Cloud](https://app.redislabs.com/) for development purposes as it offers free basic account.
 
 To get the framework itself, use the command `npm install @ti-engine/core`. And to include it directly in your package.json dependencies execute `npm install @ti-engine/core --save-prod`.
 
-## getting started
+## Getting started
 To start using the **ti-engine**, you will have to make sure that all prerequisites are available and operational. However, before we get to the fun part you need to also consider a couple of very important things while working with this framework:
 1. The runtime configuration of the framework can be customized using ENV variables. These can be provided to node.js in all the standard ways, but there is also an option to include an `.env` file.
 2. It loads your framework-related custom scripts and files dynamically, but it always assumes their provided paths are relative to the _current working directory_ (i.e. it uses `process.cwd()`). Be mindful of that whenever you declare file paths in the various settings.
@@ -61,14 +61,14 @@ At the start of the output log you can see a NOTICE that tells you a couple of i
 * The instance name - in this case `tester-service`. In the terminology of the framework, this is also known as a _service domain name_.
 * The _instance identificator_. It is an uuid string with a `ti-` prefix, that is generated by the framework at process start. It can and will be used to trace the messages during their movement through the microservice ecosystem. But more on that later.
 
-Following that come a couple of INFO lines that inform you about the microservice interface state. The framework starts with the process of registration of _business services_ within the service domain of the microservice `tester-service` and successfully adds 2 such services. The necessary information for this is read from a JSON config file included in the package. We'll get into more details on what this all means in the section [creating a microservice](#creating-a-microservice).
+Following that come a couple of INFO lines that inform you about the microservice interface state. The framework starts with the process of registration of _business services_ within the service domain of the microservice `tester-service` and successfully adds 2 such services. The necessary information for this is read from a JSON config file included in the package. We'll get into more details on what this all means in the section [Creating a microservice](#creating-a-microservice).
 
 Once the initialization sequence has completed the framework informs you that the microservice instance has started successfully. If the framework encountered an error during initialization instead, you would see something like this:
 ```text
 [timestamp]: [instance-id] - notice - Starting new instance of type 'tester-service' with instance ID '[instance-id]'.
 [timestamp]: [instance-id] - alert - Error detected in the instance startup script!
 ```
-The following 5 lines inform you about the successful connection to Redis. The default configuration assumes that your Redis is running on localhost and uses the default port. If you have a different setup, you can provide the host and port via ENV variables. We'll cover that in the section [using the framework](#using-the-framework).
+The following 5 lines inform you about the successful connection to Redis. The default configuration assumes that your Redis is running on localhost and uses the default port. If you have a different setup, you can provide the host and port via ENV variables. We'll cover that in the section [Using the framework](#using-the-framework).
 
 Finally, you should see a couple of execution statements with their results in JSON format.
 
@@ -84,24 +84,24 @@ The tester module gets its starting configuration from an `.env` file included i
 TI_INSTANCE_CLASS=tester-service.js
 TI_INSTANCE_CONFIG=tester-service.json
 TI_INSTANCE_NAME=tester-service
-TI_LOG_MIN_LEVEL=200
+TI_AUDITING_LOG_MIN_LEVEL=200
 ```
 The first variable `TI_INSTANCE_CLASS` is mandatory for every microservice you create with the **ti-engine**. It needs to specify the path to the module that is your microservice. Remember, that this path has to be relative to the working directory in which you plan to execute the `node` command. This is especially important when you're configuring your microservices to work in containers. You can find the full list of available ENV variables and what they do below.
 
 Before moving on, also take a good look at the file `bin/start-instance.js`. It should give you an idea on how to the process of starting and stopping a microservice operates. In most cases this file should be sufficient as a starting script for your **ti-engine** based microservice applications. You can, of course, create your own starting script, but then you'll have to consider all necessary steps to properly handle the microservice instance.
 
-## architecture
+## Architecture
 The architectural approach for the **ti-engine** is done in _tiers_ with lower tiers being unaware of the tiers above them. The framework prefers a high level of abstraction in all its tiers and provides many options for customization and extension. While the language is JavaScript, the structuring of the framework follows the OOP principles, and you will find a lot of abstract classes and methods that require you to implement them. These are always marked with the `@abstract` annotation but if you happen to miss one, the framework will raise an exception when you try to use it in your solution.
 
 There are three general tiers in the **ti-engine**:
-1. message exchange
-2. service domains
-3. solution implementation
+1. Message exchange
+2. Service domains
+3. Solution implementation
 
 See the following sections for more information on each of them.
 
-### tier 1 - message exchange
-This is the lowest framework tier, unless we count the actual data objects processed by the framework. As you already know, the foundational **ti-engine** concept is that of a messaging system. Therefore, the first tier provides an abstraction over a chosen message broker (Redis by default). That abstraction makes it easy to switch between message brokers whenever you want to without having to change anything above tier 1. It also provides several added bonuses that can accelerate your work - message encryption, message tracing, message observers, and others. More details about each of these features will be covered in section [using the framework](#using-the-framework).
+### Tier 1 - Message exchange
+This is the lowest framework tier, unless we count the actual data objects processed by the framework. As you already know, the foundational **ti-engine** concept is that of a messaging system. Therefore, the first tier provides an abstraction over a chosen message broker (Redis by default). That abstraction makes it easy to switch between message brokers whenever you want to without having to change anything above tier 1. It also provides several added bonuses that can accelerate your work - message encryption, message tracing, message observers, and others. More details about each of these features will be covered in section [Using the framework](#using-the-framework).
 
 Another important aspect for you to remember is that the message exchange is entirely _asynchronous_. This helps reduce system load and optimizes the usage of the available resources. Even so each node.js process can handle a limited amount of load. Therefore, you should plan for running multiple identical senders and receives in order to scale your solution. But more on that later.
 
@@ -115,21 +115,35 @@ After the processing is done the message payload is modified and the receiver se
 
 In this scenario the framework utilizes _Redis lists_ as queues for the message envelopes and _Redis hash_ as message payload storage. Other message brokers might utilize a slightly different approach, but they should still adhere to the same logical flow.
 
-### tier 2 - service domains
+The modules associated with this tier are all located in the `components/exchange/` folder. This is a short list of some terminology used here and in the JDoc inside the sourcecode itself:
+* Message - this is the actual data object processed by the framework. It consists of two parts: an envelope containing service information and a payload containing the actual data to be processed.
+* Message sender - a specialized connector that is responsible for sending a message on its way to its destination. It does not handle the actual dispatch and delivery.
+* Message receiver - a specialized connector that is responsible for receiving messages at predefined destination.
+* Message exchange - this is the actual message processing engine. It handles sending and receiving messages via preconfigured message senders and message receivers.
+* Message observer - a custom event listener that can be used to react on message `send` and `received` events.
+
+### Tier 2 - Service domains
 This tier focuses on hosting and executing the _business logic_ of your application. It's comprised of _business services_ that process input data and return the result of the processing as output data. The business services are grouped in _service domains_, which are in turn hosted inside stateless _microservices_ also named _service instances_. There are two types of service instances in **ti-engine**:
 * Service consumers - these are service instances, that can call business services in any available service domain.
 * Service providers - these are service instances, that host and run a set of business services in a particular service domain. Every service provider is also a service consumer.
 
 The various service instances in a solution represent a network of interconnected service domains that contain the business logic of your application. All business services exchange data via _service calls_ using abstract _service addresses_. These service calls are transported from one address in the network to another via the underlying message exchange tier. This, however, is completely transparent to the service instances. In essence, tier 2 does not care about the actual data transportation method or protocol. You could in fact change completely the tier 1 approach without having to modify anything in your business logic and business flow.
 
-### tier 3 - solution implementation
-Under development...
+This tier is the place to utilize any databases, file storages, integrations with other applications, scheduling jobs, and so on. In general, it should focus on executing any granular tasks that are essential to backbone operation of your application. The business logic here should remain stateless and any user context should be provided at runtime to each invoked business service. We'll see more concrete examples for that later in section [Using the framework](#using-the-framework).
+
+### Tier 3 - Solution implementation
+This tier comprises the actual implementation of your application. Its structure and behavior depends entirely on your vision and business goals. There are still a couple of points that remain constant:
+* It needs to utilize the business logic defined in tier 2 by calling the business services
+* It needs to take care of any type of stateful behavior like user sessions or transactions
+* It needs to act as the primary interface between users and your application thus handling access management and user interactions
+
+Depending on the type of software you are building, tier 3 can be an API Gateway, a Web application, backend for a Mobile application, or anything like that.
 
-## creating a microservice
+## Creating a microservice
 Under development...
 
-## using the framework
+## Using the framework
 Under development...
 
-## advanced topics
+## Advanced topics
 Under development...

package/bin/settings.json

@@ -1,7 +1,7 @@
 {
   "auditing": {
     "logConsoleEnabled": true,
-    "logDetails": false,
+    "logDetails": true,
     "logMinLevel": 0,
     "logUsesJSON": false
   },
@@ -15,14 +15,17 @@
     "authKey": null,
     "redisDB": 0,
     "redisHost": "127.0.0.1",
-    "redisPort": 6379
+    "redisPort": 6379,
+    "user": "default"
   },
   "messageExchange": {
     "messageQueuePrefix": "ti:messages:",
     "messageStore": "ti:messages:store",
     "securityHashEnabled": true,
     "securityHashKey": "23e7bdc7-a793-41f9-856e-6760332f0c73",
-    "traceLogEnabled": true
+    "traceExpirationTime": 3600,
+    "traceLogEnabled": false,
+    "traceRepository": "ti:messages:trace"
   },
   "serviceConfig": {
     "executionTimeout": 180000,

package/bin/start-instance.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/auditing.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/connection-observer.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/exchange/default/default-message-exchange.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/exchange/default/default-message-receiver.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/exchange/default/default-message-sender.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/exchange/message-dispatcher.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/exchange/message-exchange.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/exchange/message-handler.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 
@@ -158,7 +158,7 @@ class MessageHandler extends ConnectionObserver {
      * @private
      */
     onConnectionRecovered( identifier ) {
-        if ( this.#isAvailable === false ) {
+        if ( this.#isAvailable === false && identifier === this.#connectionIdentifier ) {
             this.#isAvailable = true;
             _.forEach( this.#messageObservers, ( messageObserver ) => {
                 messageObserver.onConnectionRecovered( this.#connectionIdentifier );
@@ -178,7 +178,7 @@ class MessageHandler extends ConnectionObserver {
      * @private
      */
     onConnectionDisrupted( identifier ) {
-        if ( this.#isAvailable === true ) {
+        if ( this.#isAvailable === true && identifier === this.#connectionIdentifier ) {
             this.#isAvailable = false;
             _.forEach( this.#messageObservers, ( messageObserver ) => {
                 messageObserver.onConnectionDisrupted( this.#connectionIdentifier );

package/components/exchange/message-memory-cache.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 
@@ -27,7 +27,8 @@ class MessageMemoryCache {
         let port = config.getSetting( config.setting.MEMORY_CACHE_REDIS_PORT );
         let db = config.getSetting( config.setting.MEMORY_CACHE_REDIS_DB );
         let authKey = config.getSetting( config.setting.MEMORY_CACHE_AUTH_KEY );
-        this.#redisClient = redis.createRedisClient( identifier, host, port, authKey, db );
+        let user = config.getSetting( config.setting.MEMORY_CACHE_USER );
+        this.#redisClient = redis.createRedisClient( identifier, host, port, authKey, user, db );
     }
 
     /* Public interface */

package/components/exchange/message-observer.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/exchange/message-receiver.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/exchange/message-sender.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/exchange/message-tracer.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 
@@ -7,6 +7,8 @@ const _ = require( "lodash" );
 const tools = require( "#tools" );
 const config = require( "#config" );
 const logger = require( "#logger" );
+const exceptions = require( "#exceptions" );
+const cache = require( "#cache" );
 
 /**
  * @typedef {Object} TiTraceEntry
@@ -14,13 +16,18 @@ const logger = require( "#logger" );
  * @property {string} dispatchEvent
  * @property {string} fromAddress
  * @property {string} messageID
- * @property {string} messageSnapshot
+ * @property {Object} messageSnapshot
  * @property {string} messageState
  * @property {string} messageType
  * @property {string} toAddress
  * @property {string} traceID
+ * @property {number} traceTimestamp
  */
 
+const traceRoot = {
+    trace: []
+};
+
 /**
  * Enum for listing message types.
  *
@@ -96,22 +103,28 @@ let formatLogEntry = ( traceEntry ) => {
 };
 
 /**
- * Used to obscure sensitive data in the message snapshot and convert it to string.
+ * Used to obscure sensitive data in the message, remove the payload, and return a snapshot.
  *
  * @method
  * @param {Message} message
- * @returns {string}
+ * @returns {Message}
  * @private
  */
 let obscureSensitiveData = ( message ) => {
-    let messageSnapshot = tools.stringifyJSON( message );
-    return _.replace( messageSnapshot, /("\w*?pin\w*?"|"\w*?pass\w*?"|"\w*?otp\w*?"):"(.*?)"/gmi, "\"SENSITIVE_PROPERTY\":\"OBSCURED_BY_SYSTEM\"" );
+    /** @type Message */
+    let messageSnapshot = tools.parseJSON( _.replace( tools.stringifyJSON( message ), /("\w*?pin\w*?"|"\w*?pass\w*?"|"\w*?otp\w*?"):"(.*?)"/gmi, "\"SENSITIVE_PROPERTY\":\"OBSCURED_BY_SYSTEM\"" ) );
+    delete messageSnapshot.payload;
+    return messageSnapshot;
 };
 
 /**
  * Used to create a trace entry for the provided {@link Message} and parameters.
  * <br/>
- * NOTE: With the exception of failed message delivery, trace events are logged with severity level DEBUG.
+ * NOTE: By default all trace events are stored in the memory cache for further processing and analysis. The
+ * location is configured in the MESSAGE_EXCHANGE_TRACE_REPOSITORY setting.
+ * <br/>
+ * NOTE: Trace events are logged with severity level NOTICE or ERROR for failed dispatches. They still might be
+ * filtered out if the minimum log level setting is set too high.
  *
  * @method
  * @param {Message} message The message to trace.
@@ -124,6 +137,10 @@ module.exports.recordTraceEntry = ( message, messageType, dispatchEvent, message
     // depending on whether the message comes as request or response, the from and to addresses will be opposite:
     let source = message.source.route + "." + message.source.instanceID;
     let destination = message.destination.route + ( ( message.destination.instanceID != null ) ? "." + message.destination.instanceID : "" );
+    let messageSnapshot = obscureSensitiveData( message );
+    delete messageSnapshot.chainID;
+    delete messageSnapshot.messageID;
+    let currentDate = new Date();
 
     /** @type TiTraceEntry */
     let traceEntry = {
@@ -131,16 +148,34 @@ module.exports.recordTraceEntry = ( message, messageType, dispatchEvent, message
         dispatchEvent: tools.getEnumName( dispatchEventEnum, dispatchEvent ),
         fromAddress: ( messageType === messageTypeEnum.MESSAGE_REQUEST ) ? source : destination,
         messageID: message.messageID,
-        messageSnapshot: obscureSensitiveData( message ),
+        messageSnapshot: messageSnapshot,
         messageState: tools.getEnumName( messageStateEnum, messageState ),
         messageType: tools.getEnumName( messageTypeEnum, messageType ),
         toAddress: ( messageType === messageTypeEnum.MESSAGE_REQUEST ) ? destination : source,
+        traceTimestamp: currentDate.getTime(),
         traceID: tools.getUUID()
     };
 
+    // only write the trace in the general log if this is enabled:
     if ( config.getSetting( config.setting.MESSAGE_EXCHANGE_TRACE_LOG_ENABLED ) === true ) {
-        createLogEntry( traceEntry, ( dispatchEvent === dispatchEventEnum.FAILED ) ? logger.logSeverity.ERROR : logger.logSeverity.DEBUG );
+        createLogEntry( traceEntry, ( dispatchEvent === dispatchEventEnum.FAILED ) ? logger.logSeverity.ERROR : logger.logSeverity.NOTICE );
     }
 
-    // TODO Feature: Functionality that can dispatch the trace entry to a configurable database and/or monitoring system.
+    // add the trace entry to the repository in the memory cache:
+    cache.setJSON( config.getSetting( config.setting.MESSAGE_EXCHANGE_TRACE_REPOSITORY ), traceRoot, "$", 1 ).then( () => {
+        return cache.arrayAppendJSON( config.getSetting( config.setting.MESSAGE_EXCHANGE_TRACE_REPOSITORY ), traceEntry, "$.trace" );
+    } ).then( () => {
+        // this will refresh the expiration time for the trace repository on each new record:
+        let expiration = config.getSetting( config.setting.MESSAGE_EXCHANGE_TRACE_EXPIRATION_TIME );
+        return ( expiration > 0 ) ? cache.expireValue( config.getSetting( config.setting.MESSAGE_EXCHANGE_TRACE_REPOSITORY ), expiration ) : expiration;
+    } ).catch( ( error ) => {
+        if ( error.code === exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED ) {
+            cache.addToSet( config.getSetting( config.setting.MESSAGE_EXCHANGE_TRACE_REPOSITORY ), traceEntry ).catch( ( error ) => {
+                logger.log( `Failed to add message trace entry to the trace repository. While this will not prevent the application from running, it might still be a sign of a more serious problem!`, logger.logSeverity.WARNING, error );
+            } );
+        } else {
+            logger.log( `Failed to add message trace entry to the trace repository. While this will not prevent the application from running, it might still be a sign of a more serious problem!`, logger.logSeverity.WARNING, error );
+        }
+    } );
+
 };

package/components/service-caller.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/service-consumer.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/components/service-executor.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 
@@ -102,12 +102,18 @@ class ServiceExecutor extends MessageObserver {
     onConnectionRecovered( identifier ) {
         super.onConnectionRecovered( identifier );
 
-        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 );
-            } );
-        } );
+        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.
+            }
+        }
     }
 
     /**

package/components/service-instance.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 
@@ -269,10 +269,12 @@ class ServiceInstance {
      * @private
      */
     #reportHealthy() {
-        let timestamp = new Date();
-        cache.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 );
-        } );
+        if ( cache.isOperational ) {
+            let timestamp = new Date();
+            cache.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 );
+            } );
+        }
     }
 
 }

package/components/service-provider.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/integrations/gcloud-integration.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/integrations/redis-integration.js

@@ -1,10 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 
 const ConnectionObserver = require( "#connection-observer" );
-const ioredis = require( "ioredis" );
+const Redis = require( "ioredis" );
 const tools = require( "#tools" );
 const logger = require( "#logger" );
 const exceptions = require( "#exceptions" );
@@ -19,6 +19,7 @@ const _ = require( "lodash" );
 let cacheCommandsEnum = tools.enum( {
     ADD_TO_SET: [ "sadd", "add to set", "https://redis.io/commands/sadd" ],
     DELETE_VALUE: [ "del", "delete value", "https://redis.io/commands/del" ],
+    EXPIRE: [ "expire", "expire", "https://redis.io/commands/expire" ],
     GET_ALL_FROM_SET: [ "smembers", "get all set members", "https://redis.io/commands/smembers" ],
     GET_VALUE: [ "get", "get value", "https://redis.io/commands/get" ],
     HASH_GET: [ "hget", "hash get", "https://redis.io/commands/hget" ],
@@ -27,6 +28,9 @@ let cacheCommandsEnum = tools.enum( {
     HASH_SET: [ "hset", "", "https://redis.io/commands/hset" ],
     HASH_SET_MANY: [ "hmset", "", "https://redis.io/commands/hmset" ],
     IS_SET_MEMBER: [ "sismember", "", "https://redis.io/commands/sismember" ],
+    JSON_ARRAY_APPEND: [ "json.arrappend", "", "https://redis.io/commands/json.arrappend" ],
+    JSON_GET: [ "json.get", "", "https://redis.io/commands/json.get" ],
+    JSON_SET: [ "json.set", "", "https://redis.io/commands/json.set" ],
     KEYS: [ "keys", "", "https://redis.io/commands/keys" ],
     LIST_PUSH: [ "lpush", "list push", "https://redis.io/commands/lpush" ],
     LIST_POP_TAIL_BLOCKING: [ "brpop", "list pop tail blocking", "https://redis.io/commands/brpop" ],
@@ -36,10 +40,26 @@ let cacheCommandsEnum = tools.enum( {
     UNION_OF_SETS: [ "sunion", "union of sets", "https://redis.io/commands/sunion" ]
 } );
 
+/**
+ * Enum for listing the Redis key override modes.
+ *
+ * @readonly
+ * @enum {string}
+ */
+let cacheOverrideModeEnum = tools.enum( {
+    DEFAULT: [ "", "default", "Standard Redis behaviour when setting new key." ],
+    NX: [ "nx", "nx", "Sets the key only if it does not already exist." ],
+    XX: [ "xx", "xx", "Sets the key only if it already exists." ]
+} );
+
 /**
  * @typedef {string} TiRedisCommand
  */
 module.exports.cacheCommands = cacheCommandsEnum;
+/**
+ * @typedef {string} TiRedisOverrideMode
+ */
+module.exports.cacheOverrideMode = cacheOverrideModeEnum;
 
 /**
  * Used to create a Redis Cache client.
@@ -49,10 +69,12 @@ module.exports.cacheCommands = cacheCommandsEnum;
  */
 class RedisClient {
 
-    #clientIdentifier = "default";
+    #clientIdentifier;
     #retryMaxInterval = 1000;
     #retryMaxAttempts = undefined;
     #redisClient = undefined;
+    #serverInfo = {};
+    #serverFeatures = {};
     #connectionObservers = [];
 
     /**
@@ -61,12 +83,13 @@ class RedisClient {
      * @param {string} host
      * @param {number} port
      * @param {string} authKey
+     * @param {string} user
      * @param {number} defaultDB
      * @param {boolean} autoRetryUnfulfilled
      * @param {number} maxRetries
      */
-    constructor( identifier, host, port, authKey, defaultDB, autoRetryUnfulfilled, maxRetries ) {
-        this.#clientIdentifier = identifier || this.#clientIdentifier;
+    constructor( identifier, host, port, authKey, user, defaultDB, autoRetryUnfulfilled, maxRetries ) {
+        this.#clientIdentifier = identifier || "redis-client-" + tools.getUUID();
 
         let retryStrategy = ( attempt ) => {
             let result = Math.min( attempt * 50, this.#retryMaxInterval );
@@ -87,6 +110,7 @@ class RedisClient {
         let options = {
             port: port,
             host: host,
+            username: user,
             password: authKey,
             db: defaultDB,
             autoResendUnfulfilledCommands: autoRetryUnfulfilled,
@@ -96,23 +120,43 @@ class RedisClient {
         };
 
         /** @type Redis */
-        this.#redisClient = new ioredis( options );
+        this.#redisClient = new Redis( options );
 
         this.#redisClient.on( "ready", () => {
-            logger.log( `Connection to Redis server ${ host }:${ port } (re)established by client '${ this.identifier }' and is ready to be used.`, logger.logSeverity.INFO, {
-                redis_version: this.#redisClient.serverInfo.redis_version,
-                redis_mode: this.#redisClient.serverInfo.redis_mode,
-                os: this.#redisClient.serverInfo.os,
-                uptime_in_days: this.#redisClient.serverInfo.uptime_in_days,
-                connected_clients: this.#redisClient.serverInfo.connected_clients,
-                role: this.#redisClient.serverInfo.role,
-                connected_slaves: this.#redisClient.serverInfo.connected_slaves
-            } );
+            logger.log( `Connection to Redis server ${ host }:${ port } (re)established by client '${ this.identifier }' and is ready to be used.`, logger.logSeverity.INFO );
 
             // notify all connection observers about this event:
             _.forEach( this.#connectionObservers, ( connectionObservers ) => {
                 connectionObservers.onConnectionRecovered( this.#clientIdentifier );
             } );
+
+            // fetch the server information and store it:
+            this.#redisClient.info().then( ( result ) => {
+                this.#serverInfo = {};
+                if ( _.isString( result ) ) {
+                    let rawData = _.split( result, "\r\n" );
+                    _.forEach( rawData, ( entry ) => {
+                        let details = _.split( entry, ":" );
+                        if ( !_.startsWith( details[ 0 ], "#" ) && details[ 0 ] !== "" && details[ 0 ] ) {
+                            if ( _.isNaN( _.toNumber( details[ 1 ] ) ) ) {
+                                this.#serverInfo[ details[ 0 ] ] = details[ 1 ];
+                            } else {
+                                this.#serverInfo[ details[ 0 ] ] = _.toNumber( details[ 1 ] );
+                            }
+                        }
+                    } );
+                }
+                return this.#redisClient.module( "LIST" );
+            } ).then( ( result ) => {
+                this.#serverFeatures = {};
+                if ( _.isArray( result ) ) {
+                    _.forEach( result, ( entry ) => {
+                        this.#serverFeatures[ entry[ 1 ] ] = entry[ 3 ];
+                    } );
+                }
+            } ).catch( ( error ) => {
+                logger.log( `Failed to fetch server information by client '${ this.identifier }'!`, logger.logSeverity.WARNING, error );
+            } );
         } );
         this.#redisClient.on( "error", ( error ) => {
             logger.log( `Error received in Redis client '${ this.identifier }'.`, logger.logSeverity.ERROR, error );
@@ -142,6 +186,28 @@ class RedisClient {
         return this.#clientIdentifier;
     }
 
+    /**
+     * Used to return the Redis server version.
+     *
+     * @property
+     * @return {number}
+     * @public
+     */
+    get serverVersion() {
+        return this.#serverInfo[ "redis_version" ];
+    }
+
+    /**
+     * Verify if Redis server supports JSON data types.
+     *
+     * @property
+     * @returns {boolean}
+     * @public
+     */
+    get isJSONSupported() {
+        return !_.isNil( this.#serverFeatures[ "ReJSON" ] );
+    }
+
     /**
      * Used to register a new {@link ConnectionObserver} for events related to the Redis connection state.
      *
@@ -177,6 +243,7 @@ class RedisClient {
 
     /**
      * Used to send a new blocking command to Redis.
+     * <br/>
      * WARNING: This will reserve the client connection until a result is received.
      *
      * @method
@@ -240,6 +307,28 @@ class RedisClient {
         } );
     }
 
+    /**
+     * Used to execute any Redis command in an unmanaged way.
+     * <br/>
+     * WARNING: Use this only if there is no other implemented function in this module and the command
+     * you want to execute is not supported by the 'multi' Redis command (implemented in {@link RedisClient.executeCommands}).
+     * Make sure to handle the result as it will be returned raw.
+     *
+     * @method
+     * @param {string[]} commandArguments
+     * @returns {Promise<Object>}
+     * @public
+     */
+    callCommand( commandArguments ) {
+        return new Promise( ( resolve, reject ) => {
+            this.#redisClient[ "call" ].apply( this.#redisClient, commandArguments ).then( ( result ) => {
+                resolve( result );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
 }
 
 /**
@@ -250,12 +339,13 @@ class RedisClient {
  * @param {string} host
  * @param {number} [port=6379]
  * @param {string} [authKey=undefined]
+ * @param {string} [user="default"]
  * @param {number} [defaultDB=0]
  * @param {boolean} [autoRetryUnfulfilled=true]
  * @param {number} [maxRetries=20]
  * @return {RedisClient}
  * @public
  */
-module.exports.createRedisClient = ( identifier, host, port = 6379, authKey = undefined, defaultDB = 0, autoRetryUnfulfilled = true, maxRetries = 20 ) => {
-    return Object.freeze( new RedisClient( identifier, host, port, authKey, defaultDB, autoRetryUnfulfilled, maxRetries ) );
+module.exports.createRedisClient = ( identifier, host, port = 6379, authKey = undefined, user = "default", defaultDB = 0, autoRetryUnfulfilled = true, maxRetries = 20 ) => {
+    return Object.freeze( new RedisClient( identifier, host, port, authKey, user, defaultDB, autoRetryUnfulfilled, maxRetries ) );
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.0.11",
+  "version": "1.1.0",
   "description": "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.",
   "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
   "license": "ISC",
@@ -41,15 +41,16 @@
     "#tools": "./utils/tools.js"
   },
   "dependencies": {
-    "blake2": "^4.1.0",
-    "dotenv": "^14.1.0",
-    "fs-extra": "^10.0.0",
+    "blake2": "^5.0.0",
+    "dotenv": "^16.3.1",
+    "fs-extra": "^11.1.1",
     "lodash": "^4.17.21",
-    "node-schedule": "^2.1.0",
-    "ioredis": "^4.28.3"
+    "node-schedule": "^2.1.1",
+    "ioredis": "^5.3.2"
   },
   "optionalDependencies": {
-    "@google-cloud/error-reporting": "^2.0.4"
+    "@google-cloud/error-reporting": "^3.0.5",
+    "zeromq": "^6.0.0-beta.19"
   },
   "repository": {
     "type": "git",

package/utils/cache.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 
@@ -23,6 +23,7 @@ class CommonMemoryCache extends ConnectionObserver {
     static #instance = null;
     #redisClient = null;
     #isOperational = false;
+    #connectionIdentifier = "system-cache";
 
     /**
      * @constructor
@@ -36,7 +37,8 @@ class CommonMemoryCache extends ConnectionObserver {
             let port = config.getSetting( config.setting.MEMORY_CACHE_REDIS_PORT );
             let db = config.getSetting( config.setting.MEMORY_CACHE_REDIS_DB );
             let authKey = config.getSetting( config.setting.MEMORY_CACHE_AUTH_KEY );
-            this.#redisClient = redis.createRedisClient( "system", host, port, authKey, db );
+            let user = config.getSetting( config.setting.MEMORY_CACHE_USER );
+            this.#redisClient = redis.createRedisClient( this.#connectionIdentifier, host, port, authKey, user, db );
             this.#redisClient.addConnectionObserver( this );
             CommonMemoryCache.#instance = this;
         }
@@ -54,6 +56,15 @@ class CommonMemoryCache extends ConnectionObserver {
      */
     get isOperational() { return this.#isOperational; }
 
+    /**
+     * Property returning the connection identifier of the cache service.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get connectionIdentifier() { return this.#connectionIdentifier; }
+
     /**
      * Needs to be invoked by the connection handler when the connection is disrupted.
      *
@@ -63,7 +74,9 @@ class CommonMemoryCache extends ConnectionObserver {
      * @public
      */
     onConnectionDisrupted( identifier ) {
-        this.#isOperational = false;
+        if ( identifier === this.#connectionIdentifier ) {
+            this.#isOperational = false;
+        }
     }
 
     /**
@@ -75,7 +88,9 @@ class CommonMemoryCache extends ConnectionObserver {
      * @public
      */
     onConnectionRecovered( identifier ) {
-        this.#isOperational = true;
+        if ( identifier === this.#connectionIdentifier ) {
+            this.#isOperational = true;
+        }
     }
 
     /**
@@ -263,6 +278,32 @@ class CommonMemoryCache extends ConnectionObserver {
         } );
     }
 
+    /**
+     * Used to set expiration in seconds to an existing key.
+     * <br/>
+     * NOTE: For performance optimization reasons, only use this only if the Redis command does not itself support the 'EX' argument.
+     *
+     * @method
+     * @param {string} key
+     * @param {number} seconds
+     * @returns {Promise<number>} This will resolve with the seconds as provided initially by the caller.
+     * @public
+     */
+    expireValue( key, seconds ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#isOperational === true ) {
+                let commandExpire = [ redis.cacheCommands.EXPIRE, key, seconds ];
+                this.#redisClient.executeCommands( [ commandExpire ] ).then( () => {
+                    resolve( seconds );
+                } ).catch( ( error ) => {
+                    reject( error );
+                } );
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
+            }
+        } );
+    }
+
     /**
      * Used to add the specified values to a list.
      *
@@ -298,7 +339,7 @@ class CommonMemoryCache extends ConnectionObserver {
      *
      * @method
      * @param {string} key
-     * @param {string} value
+     * @param {string|Object} value
      * @returns {Promise}
      * @public
      */
@@ -501,6 +542,104 @@ class CommonMemoryCache extends ConnectionObserver {
             }
         } );
     }
+
+    /**
+     * Used to store a JSON variable.
+     * <br/>
+     * NOTE: Requires ReJSON module installed on server to work.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} value
+     * @param {string} [path='&']
+     * @param {number} [overrideMode=0] By default this allows full override for existing keys.
+     * Option 1 will set the key only if it doesn't already exist. Option 2 will set it only if it already exists.
+     * @returns {Promise}
+     * @public
+     */
+    setJSON( key, value, path = "$", overrideMode = 0 ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#isOperational === true ) {
+                if ( this.#redisClient.isJSONSupported ) {
+                    let commandArguments = [ redis.cacheCommands.JSON_SET, key, path, tools.stringifyJSON( value ) ];
+                    if ( overrideMode !== 0 ) {
+                        commandArguments.push( overrideMode === 1 ? redis.cacheOverrideMode.NX : redis.cacheOverrideMode.XX );
+                    }
+                    this.#redisClient.callCommand( commandArguments ).then( () => {
+                        resolve();
+                    } ).catch( ( error ) => {
+                        reject( error );
+                    } );
+                } else {
+                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED ), { details: "No RedisJSON module installed on server." } );
+                }
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
+            }
+        } );
+    }
+
+    /**
+     * Used to fetch a JSON variable.
+     * <br/>
+     * NOTE: Requires ReJSON module installed on server to work.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} path
+     * @returns {Promise<Object>}
+     * @public
+     */
+    getJSON( key, path = "$" ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#isOperational === true ) {
+                if ( this.#redisClient.isJSONSupported ) {
+                    let commandArguments = [ redis.cacheCommands.JSON_GET, key, path ];
+                    this.#redisClient.callCommand( commandArguments ).then( ( result ) => {
+                        resolve( tools.parseJSON( result ) );
+                    } ).catch( ( error ) => {
+                        reject( error );
+                    } );
+                } else {
+                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED ), { details: "No RedisJSON module installed on server." } );
+                }
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
+            }
+        } );
+    }
+
+    /**
+     * Used to add an item to a JSON array. That array needs to exist already.
+     * <br/>
+     * NOTE: Requires ReJSON module installed on server to work.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} value
+     * @param {string} path
+     * @returns {Promise}
+     * @public
+     */
+    arrayAppendJSON( key, value, path = "$" ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#isOperational === true ) {
+                if ( this.#redisClient.isJSONSupported ) {
+                    let commandArguments = [ redis.cacheCommands.JSON_ARRAY_APPEND, key, path, tools.stringifyJSON( value ) ];
+                    this.#redisClient.callCommand( commandArguments ).then( () => {
+                        resolve();
+                    } ).catch( ( error ) => {
+                        reject( error );
+                    } );
+                } else {
+                    reject( exceptions.raise( exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED ), { details: "No RedisJSON module installed on server." } );
+                }
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
+            }
+        } );
+    }
+
 }
 
 const instance = new CommonMemoryCache();

package/utils/config.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 
@@ -27,6 +27,7 @@ const tools = require( "#tools" );
  * @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_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
@@ -67,6 +68,7 @@ const tools = require( "#tools" );
  * @property {number} redisDB
  * @property {string} redisHost
  * @property {number} redisPort
+ * @property {string} user
  */
 
 /**
@@ -75,7 +77,9 @@ const tools = require( "#tools" );
  * @property {string} messageStore
  * @property {boolean} securityHashEnabled
  * @property {string} securityHashKey
+ * @property {number} traceExpirationTime
  * @property {boolean} traceLogEnabled
+ * @property {string} traceRepository
  */
 
 /**
@@ -104,11 +108,14 @@ let settingsEnum = tools.enum( {
     MEMORY_CACHE_REDIS_DB: [ "memoryCache.redisDB", "redisDB", "" ],
     MEMORY_CACHE_REDIS_HOST: [ "memoryCache.redisHost", "redisHost", "" ],
     MEMORY_CACHE_REDIS_PORT: [ "memoryCache.redisPort", "redisPort", "" ],
+    MEMORY_CACHE_USER: [ "memoryCache.user", "user", "" ],
     MESSAGE_EXCHANGE_QUEUE_PREFIX: [ "messageExchange.messageQueuePrefix", "messageQueuePrefix", "" ],
     MESSAGE_EXCHANGE_MESSAGE_STORE: [ "messageExchange.messageStore", "messageStore", "" ],
     MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED: [ "messageExchange.securityHashEnabled", "securityHashEnabled", "" ],
     MESSAGE_EXCHANGE_SECURITY_HASH_KEY: [ "messageExchange.securityHashKey", "securityHashKey", "" ],
+    MESSAGE_EXCHANGE_TRACE_EXPIRATION_TIME: [ "messageExchange.traceExpirationTime", "traceExpirationTime", "" ],
     MESSAGE_EXCHANGE_TRACE_LOG_ENABLED: [ "messageExchange.traceLogEnabled", "traceLogEnabled", "" ],
+    MESSAGE_EXCHANGE_TRACE_REPOSITORY: [ "messageExchange.traceRepository", "traceRepository", "" ],
     SERVICE_EXECUTION_TIMEOUT: [ "serviceConfig.executionTimeout", "executionTimeout", "" ],
     SERVICE_HEALTH_CHECK_ADDRESS: [ "serviceConfig.healthCheckAddress", "healthCheckAddress", "" ],
     SERVICE_HEALTH_CHECK_INTERVAL: [ "serviceConfig.healthCheckInterval", "healthCheckInterval", "" ],
@@ -136,6 +143,7 @@ if ( settings.memoryCache ) {
     settings.memoryCache.redisDB = ( process.env.TI_MEMORY_CACHE_REDIS_DB !== undefined ) ? process.env.TI_MEMORY_CACHE_REDIS_DB : settings.memoryCache.redisDB;
     settings.memoryCache.redisHost = ( process.env.TI_MEMORY_CACHE_REDIS_HOST !== undefined ) ? process.env.TI_MEMORY_CACHE_REDIS_HOST : settings.memoryCache.redisHost;
     settings.memoryCache.redisPort = ( process.env.TI_MEMORY_CACHE_REDIS_PORT !== undefined ) ? process.env.TI_MEMORY_CACHE_REDIS_PORT : settings.memoryCache.redisPort;
+    settings.memoryCache.user = ( process.env.TI_MEMORY_CACHE_USER !== undefined ) ? process.env.TI_MEMORY_CACHE_USER : settings.memoryCache.user;
 }
 if ( settings.messageExchange ) {
     settings.messageExchange.securityHashEnabled = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED ) : settings.messageExchange.securityHashEnabled;

package/utils/exceptions.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 
@@ -21,6 +21,7 @@ let exceptionCodeEnum = tools.enum( {
     E_GEN_INVALID_SERVICE_DOMAIN_NAME: [ 1003, "invalid service domain name", "Invalid or no service domain name provided at microservice startup." ],
     E_GEN_SYSTEM_CACHE_UNAVAILABLE: [ 1004, "system cache unavailable", "The system cache required for proper engine operation is unavailable." ],
     E_GEN_BAD_SERVICE_HANDLER: [ 1005, "bad service handler", "The provided service handler is not a proper function." ],
+    E_GEN_FEATURE_UNSUPPORTED: [ 1006, "feature unsupported", "The requested feature is not supported by current configuration or version." ],
     /** Security & Administration related 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." ],

package/utils/logger.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */
 

package/utils/tools.js

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
  * SPDX-License-Identifier: ICU
  */