@ti-engine/core 1.0.0

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

@@ -0,0 +1,150 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const config = require( "#config" );
+const tools = require( "#tools" );
+const exceptions = require( "#exceptions" );
+const redis = require( "#redis-integration" );
+
+/**
+ * Used to create a Redis Cache client wrapped in a specialized message memory cache interface.
+ *
+ * @class MessageMemoryCache
+ * @public
+ */
+class MessageMemoryCache {
+
+    #redisClient = null;
+
+    /**
+     * @constructor
+     * @param {string} identifier The connection identifier for the Redis connection.
+     */
+    constructor( identifier ) {
+        let host = config.getSetting( config.setting.MEMORY_CACHE_REDIS_HOST );
+        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 );
+    }
+
+    /* Public interface */
+
+    /**
+     * Used to register a new {@link ConnectionObserver} for events related to the Redis connection state.
+     *
+     * @method
+     * @param {ConnectionObserver} connectionObserver The {@link ConnectionObserver} that will be notified of any changes.
+     * @public
+     */
+    addConnectionObserver( connectionObserver ) {
+        this.#redisClient.addConnectionObserver( connectionObserver );
+    }
+
+    /**
+     * Used to send a message to the specified route.
+     *
+     * @method
+     * @param {Message} message The message to send.
+     * @param {string} queue The destination queue for the message as recognized by the {@link MessageExchange} implementation.
+     * @returns {Promise<number>} Will return the destination queue length after adding the current message to it.
+     * @public
+     */
+    sendMessage( message, queue ) {
+        return new Promise( ( resolve, reject ) => {
+            let command = [ redis.cacheCommands.LIST_PUSH, queue, tools.stringifyJSON( message ) ];
+            this.#redisClient.executeCommands( [ command ] ).then( ( results ) => {
+                results = results[ 0 ];
+                resolve( ( results && results.length > 1 ) ? results[ 1 ] : undefined );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to store a message payload.
+     *
+     * @method
+     * @param {Object} payload
+     * @param {string} storeLocation
+     * @returns {Promise<string>} Will return an unique ID of the storage location for the payload.
+     * @public
+     */
+    storeMessagePayload( payload, storeLocation ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( payload ) {
+                let storeID = tools.getUUID();
+                let command = [ redis.cacheCommands.HASH_SET, storeLocation, storeID, tools.stringifyJSON( payload ) ];
+                this.#redisClient.executeCommands( [ command ] ).then( () => {
+                    resolve( storeID );
+                } ).catch( ( error ) => {
+                    reject( exceptions.raise( error ) );
+                } );
+            } else {
+                resolve();
+            }
+        } );
+    }
+
+    /**
+     * Used to receive a message from the specified queue.
+     *
+     * @method
+     * @param {string} queue
+     * @returns {Promise<Message>}
+     * @public
+     */
+    receiveMessage( queue ) {
+        return new Promise( ( resolve, reject ) => {
+            this.#redisClient.blockingCommand( redis.cacheCommands.LIST_POP_TAIL_BLOCKING, [ queue, 0 ] ).then( ( results ) => {
+                results = ( results && results.length > 1 ) ? results[ 1 ] : undefined;
+                resolve( tools.parseJSON( results ) );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to retrieve a message payload by its store ID.
+     *
+     * @method
+     * @param {Message} message
+     * @param {string} storeLocation
+     * @returns {Promise<Message>} Will return the message with its payload populated if such is found.
+     * @public
+     */
+    retrieveMessagePayload( message, storeLocation ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( message.payload ) {
+                let command1 = [ redis.cacheCommands.HASH_GET, storeLocation, message.payload ];
+                let command2 = [ redis.cacheCommands.HASH_REMOVE, storeLocation, message.payload ];
+                this.#redisClient.executeCommands( [ command1, command2 ] ).then( ( results ) => {
+                    results = results[ 0 ];
+                    message.payload = ( results && results.length > 1 ) ? tools.parseJSON( results[ 1 ] ) : undefined;
+                    resolve( message );
+                } ).catch( ( error ) => {
+                    reject( exceptions.raise( error ) );
+                } );
+            } else {
+                resolve( message );
+            }
+        } );
+    }
+
+}
+
+/**
+ * Used to create a new message memory cache.
+ *
+ * @method
+ * @param {string} identifier The connection identifier for the Redis connection.
+ * @returns {MessageMemoryCache}
+ * @public
+ */
+module.exports.create = ( identifier ) => {
+    return Object.freeze( new MessageMemoryCache( identifier ) );
+};

package/components/exchange/message-observer.js

