@ti-engine/core 1.0.0

package/components/auditing.js

@@ -0,0 +1,163 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const _ = require( "lodash" );
+const tools = require( "#tools" );
+const logger = require( "#logger" );
+const config = require( "#config" );
+const gcloud = require( "#gcloud-integration" );
+
+/**
+ * @typedef {Object} LogEntry
+ * @property {string} _id Unique identifier that can be used to identify the document in a NoSQL database.
+ * @property {TiLogSeverity} severity The log severity level.
+ * @property {string} thread The categorization of the log message.
+ * @property {string} reporter
+ * @property {string} message The actual log message.
+ * @property {number} timestamp The timestamp of the log entry in UTC time.
+ * @property {Object} data Additional JSON data to accompany the message.
+ */
+
+/**
+ * Used to create and/or return an Auditing System singleton instance.
+ *
+ * @class Auditing
+ * @singleton
+ * @public
+ */
+class Auditing {
+
+    static #instance = null;
+
+    /**
+     * @constructor
+     * @returns {Auditing}
+     */
+    constructor() {
+        if ( !Auditing.#instance ) {
+            Auditing.#instance = this;
+        }
+        return Auditing.#instance;
+    }
+
+    /* Public interface */
+
+    /**
+     * Used to generate a log entry and dispatch it to all enabled logging destinations.
+     *
+     * @method
+     * @param {string} message The primary log message.
+     * @param {TiLogSeverity} [severity=DEFAULT] The log severity level. If the current log filtering setting is higher than this then the log entry will be ignored.
+     * @param {string} [thread='main'] The logging thread to which the log entry belongs.
+     * @param {Object} [data={}] Optional JSON data containing details of the log entry.
+     * @public
+     */
+    log( message, severity = logger.logSeverity.DEFAULT, thread = "main", data = {} ) {
+        try {
+            // log entries bellow the min allowed level will be ignored:
+            if ( severity >= config.getSetting( config.setting.AUDITING_LOG_MIN_LEVEL ) ) {
+                // obscure any passwords that might have landed in the data object;
+                // also make sure to convert a potential Error object to a JSON:
+                let copyOfData = ( config.getSetting( config.setting.AUDITING_LOG_DETAILS ) === true ) ? _.cloneDeep( data ) : undefined;
+                let logEntry = Auditing.#createLogEntry( severity, thread, message, copyOfData );
+
+                // make sure there is a console available:
+                if ( config.getSetting( config.setting.AUDITING_LOG_CONSOLE_ENABLED ) === true && console ) {
+                    Auditing.#logToConsole( logEntry );
+                }
+
+                // if this is an actual error, then send it to GCloud error reporting system as well:
+                if ( logEntry.severity >= logger.logSeverity.WARNING && data instanceof Error && gcloud.isEnabled() ) {
+                    gcloud.reportError( data );
+                }
+            }
+        } catch ( error ) {
+            // do nothing here for now...
+        }
+    }
+
+    /* Private interface */
+
+    /**
+     * Used to generate a new Log Entry object.
+     *
+     * @method
+     * @param {TiLogSeverity} severity
+     * @param {string} thread
+     * @param {string} message
+     * @param {Object} data
+     * @returns {LogEntry}
+     * @private
+     */
+    static #createLogEntry( severity, thread, message, data ) {
+        let currentDate = new Date();
+        let logDate = tools.getUTCDateString( currentDate );
+        let logTime = tools.getUTCTimeString( currentDate, true );
+        let reporter = process.env.TI_INSTANCE_ID;
+
+        return {
+            _id: `${ logDate }-${ logTime }-${ thread }-${ reporter }-${ logger.getSeverityName( severity ) }-${ tools.getUUID() }`,
+            severity: severity,
+            thread: thread,
+            reporter: reporter,
+            message: message,
+            timestamp: currentDate.getTime(),
+            data: data
+        };
+    }
+
+    /**
+     * Used to write the log entries to the system console (i.e. STD OUT and STD ERR).
+     * <br/>
+     * NOTE: There was an issue in previous Node versions with console that can crash the application if the number of
+     *    outputs exceeds several thousands per second. To be monitored and adjusted as necessary!
+     *
+     * @method
+     * @param {LogEntry} logEntry
+     * @private
+     */
+    static #logToConsole( logEntry ) {
+        if ( config.getSetting( config.setting.AUDITING_LOG_USES_JSON ) === true ) {
+            if ( logEntry.severity >= logger.logSeverity.WARNING ) {
+                console.error( tools.stringifyJSON( logEntry ) );
+            } else {
+                console.log( tools.stringifyJSON( logEntry ) );
+            }
+        } else {
+            console.log( Auditing.#formatConsoleMessage( logEntry ) );
+            if ( !_.isEmpty( logEntry.data ) ) {
+                console.log( `   » ${ Auditing.#formatConsoleData( logEntry ) }` );
+            }
+        }
+    }
+
+    /**
+     * Used to format a log entry for the Node console.
+     *
+     * @method
+     * @param {LogEntry} logEntry
+     * @returns {string}
+     * @private
+     */
+    static #formatConsoleMessage( logEntry ) {
+        let logDate = new Date( logEntry.timestamp );
+        return `${ tools.getUTCDateString( logDate ) }, ${ tools.getUTCTimeString( logDate, true ) } (UTC): ${ logEntry.reporter } - ${ logger.getSeverityName( logEntry.severity ) } - ${ logEntry.message }`;
+    }
+
+    /**
+     * Used to format a log entry data payload for the Node console.
+     *
+     * @method
+     * @param {LogEntry} logEntry
+     * @returns {string}
+     * @private
+     */
+    static #formatConsoleData( logEntry ) {
+        return tools.stringifyJSON( logEntry.data );
+    }
+}
+
+const instance = new Auditing();
+module.exports = Object.freeze( instance );

