@ti-engine/core 1.0.14 → 1.1.0

package/CHANGELOG.md

@@ -1,18 +1,44 @@
 # 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
@@ -21,4 +47,5 @@
 * docs: add a change log
 
 ## Version 1.0.0
+
 * feat: create initial version of the framework

package/bin/settings.json

@@ -23,7 +23,9 @@
     "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
  */
 

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
  */
 

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
  */
 

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
  */
 

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,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
  */
 
@@ -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.
@@ -53,6 +73,8 @@ class RedisClient {
     #retryMaxInterval = 1000;
     #retryMaxAttempts = undefined;
     #redisClient = undefined;
+    #serverInfo = {};
+    #serverFeatures = {};
     #connectionObservers = [];
 
     /**
@@ -101,13 +123,40 @@ class RedisClient {
         this.#redisClient = new Redis( options );
 
         this.#redisClient.on( "ready", () => {
-            let serverInfo = this.#redisClient.serverInfo || {};
-            logger.log( `Connection to Redis server ${ host }:${ port } (re)established by client '${ this.identifier }' and is ready to be used.`, logger.logSeverity.INFO, serverInfo );
+            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 );
@@ -137,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.
      *
@@ -172,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
@@ -235,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 ) );
+            } );
+        } );
+    }
+
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.0.14",
+  "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",
@@ -50,7 +50,7 @@
   },
   "optionalDependencies": {
     "@google-cloud/error-reporting": "^3.0.5",
-    "zeromq": "^6.0.0-beta.17"
+    "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
  */
 
@@ -278,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.
      *
@@ -313,7 +339,7 @@ class CommonMemoryCache extends ConnectionObserver {
      *
      * @method
      * @param {string} key
-     * @param {string} value
+     * @param {string|Object} value
      * @returns {Promise}
      * @public
      */
@@ -516,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
@@ -76,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
  */
 
 /**
@@ -110,7 +113,9 @@ let settingsEnum = tools.enum( {
     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", "" ],
@@ -138,7 +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.MEMORY_CACHE_USER !== undefined ) ? process.env.MEMORY_CACHE_USER : settings.memoryCache.user;
+    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
  */