@@ -0,0 +1,76 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const ConnectionObserver = require( "#connection-observer" );
+const exceptions = require( "#exceptions" );
+
+/**
+ * An abstract class that allows the child class to observe and take action on message events.
+ * <br/>
+ * NOTE: This class inherits {@link ConnectionObserver} so it can also act in that capacity.
+ *
+ * @class MessageObserver
+ * @extends ConnectionObserver
+ * @abstract
+ * @public
+ */
+class MessageObserver extends ConnectionObserver {
+
+    /**
+     * @constructor
+     */
+    constructor() {
+        super();
+
+        // make sure this abstract class cannot be instantiated:
+        if ( new.target === MessageObserver ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
+        }
+    }
+
+    /**
+     * Needs to be invoked by the message handler once a message enters its logic for processing.
+     * <br/>
+     * NOTE: Override this to add custom functionality.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @param {Message} message The message for processing.
+     * @virtual
+     * @public
+     */
+    onMessage( identifier, message ) { }
+
+    /**
+     * Needs to be invoked by the connection handler when the connection is disrupted.
+     * <br/>
+     * NOTE: Override this to add custom functionality.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @virtual
+     * @public
+     */
+    onConnectionDisrupted( identifier ) {
+        super.onConnectionDisrupted( identifier );
+    }
+
+    /**
+     * Needs to be invoked by the connection handler when the connection is recovered.
+     * <br/>
+     * NOTE: Override this to add custom functionality.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @virtual
+     * @public
+     */
+    onConnectionRecovered( identifier ) {
+        super.onConnectionRecovered( identifier );
+    }
+
+}
+
+module.exports = MessageObserver;

package/components/exchange/message-receiver.js

@@ -0,0 +1,113 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const MessageHandler = require( "#message-handler" );
+const logger = require( "#logger" );
+const exceptions = require( "#exceptions" );
+
+/**
+ * An abstract class that defines a basic message receiver behavior.
+ *
+ * @class MessageReceiver
+ * @extends MessageHandler
+ * @abstract
+ * @public
+ */
+class MessageReceiver extends MessageHandler {
+
+    #receiveQueue;
+
+    /**
+     * @constructor
+     * @param {string} identifier An identifier for this message handler. Should be unique in the context of the message exchange.
+     * @param {string} receiveQueue The queue from which the messages will be received.
+     */
+    constructor( identifier, receiveQueue ) {
+        super( identifier );
+
+        // make sure this abstract class cannot be instantiated:
+        if ( new.target === MessageReceiver ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
+        }
+
+        this.#receiveQueue = receiveQueue;
+    }
+
+    /* Public interface */
+
+    /**
+     * Property returning the configured receive queue.
+     *
+     * @property
+     * @returns {string}
+     * @public
+     */
+    get receiveQueue() { return this.#receiveQueue; }
+
+    /**
+     * Used to initialize and enable the communication capabilities of the handler.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    enable() {
+        return super.enable();
+    }
+
+    /**
+     * Used to shutdown and disable the communication behavior of the handler.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    disable() {
+        return super.disable();
+    }
+
+    /**
+     * Used to receive messages.
+     * <br/>
+     * NOTE: This method will start a recursion of subsequent receives that will continue even if an individual message fetch fails.
+     *
+     * @method
+     * @public
+     */
+    receive() {
+        this.onReceive().then( ( message ) => {
+            this.onMessage( message );
+        } ).catch( ( error ) => {
+            logger.log( `Error while trying to receive the next pending message from memory cache in receiver '${ this.connectionIdentifier }'! Resuming operation...`, logger.logSeverity.ERROR, error );
+        } ).finally( () => {
+            this.receive();
+        } );
+    }
+
+    /**
+     * Used to receive messages.
+     * <br/>
+     * NOTE: This method will be called automatically even if overridden.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise<Message>}
+     * @abstract
+     * @public
+     */
+    onReceive() {
+        return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_METHOD_CALL, { name: this.constructor.name + "." + this.onReceive.name } ) );
+    }
+
+}
+
+module.exports = MessageReceiver;

package/components/exchange/message-sender.js

