@ti-engine/core 1.1.4 → 1.1.8

package/components/exchange/message-exchange.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
 
 const MessageObserver = require( "#message-observer" );
 const _ = require( "lodash" );
@@ -92,7 +95,9 @@ class MessageExchange extends MessageObserver {
      * @returns {string}
      * @public
      */
-    static get connectionNameRequestsOut() { return this.#connectionNameRequestsOut; }
+    static get connectionNameRequestsOut() {
+        return this.#connectionNameRequestsOut;
+    }
 
     /**
      * Used to set the connection name for the outgoing message requests.
@@ -101,7 +106,9 @@ class MessageExchange extends MessageObserver {
      * @param {string} value
      * @public
      */
-    static set connectionNameRequestsOut( value ) { this.#connectionNameRequestsOut = value; }
+    static set connectionNameRequestsOut( value ) {
+        this.#connectionNameRequestsOut = value;
+    }
 
     /**
      * Property returning the configured connection name for the incoming message requests.
@@ -110,7 +117,9 @@ class MessageExchange extends MessageObserver {
      * @returns {string}
      * @public
      */
-    static get connectionNameRequestsIn() { return this.#connectionNameRequestsIn; }
+    static get connectionNameRequestsIn() {
+        return this.#connectionNameRequestsIn;
+    }
 
     /**
      * Used to set the connection name for the incoming message requests.
@@ -119,7 +128,9 @@ class MessageExchange extends MessageObserver {
      * @param {string} value
      * @public
      */
-    static set connectionNameRequestsIn( value ) { this.#connectionNameRequestsIn = value; }
+    static set connectionNameRequestsIn( value ) {
+        this.#connectionNameRequestsIn = value;
+    }
 
     /**
      * Property returning the configured connection name for the outgoing message responses.
@@ -128,7 +139,9 @@ class MessageExchange extends MessageObserver {
      * @returns {string}
      * @public
      */
-    static get connectionNameResponsesOut() { return this.#connectionNameResponsesOut; }
+    static get connectionNameResponsesOut() {
+        return this.#connectionNameResponsesOut;
+    }
 
     /**
      * Used to set the connection name for the outgoing message responses.
@@ -137,7 +150,9 @@ class MessageExchange extends MessageObserver {
      * @param {string} value
      * @public
      */
-    static set connectionNameResponsesOut( value ) { this.#connectionNameResponsesOut = value; }
+    static set connectionNameResponsesOut( value ) {
+        this.#connectionNameResponsesOut = value;
+    }
 
     /**
      * Property returning the configured connection name for the incoming message responses.
@@ -146,7 +161,9 @@ class MessageExchange extends MessageObserver {
      * @returns {string}
      * @public
      */
-    static get connectionNameResponsesIn() { return this.#connectionNameResponsesIn; }
+    static get connectionNameResponsesIn() {
+        return this.#connectionNameResponsesIn;
+    }
 
     /**
      * Used to set the connection name for the incoming message responses.
@@ -155,7 +172,9 @@ class MessageExchange extends MessageObserver {
      * @param {string} value
      * @public
      */
-    static set connectionNameResponsesIn( value ) { this.#connectionNameResponsesIn = value; }
+    static set connectionNameResponsesIn( value ) {
+        this.#connectionNameResponsesIn = value;
+    }
 
     /**
      * Property returning the identifier of the pending messages queue.
@@ -164,7 +183,9 @@ class MessageExchange extends MessageObserver {
      * @returns {string}
      * @public
      */
-    static get pendingQueue() { return "pending:"; }
+    static get pendingQueue() {
+        return "pending:";
+    }
 
     /**
      * Property returning the identifier of the processed messages queue.
@@ -173,7 +194,9 @@ class MessageExchange extends MessageObserver {
      * @returns {string}
      * @public
      */
-    static get processedQueue() { return "processed:"; }
+    static get processedQueue() {
+        return "processed:";
+    }
 
     /**
      * Property returning the configured service instance ID.
@@ -182,7 +205,9 @@ class MessageExchange extends MessageObserver {
      * @returns {string}
      * @public
      */
-    get instanceID() { return this.#instanceID; }
+    get instanceID() {
+        return this.#instanceID;
+    }
 
     /**
      * Property returning the configured service domain name.
@@ -191,7 +216,9 @@ class MessageExchange extends MessageObserver {
      * @returns {string}
      * @public
      */
-    get serviceDomainName() { return this.#serviceDomainName; }
+    get serviceDomainName() {
+        return this.#serviceDomainName;
+    }
 
     /**
      * Returns the currently configured {@link MessageSender} for outbound message requests.
@@ -200,7 +227,9 @@ class MessageExchange extends MessageObserver {
      * @returns {MessageSender}
      * @public
      */
-    get messageRequestsOut() { return this.#messageRequestsOut; }
+    get messageRequestsOut() {
+        return this.#messageRequestsOut;
+    }
 
     /**
      * Returns the currently configured {@link MessageSender} for outbound message responses.
@@ -209,7 +238,9 @@ class MessageExchange extends MessageObserver {
      * @returns {MessageSender}
      * @public
      */
-    get messageResponsesOut() { return this.#messageResponsesOut; }
+    get messageResponsesOut() {
+        return this.#messageResponsesOut;
+    }
 
     /**
      * Returns the currently configured {@link MessageReceiver} for inbound message requests.
@@ -218,7 +249,9 @@ class MessageExchange extends MessageObserver {
      * @returns {MessageReceiver}
      * @public
      */
-    get messageRequestsIn() { return this.#messageRequestsIn; }
+    get messageRequestsIn() {
+        return this.#messageRequestsIn;
+    }
 
     /**
      * Returns the currently configured {@link MessageReceiver} for inbound message responses.
@@ -227,7 +260,9 @@ class MessageExchange extends MessageObserver {
      * @returns {MessageReceiver}
      * @public
      */
-    get messageResponsesIn() { return this.#messageResponsesIn; }
+    get messageResponsesIn() {
+        return this.#messageResponsesIn;
+    }
 
     /**
      * Returns a flag indicating if the message exchange is configured for outbound communication.
@@ -236,7 +271,9 @@ class MessageExchange extends MessageObserver {
      * @returns {boolean}
      * @public
      */
-    get configuredOutbound() { return this.#configuredOutbound; }
+    get configuredOutbound() {
+        return this.#configuredOutbound;
+    }
 
     /**
      * Returns a flag indicating if the message exchange is configured for inbound communication.
@@ -245,7 +282,9 @@ class MessageExchange extends MessageObserver {
      * @returns {boolean}
      * @public
      */
-    get configuredInbound() { return this.#configuredInbound; }
+    get configuredInbound() {
+        return this.#configuredInbound;
+    }
 
     /**
      * Should be used to enable all communication channels for messaging.
@@ -253,8 +292,8 @@ class MessageExchange extends MessageObserver {
      * NOTE: Override this to implement messaging initialization.
      *
      * @method
-     * @param {boolean} configureInbound If set to 'true' it tells the message exchange to setup inbound messaging.
-     * @param {boolean} configureOutbound If set to 'true' it tells the message exchange to setup outbound messaging.
+     * @param {boolean} configureInbound If set to 'true' it tells the message exchange to set up inbound messaging.
+     * @param {boolean} configureOutbound If set to 'true' it tells the message exchange to set up outbound messaging.
      * @returns {Promise}
      * @abstract
      * @public
@@ -368,9 +407,9 @@ class MessageExchange extends MessageObserver {
         message.destination.instanceID = this.#instanceID;
 
         if ( MessageExchange.connectionNameRequestsIn === identifier ) {
-            messageTracer.recordTraceEntry( message, messageTracer.messageType.MESSAGE_REQUEST, messageTracer.dispatchEvent.RECEIVED, messageTracer.messageState.PENDING );
+            messageTracer.instance.recordTraceEntry( message, messageTracer.messageType.MESSAGE_REQUEST, messageTracer.dispatchEvent.RECEIVED, messageTracer.messageState.PENDING );
         } else if ( MessageExchange.connectionNameResponsesIn === identifier ) {
-            messageTracer.recordTraceEntry( message, messageTracer.messageType.MESSAGE_RESPONSE, messageTracer.dispatchEvent.RECEIVED, messageTracer.messageState.PROCESSED );
+            messageTracer.instance.recordTraceEntry( message, messageTracer.messageType.MESSAGE_RESPONSE, messageTracer.dispatchEvent.RECEIVED, messageTracer.messageState.PROCESSED );
         }
     }
 
@@ -416,4 +455,4 @@ class MessageExchange extends MessageObserver {
 
 }
 
-module.exports = MessageExchange;
+module.exports = MessageExchange;

package/components/exchange/message-handler.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
 
 const ConnectionObserver = require( "#connection-observer" );
 const _ = require( "lodash" );
@@ -88,7 +91,7 @@ class MessageHandler extends ConnectionObserver {
     }
 
     /**
-     * Used to shutdown and disable the communication behavior of the handler.
+     * Used to shut down and disable the communication behavior of the handler.
      * <br/>
      * NOTE: Override this to add functionality.
      *

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

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
 
 const config = require( "#config" );
 const tools = require( "#tools" );
@@ -28,11 +31,25 @@ class MessageMemoryCache {
         let db = config.getSetting( config.setting.MEMORY_CACHE_REDIS_DB );
         let authKey = config.getSetting( config.setting.MEMORY_CACHE_AUTH_KEY );
         let user = config.getSetting( config.setting.MEMORY_CACHE_USER );
-        this.#redisClient = redis.createRedisClient( identifier, host, port, authKey, user, db );
+        let retryMaxAttempts = config.getSetting( config.setting.MEMORY_CACHE_RETRY_MAX_ATTEMPTS );
+        let retryMaxInterval = config.getSetting( config.setting.MEMORY_CACHE_RETRY_MAX_INTERVAL );
+        this.#redisClient = redis.createRedisClient( identifier, host, port, authKey, user, db, retryMaxInterval, retryMaxAttempts );
     }
 
     /* Public interface */
 
+    /**
+     * Used to gracefully shut down the cache service.
+     *
+     * @method
+     * @param {number} [timeoutMs]
+     * @return {Promise}
+     * @public
+     */
+    shutDown( timeoutMs ) {
+        return this.#redisClient.shutDown( timeoutMs );
+    }
+
     /**
      * Used to register a new {@link ConnectionObserver} for events related to the Redis connection state.
      *
@@ -71,7 +88,7 @@ class MessageMemoryCache {
      * @method
      * @param {Object} payload
      * @param {string} storeLocation
-     * @returns {Promise<string>} Will return an unique ID of the storage location for the payload.
+     * @returns {Promise<string>} Will return a unique ID of the storage location for the payload.
      * @public
      */
     storeMessagePayload( payload, storeLocation ) {
@@ -148,4 +165,4 @@ class MessageMemoryCache {
  */
 module.exports.create = ( identifier ) => {
     return Object.freeze( new MessageMemoryCache( identifier ) );
-};
+};

package/components/exchange/message-observer.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
 
 const ConnectionObserver = require( "#connection-observer" );
 const exceptions = require( "#exceptions" );

package/components/exchange/message-receiver.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
 
 const MessageHandler = require( "#message-handler" );
 const logger = require( "#logger" );
@@ -39,7 +42,7 @@ class MessageReceiver extends MessageHandler {
     /* Public interface */
 
     /**
-     * Property returning the configured receive queue.
+     * Property returning the configured receiving queue.
      *
      * @property
      * @returns {string}
@@ -62,7 +65,7 @@ class MessageReceiver extends MessageHandler {
     }
 
     /**
-     * Used to shutdown and disable the communication behavior of the handler.
+     * Used to shut down and disable the communication behavior of the handler.
      * <br/>
      * NOTE: Override this to add functionality.
      *

package/components/exchange/message-sender.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
 
 const MessageHandler = require( "#message-handler" );
 const exceptions = require( "#exceptions" );
@@ -47,7 +50,7 @@ class MessageSender extends MessageHandler {
     }
 
     /**
-     * Used to shutdown and disable the communication behavior of the handler.
+     * Used to shut down and disable the communication behavior of the handler.
      * <br/>
      * NOTE: Override this to add functionality.
      *

package/components/exchange/message-tracer.js

@@ -1,7 +1,10 @@
 /*
- * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
- * SPDX-License-Identifier: ICU
- */
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
 
 const _ = require( "lodash" );
 const tools = require( "#tools" );
@@ -79,103 +82,149 @@ let messageStateEnum = tools.enum( {
 module.exports.messageState = messageStateEnum;
 
 /**
- * Used to create a log entry from the trace entry.
- *
- * @method
- * @param {TiTraceEntry} traceEntry The trace entry to log.
- * @param {TiLogSeverity} severity The log entry severity.
- * @private
- */
-let createLogEntry = ( traceEntry, severity ) => {
-    logger.log( formatLogEntry( traceEntry ), severity, traceEntry );
-};
-
-/**
- * Used to format trace entry into log-suitable string.
+ * Used for recording message trace entries.
  *
- * @method
- * @param {TiTraceEntry} traceEntry
- * @return {string} Prepared trace info.
- * @private
+ * @class MessageTracer
+ * @singleton
+ * @public
  */
-let formatLogEntry = ( traceEntry ) => {
-    return `Message(${ traceEntry.chainID || traceEntry.messageID }) Trace: '${ traceEntry.messageType } ${ traceEntry.dispatchEvent } ${ traceEntry.messageState }' From: '${ traceEntry.fromAddress }' To: '${ traceEntry.toAddress }'`;
-};
+class MessageTracer {
 
-/**
- * Used to obscure sensitive data in the message, remove the payload, and return a snapshot.
- *
- * @method
- * @param {Message} message
- * @returns {Message}
- * @private
- */
-let obscureSensitiveData = ( message ) => {
-    /** @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;
-};
+    static #instance = null;
 
-/**
- * Used to create a trace entry for the provided {@link Message} and parameters.
- * <br/>
- * 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.
- * @param {TiMessageType} messageType The type of the message.
- * @param {TiDispatchEvent} dispatchEvent The event in the dispatch system that triggered the trace entry.
- * @param {TiMessageState} messageState The state of the processing of the message.
- * @public
- */
-module.exports.recordTraceEntry = ( message, messageType, dispatchEvent, messageState ) => {
-    // 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 = {
-        chainID: message.chainID,
-        dispatchEvent: tools.getEnumName( dispatchEventEnum, dispatchEvent ),
-        fromAddress: ( messageType === messageTypeEnum.MESSAGE_REQUEST ) ? source : destination,
-        messageID: message.messageID,
-        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.NOTICE );
+    /**
+     * @constructor
+     * @return {MessageTracer}
+     */
+    constructor() {
+        if ( !MessageTracer.#instance ) {
+            MessageTracer.#instance = this;
+        }
+        return MessageTracer.#instance;
     }
 
-    // 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 );
+    /* Public interface */
+
+    /**
+     * Used to initialize the message tracer.
+     *
+     * @method
+     * @returns {Promise}
+     * @public
+     */
+    initialize() {
+        return new Promise( ( resolve, reject ) => {
+            cache.instance.setJSON( config.getSetting( config.setting.MESSAGE_EXCHANGE_TRACE_REPOSITORY ), traceRoot, "$", 1 ).then( () => {
+                resolve();
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( 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 );
+        } );
+    }
+
+    /**
+     * Used to create a trace entry for the provided {@link Message} and parameters.
+     * <br/>
+     * 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.
+     * @param {TiMessageType} messageType The type of the message.
+     * @param {TiDispatchEvent} dispatchEvent The event in the dispatch system that triggered the trace entry.
+     * @param {TiMessageState} messageState The state of the message processing.
+     * @public
+     */
+    recordTraceEntry( message, messageType, dispatchEvent, messageState ) {
+        // 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 = MessageTracer.#obscureSensitiveData( message );
+        delete messageSnapshot.chainID;
+        delete messageSnapshot.messageID;
+        let currentDate = new Date();
+
+        /** @type TiTraceEntry */
+        let traceEntry = {
+            chainID: message.chainID,
+            dispatchEvent: tools.getEnumName( dispatchEventEnum, dispatchEvent ),
+            fromAddress: ( messageType === messageTypeEnum.MESSAGE_REQUEST ) ? source : destination,
+            messageID: message.messageID,
+            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 ) {
+            MessageTracer.#createLogEntry( traceEntry, ( dispatchEvent === dispatchEventEnum.FAILED ) ? logger.logSeverity.ERROR : logger.logSeverity.NOTICE );
         }
-    } );
 
-};
+        // Add the trace entry to the repository in the memory cache:
+        cache.instance.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.instance.expireValue( config.getSetting( config.setting.MESSAGE_EXCHANGE_TRACE_REPOSITORY ), expiration ) : expiration;
+        } ).catch( ( error ) => {
+            // If JSON is unsupported in Redis server, then try to store the trace entry in a Set:
+            if ( error.code === exceptions.exceptionCode.E_GEN_FEATURE_UNSUPPORTED ) {
+                cache.instance.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 );
+            }
+        } );
+    }
+
+    /* Private interface */
+
+    /**
+     * Used to create a log entry from the trace entry.
+     *
+     * @method
+     * @param {TiTraceEntry} traceEntry The trace entry to log.
+     * @param {TiLogSeverity} severity The log entry severity.
+     * @private
+     */
+    static #createLogEntry( traceEntry, severity ) {
+        logger.log( MessageTracer.#formatLogEntry( traceEntry ), severity, traceEntry );
+    }
+
+    /**
+     * Used to format trace entry into log-suitable string.
+     *
+     * @method
+     * @param {TiTraceEntry} traceEntry
+     * @return {string} Prepared trace info.
+     * @private
+     */
+    static #formatLogEntry( traceEntry ) {
+        return `Message(${ traceEntry.chainID || traceEntry.messageID }) Trace: '${ traceEntry.messageType } ${ traceEntry.dispatchEvent } ${ traceEntry.messageState }' From: '${ traceEntry.fromAddress }' To: '${ traceEntry.toAddress }'`;
+    }
+
+    /**
+     * Used to obscure sensitive data in the message, remove the payload, and return a snapshot.
+     *
+     * @method
+     * @param {Message} message
+     * @returns {Message}
+     * @private
+     */
+    static #obscureSensitiveData( message ) {
+        /** @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;
+    }
+
+}
+
+const instance = new MessageTracer();
+module.exports.instance = Object.freeze( instance );