package/components/connection-observer.js

@@ -0,0 +1,53 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const exceptions = require( "#exceptions" );
+
+/**
+ * An abstract class that allows the child class to observe and take action on various events related to external connections.
+ *
+ * @class ConnectionObserver
+ * @abstract
+ * @public
+ */
+class ConnectionObserver {
+
+    /**
+     * @constructor
+     */
+    constructor() {
+        // make sure this abstract class cannot be instantiated:
+        if ( new.target === ConnectionObserver ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
+        }
+    }
+
+    /**
+     * 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 ) { }
+
+    /**
+     * 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 ) { }
+
+}
+
+module.exports = ConnectionObserver;

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

@@ -0,0 +1,133 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const MessageExchange = require( "#message-exchange" );
+const config = require( "#config" );
+const exceptions = require( "#exceptions" );
+
+/**
+ * The default {@link MessageExchange} behavior for the Ti Engine using Redis for message exchange.
+ *
+ * @class DefaultMessageExchange
+ * @extends MessageExchange
+ * @public
+ */
+class DefaultMessageExchange extends MessageExchange {
+
+    /**
+     * @constructor
+     * @param {string} instanceID The unique identifier of the microservice instance using the message exchange.
+     * @param {string} serviceDomainName The domain name of the microservice using the message exchange.
+     */
+    constructor( instanceID, serviceDomainName ) {
+        super( instanceID, serviceDomainName );
+    }
+
+    /* Public interface */
+
+    /**
+     * Used to initialize the message exchange.
+     * <br/>
+     * NOTE: This will create and prepare all necessary message handlers and then enable them simultaneously.
+     *
+     * @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.
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    enableMessaging( configureInbound, configureOutbound ) {
+        return new Promise( ( resolve, reject ) => {
+            const DefaultMessageSender = require( "#default-message-sender" );
+            const DefaultMessageReceiver = require( "#default-message-receiver" );
+
+            let handlersToEnable = [];
+            if ( configureInbound ) {
+                let messageResponsesOut = new DefaultMessageSender( MessageExchange.connectionNameResponsesOut );
+                let receiveRequestsQueue = config.getSetting( config.setting.MESSAGE_EXCHANGE_QUEUE_PREFIX ) + MessageExchange.pendingQueue + this.serviceDomainName;
+                let messageRequestsIn = new DefaultMessageReceiver( MessageExchange.connectionNameRequestsIn, receiveRequestsQueue );
+                messageRequestsIn.addMessageObserver( this );
+                this.configureInboundMessaging( messageRequestsIn, messageResponsesOut );
+                handlersToEnable.push( this.messageResponsesOut.enable() );
+                handlersToEnable.push( this.messageRequestsIn.enable() );
+            }
+            if ( configureOutbound ) {
+                let messageRequestsOut = new DefaultMessageSender( MessageExchange.connectionNameRequestsOut );
+                let receiveResponsesQueue = config.getSetting( config.setting.MESSAGE_EXCHANGE_QUEUE_PREFIX ) + MessageExchange.processedQueue + this.serviceDomainName + ":" + this.instanceID;
+                let messageResponsesIn = new DefaultMessageReceiver( MessageExchange.connectionNameResponsesIn, receiveResponsesQueue );
+                messageResponsesIn.addMessageObserver( this );
+                this.configureOutboundMessaging( messageRequestsOut, messageResponsesIn );
+                handlersToEnable.push( this.messageRequestsOut.enable() );
+                handlersToEnable.push( this.messageResponsesIn.enable() );
+            }
+
+            Promise.all( handlersToEnable ).then( () => {
+                resolve();
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to gracefully shut down the message exchange.
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    disableMessaging() {
+        return new Promise( ( resolve, reject ) => {
+            let handlersToDisable = [];
+            if ( this.configuredInbound ) {
+                handlersToDisable.push( this.messageResponsesOut.disable() );
+                handlersToDisable.push( this.messageRequestsIn.disable() );
+            }
+            if ( this.configuredOutbound ) {
+                handlersToDisable.push( this.messageRequestsOut.disable() );
+                handlersToDisable.push( this.messageResponsesIn.disable() );
+            }
+
+            Promise.all( handlersToDisable ).then( () => {
+                resolve();
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to send a message request vie the specified route.
+     *
+     * @method
+     * @param {Message} message The message request to send.
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    sendMessageRequest( message ) {
+        let sendQueue = config.getSetting( config.setting.MESSAGE_EXCHANGE_QUEUE_PREFIX ) + MessageExchange.pendingQueue + message.destination.route;
+        return this.messageRequestsOut.send( message, sendQueue );
+    }
+
+    /**
+     * Used to send a message response via the specified route.
+     *
+     * @method
+     * @param {Message} message The message response to send.
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    sendMessageResponse( message ) {
+        let sendQueue = config.getSetting( config.setting.MESSAGE_EXCHANGE_QUEUE_PREFIX ) + MessageExchange.processedQueue + message.source.route + ":" + message.source.instanceID;
+        return this.messageResponsesOut.send( message, sendQueue );
+    }
+
+}
+
+module.exports = DefaultMessageExchange;

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

@@ -0,0 +1,89 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const MessageReceiver = require( "#message-receiver" );
+const memoryCache = require( "#message-memory-cache" );
+const config = require( "#config" );
+const exceptions = require( "#exceptions" );
+
+/**
+ * The default {@link MessageReceiver} behavior for the Ti Engine using Redis for message exchange.
+ *
+ * @class DefaultMessageReceiver
+ * @extends MessageReceiver
+ * @public
+ */
+class DefaultMessageReceiver extends MessageReceiver {
+
+    #memoryCache;
+
+    /**
+     * @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.
+     * @param {string} [processingQueue=undefined] The queue in which the messages will be put for processing (if necessary).
+     */
+    constructor( identifier, receiveQueue, processingQueue = undefined ) {
+        super( identifier, receiveQueue, processingQueue );
+    }
+
+    /**
+     * Used to initialize and enable the communication capabilities of the handler.
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    enable() {
+        return new Promise( ( resolve, reject ) => {
+            this.#memoryCache = memoryCache.create( this.connectionIdentifier );
+            this.#memoryCache.addConnectionObserver( this );
+            this.receive();
+            resolve();
+        } );
+    }
+
+    /**
+     * Used to shutdown and disable the communication behavior of the handler.
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    disable() {
+        return new Promise( ( resolve, reject ) => {
+            this.isAvailable = false;
+            this.#memoryCache = null;
+            resolve();
+        } );
+    }
+
+    /**
+     * Used to receive messages.
+     * <br/>
+     * NOTE: The default message exchange works with lightweight messages (i.e. will keep the payloads stored in Redis while exchanging).
+     *
+     * @method
+     * @returns {Promise<Message>}
+     * @override
+     * @public
+     */
+    onReceive() {
+        return new Promise( ( resolve, reject ) => {
+            this.#memoryCache.receiveMessage( this.receiveQueue ).then( ( lightweightMessage ) => {
+                return this.#memoryCache.retrieveMessagePayload( lightweightMessage, config.getSetting( config.setting.MESSAGE_EXCHANGE_STORE ) );
+            } ).then( ( message ) => {
+                resolve( message );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+}
+
+module.exports = DefaultMessageReceiver;

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

@@ -0,0 +1,90 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const MessageSender = require( "#message-sender" );
+const _ = require( "lodash" );
+const config = require( "#config" );
+const exceptions = require( "#exceptions" );
+const memoryCache = require( "#message-memory-cache" );
+
+/**
+ * The default {@link MessageSender} behavior for the Ti Engine using Redis for message exchange.
+ *
+ * @class DefaultMessageSender
+ * @extends MessageSender
+ * @public
+ */
+class DefaultMessageSender extends MessageSender {
+
+    #memoryCache;
+
+    /**
+     * @constructor
+     * @param {string} identifier An identifier for this message handler. Should be unique in the context of the message exchange.
+     */
+    constructor( identifier ) {
+        super( identifier );
+    }
+
+    /**
+     * Used to perform the actual sending of a message.
+     * <br/>
+     * NOTE: The default message exchange works with lightweight messages (i.e. will keep the payloads stored in Redis while exchanging).
+     *
+     * @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}
+     * @override
+     * @public
+     */
+    onSend( message, queue ) {
+        return new Promise( ( resolve, reject ) => {
+            this.#memoryCache.storeMessagePayload( message.payload, config.getSetting( config.setting.MESSAGE_EXCHANGE_STORE ) ).then( ( storeID ) => {
+                let lightweightMessage = _.cloneDeep( message );
+                lightweightMessage.payload = storeID;
+                return this.#memoryCache.sendMessage( lightweightMessage, queue );
+            } ).then( () => {
+                resolve();
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to initialize and enable the communication capabilities of the handler.
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    enable() {
+        return new Promise( ( resolve, reject ) => {
+            this.#memoryCache = memoryCache.create( this.connectionIdentifier );
+            this.#memoryCache.addConnectionObserver( this );
+            resolve();
+        } );
+    }
+
+    /**
+     * Used to shutdown and disable the communication behavior of the handler.
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    disable() {
+        return new Promise( ( resolve, reject ) => {
+            this.isAvailable = false;
+            this.#memoryCache = null;
+            resolve();
+        } );
+    }
+}
+
+module.exports = DefaultMessageSender;

package/components/exchange/message-dispatcher.js

@@ -0,0 +1,162 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const tools = require( "#tools" );
+const exceptions = require( "#exceptions" );
+const logger = require( "#logger" );
+const messageTracer = require( "#message-tracer" );
+
+/**
+ * Used to create and/or return a Message Dispatcher singleton instance.
+ * This class handles the internal message dispatching between the microservices.
+ *
+ * @class MessageDispatcher
+ * @singleton
+ * @public
+ */
+class MessageDispatcher {
+
+    static #instance = null;
+    #messageExchange;
+
+    /**
+     * @constructor
+     * @returns {MessageDispatcher}
+     */
+    constructor() {
+        if ( !MessageDispatcher.#instance ) {
+            MessageDispatcher.#instance = this;
+        }
+
+        return MessageDispatcher.#instance;
+    }
+
+    /* Public interface */
+
+    /**
+     * Used to initialize the message dispatcher and enable the message exchange.
+     *
+     * @method
+     * @param {MessageExchange} messageExchange The message exchange instance to be used by the dispatcher.
+     * @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.
+     * @returns {Promise}
+     * @public
+     */
+    initialize( messageExchange, configureInbound, configureOutbound ) {
+        return new Promise( ( resolve, reject ) => {
+            this.#messageExchange = messageExchange;
+            this.#messageExchange.enableMessaging( configureInbound, configureOutbound ).then( () => {
+                resolve();
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to shut down the message dispatcher and disable the message exchange.
+     *
+     * @method
+     * @returns {Promise}
+     * @public
+     */
+    shutDown() {
+        return new Promise( ( resolve, reject ) => {
+            this.#messageExchange.disableMessaging().then( () => {
+                this.#messageExchange = null;
+                resolve();
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to send a message request via the message exchange system.
+     *
+     * @method
+     * @param {Message} message The message to send. This can also be a subclass of {@link Message}.
+     * @returns {Promise<string>}
+     * @public
+     */
+    sendRequest( message ) {
+        return new Promise( ( resolve, reject ) => {
+            let retry = new tools.RetryPolicy( 3 );
+            retry.onFailedAttempt( ( error ) => {
+                logger.log( `Failed to send message request with chain ID: ${ message.chainID }`, logger.logSeverity.WARNING, error );
+            } );
+            retry.onRetry( ( attempt ) => {
+                logger.log( `Retrying to send message response with chain ID: ${ message.chainID }. This is attempt ${ attempt }...`, logger.logSeverity.NOTICE );
+            } );
+
+            messageTracer.recordTraceEntry( message, messageTracer.messageType.MESSAGE_REQUEST, messageTracer.dispatchEvent.SENT, messageTracer.messageState.PENDING );
+
+            retry.execute( this.#messageExchange, this.#messageExchange.sendMessageRequest, [ message ] ).then( () => {
+                messageTracer.recordTraceEntry( message, messageTracer.messageType.MESSAGE_REQUEST, messageTracer.dispatchEvent.DELIVERED, messageTracer.messageState.PENDING );
+                resolve( message.messageID );
+            } ).catch( ( error ) => {
+                messageTracer.recordTraceEntry( message, messageTracer.messageType.MESSAGE_REQUEST, messageTracer.dispatchEvent.FAILED, messageTracer.messageState.PENDING );
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to send a message response via the message exchange system.
+     *
+     * @method
+     * @param {Message} message The message to send. This can also be a subclass of {@link Message}.
+     * @returns {Promise}
+     * @public
+     */
+    sendResponse( message ) {
+        return new Promise( ( resolve, reject ) => {
+            let retry = new tools.RetryPolicy( 3 );
+            retry.onFailedAttempt( ( error ) => {
+                logger.log( `Failed to send message response with chain ID: ${ message.chainID }`, logger.logSeverity.WARNING, error );
+            } );
+            retry.onRetry( ( attempt ) => {
+                logger.log( `Retrying to send message response with chain ID: ${ message.chainID }. This is attempt ${ attempt }...`, logger.logSeverity.NOTICE );
+            } );
+
+            messageTracer.recordTraceEntry( message, messageTracer.messageType.MESSAGE_RESPONSE, messageTracer.dispatchEvent.SENT, messageTracer.messageState.PROCESSED );
+
+            retry.execute( this.#messageExchange, this.#messageExchange.sendMessageResponse, [ message ] ).then( () => {
+                messageTracer.recordTraceEntry( message, messageTracer.messageType.MESSAGE_RESPONSE, messageTracer.dispatchEvent.DELIVERED, messageTracer.messageState.PROCESSED );
+                resolve();
+            } ).catch( ( error ) => {
+                messageTracer.recordTraceEntry( message, messageTracer.messageType.MESSAGE_RESPONSE, messageTracer.dispatchEvent.FAILED, messageTracer.messageState.PROCESSED );
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to add an additional {@link MessageObserver} to the connection for the incoming message requests.
+     *
+     * @method
+     * @param {MessageObserver} messageObserver
+     * @public
+     */
+    addMessageObserverRequestsIn( messageObserver ) {
+        this.#messageExchange.addMessageObserverRequestsIn( messageObserver );
+    }
+
+    /**
+     * Used to add an additional {@link MessageObserver} to the connection for the incoming message responses.
+     *
+     * @method
+     * @param {MessageObserver} messageObserver
+     * @public
+     */
+    addMessageObserverResponsesIn( messageObserver ) {
+        this.#messageExchange.addMessageObserverResponsesIn( messageObserver );
+    }
+
+}
+
+const instance = new MessageDispatcher();
+module.exports = Object.freeze( instance );