@@ -0,0 +1,133 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const MessageHandler = require( "#message-handler" );
+const exceptions = require( "#exceptions" );
+
+/**
+ * An abstract class that defines a basic message sender behavior.
+ *
+ * @class MessageSender
+ * @extends MessageHandler
+ * @abstract
+ * @public
+ */
+class MessageSender extends MessageHandler {
+
+    /**
+     * @constructor
+     * @param {string} identifier An identifier for this message handler. Should be unique in the context of the message exchange.
+     */
+    constructor( identifier ) {
+        super( identifier );
+
+        // make sure this abstract class cannot be instantiated:
+        if ( new.target === MessageSender ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
+        }
+    }
+
+    /* Public interface */
+
+    /**
+     * Used to initialize and enable the communication capabilities of the handler.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    enable() {
+        return super.enable();
+    }
+
+    /**
+     * Used to shutdown and disable the communication behavior of the handler.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    disable() {
+        return super.disable();
+    }
+
+    /**
+     * Used to send a {@link Message} via this message handler.
+     *
+     * @method
+     * @param {Message} message The message to send.
+     * @param {string} queue The route to destination (queue) for the message as recognized by the {@link MessageExchange} implementation.
+     * @returns {Promise}
+     * @public
+     */
+    send( message, queue ) {
+        return new Promise( ( resolve, reject ) => {
+            this.#preSend().then( () => {
+                return this.onSend( message, queue );
+            } ).then( () => {
+                return this.#postSend();
+            } ).then( () => {
+                resolve();
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to perform the actual sending of a message.
+     * <br/>
+     * NOTE: This method will be called automatically even if overridden.
+     * <br/>
+     * NOTE: Override this to add functionality.
+     *
+     * @method
+     * @param {Message} message The message to send.
+     * @param {string} queue The route to destination (queue) for the message as recognized by the {@link MessageExchange} implementation.
+     * @returns {Promise<*>}
+     * @abstract
+     * @public
+     */
+    onSend( message, queue ) {
+        return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_METHOD_CALL, { name: this.constructor.name + "." + this.onSend.name } ) );
+    }
+
+    /* Private interface */
+
+    /**
+     * Used to do pre-send verifications and checks.
+     *
+     * @method
+     * @returns {Promise}
+     * @private
+     */
+    #preSend() {
+        if ( this.isAvailable === true ) {
+            return Promise.resolve();
+        } else {
+            return Promise.reject( exceptions.raise( exceptions.exceptionCode.E_COM_MESSAGE_SENDER_UNAVAILABLE ) );
+        }
+    }
+
+    /**
+     * Used to execute post- successful send logic.
+     *
+     * @method
+     * @returns {Promise}
+     * @private
+     */
+    #postSend() {
+        return Promise.resolve();
+    }
+
+}
+
+module.exports = MessageSender;

package/components/exchange/message-tracer.js

@@ -0,0 +1,146 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const _ = require( "lodash" );
+const tools = require( "#tools" );
+const config = require( "#config" );
+const logger = require( "#logger" );
+
+/**
+ * @typedef {Object} TiTraceEntry
+ * @property {string} chainID
+ * @property {string} dispatchEvent
+ * @property {string} fromAddress
+ * @property {string} messageID
+ * @property {string} messageSnapshot
+ * @property {string} messageState
+ * @property {string} messageType
+ * @property {string} toAddress
+ * @property {string} traceID
+ */
+
+/**
+ * Enum for listing message types.
+ *
+ * @readonly
+ * @enum {number}
+ */
+let messageTypeEnum = tools.enum( {
+    MESSAGE_REQUEST: [ 1000, "REQUEST", "" ],
+    MESSAGE_RESPONSE: [ 1001, "RESPONSE", "" ]
+} );
+
+/**
+ * @typedef {number} TiMessageType
+ */
+module.exports.messageType = messageTypeEnum;
+
+/**
+ * Enum for listing dispatch events.
+ *
+ * @readonly
+ * @enum {number}
+ */
+let dispatchEventEnum = tools.enum( {
+    DELIVERED: [ 1100, "DELIVERED", "When message delivery is confirmed." ],
+    FAILED: [ 1101, "FAILED", "When message delivery has failed." ],
+    RECEIVED: [ 1102, "RECEIVED", "When message was received." ],
+    SENT: [ 1103, "SENT", "When message was sent." ]
+} );
+
+/**
+ * @typedef {number} TiDispatchEvent
+ */
+module.exports.dispatchEvent = dispatchEventEnum;
+
+/**
+ * Enum for listing message states.
+ *
+ * @readonly
+ * @enum {number}
+ */
+let messageStateEnum = tools.enum( {
+    PENDING: [ 1200, "PENDING", "" ],
+    PROCESSED: [ 1201, "PROCESSED", "" ]
+} );
+
+/**
+ * @typedef {number} TiMessageState
+ */
+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.
+ *
+ * @method
+ * @param {TiTraceEntry} traceEntry
+ * @return {string} Prepared trace info.
+ * @private
+ */
+let 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 snapshot and convert it to string.
+ *
+ * @method
+ * @param {Message} message
+ * @returns {string}
+ * @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\"" );
+};
+
+/**
+ * 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.
+ *
+ * @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 : "" );
+
+    /** @type TiTraceEntry */
+    let traceEntry = {
+        chainID: message.chainID,
+        dispatchEvent: tools.getEnumName( dispatchEventEnum, dispatchEvent ),
+        fromAddress: ( messageType === messageTypeEnum.MESSAGE_REQUEST ) ? source : destination,
+        messageID: message.messageID,
+        messageSnapshot: obscureSensitiveData( message ),
+        messageState: tools.getEnumName( messageStateEnum, messageState ),
+        messageType: tools.getEnumName( messageTypeEnum, messageType ),
+        toAddress: ( messageType === messageTypeEnum.MESSAGE_REQUEST ) ? destination : source,
+        traceID: tools.getUUID()
+    };
+
+    if ( config.getSetting( config.setting.MESSAGE_EXCHANGE_TRACE_LOG_ENABLED ) === true ) {
+        createLogEntry( traceEntry, ( dispatchEvent === dispatchEventEnum.FAILED ) ? logger.logSeverity.ERROR : logger.logSeverity.DEBUG );
+    }
+
+    // TODO Feature: Functionality that can dispatch the trace entry to a configurable database and/or monitoring system.
+};