@ti-engine/core 1.0.0

package/components/service-caller.js

@@ -0,0 +1,306 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const MessageObserver = require( "#message-observer" );
+const tools = require( "#tools" );
+const exceptions = require( "#exceptions" );
+const logger = require( "#logger" );
+const config = require( "#config" );
+const cache = require( "#cache" );
+const messageDispatcher = require( "#message-dispatcher" );
+
+/**
+ * @typedef {Object} ServiceAddress
+ * @property {string} serviceAlias A valid service alias.
+ * @property {string} serviceDomainName A valid service domain name.
+ * @property {number|undefined} serviceVersion Optional service version. If not provided, the latest version will be assumed as a target.
+ */
+
+/**
+ * @typedef {Object} ServiceExecContext
+ * @property {string} authToken A valid authentication token that initialized the service call.
+ * @property {ServiceCallPredecessor|undefined} previousServiceCall The previous service call in the execution chain (if such exists).
+ */
+
+/**
+ * @typedef {Message} ServiceCallPredecessor
+ * @property {string} predecessor The {@link Message.messageID} of the predecessor in the service call tree.
+ * @property {ServiceAddress} serviceAddress The address of the service that has to process the service call.
+ * @property {Object|undefined} serviceParams The named params to be provided to the API service.
+ */
+
+/**
+ * @typedef {ServiceCallPredecessor} ServiceCall
+ * @property {string} authToken A valid authentication token that initialized the service call.
+ * @property {number} createdOn A unix timestamp taken at creation time of the service call.
+ * @property {number} executionTime The total execution time of this service call in milliseconds.
+ * @property {Object|undefined} exception If there was exception during the service call processing, it will be set here. Otherwise it will be 'undefined'.
+ * @property {number|undefined} finishedOn A unix timestamp taken at finish time of the service call.
+ * @property {boolean} isCompleted Flag to indicate if this service call has been completed.
+ * @property {boolean|undefined} isSuccessful A flag indicating if this service call can be considered successful or not. Will be 'undefined' until the service call is processed.
+ * @property {string[]} successors The service call IDs of the successors in the service call tree.
+ */
+
+/**
+ * @typedef {Object} ServiceCallResult
+ * @property {Object|undefined} exception If there was exception during the service call processing, it will be set here. Otherwise it will be 'undefined'.
+ * @property {boolean} isSuccessful A flag indicating if this service call can be considered successful or not.
+ * @property {Object|string|undefined} payload The payload containing the results from the service call processing. If string, it is ID of the payload in the memory cache instead.
+ */
+
+/**
+ * @callback TaskHandler
+ * @param {ServiceCall} serviceCall The service call for processing.
+ */
+
+/**
+ * A class defining a service caller behavior.
+ *
+ * @class ServiceCaller
+ * @extends MessageObserver
+ * @public
+ */
+class ServiceCaller extends MessageObserver {
+
+    #serviceCallTasks = {};
+
+    /**
+     * @constructor
+     */
+    constructor() {
+        super();
+    }
+
+    /* Public interface */
+
+    /**
+     * Used to call a service in the service ecosystem asynchronously.
+     * <br/>
+     * NOTE: This method will timeout after specific preconfigured time, in which case it will resolve with {@link E_COM_SERVICE_EXEC_TIMEOUT} error.
+     *
+     * @method
+     * @param {ServiceAddress} serviceAddress The service address has to define a valid service domain name, service alias, and optionally a service version.
+     * @param {Object} serviceParams Set of named parameters to provide to the called service.
+     * @param {ServiceExecContext} serviceExecContext The context in which the service call is being executed.
+     * @returns {Promise<ServiceCallResult>} Will always return a service call result that can be either successful or not.
+     * @public
+     */
+    executeServiceCall( serviceAddress, serviceParams, serviceExecContext ) {
+        let execution = new Promise( ( resolve, reject ) => {
+            this.#findServiceInRegistry( serviceAddress ).then( () => {
+                return this.#prepareServiceCall( serviceAddress, serviceParams, serviceExecContext );
+            } ).then( ( serviceCall ) => {
+                return messageDispatcher.sendRequest( serviceCall );
+            } ).then( ( messageID ) => {
+                this.#addTaskHandler( messageID, ( serviceCall ) => {
+                    this.#completeServiceCall( serviceCall ).then( ( serviceCall ) => {
+                        let serviceCallResult = {
+                            exception: serviceCall.exception,
+                            isSuccessful: ( serviceCall.isSuccessful !== undefined ) ? serviceCall.isSuccessful : true,
+                            payload: serviceCall.payload
+                        };
+
+                        resolve( serviceCallResult );
+                    } ).catch( ( error ) => {
+                        reject( exceptions.raise( error ) );
+                    } );
+                } );
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+        let timeoutHandle;
+        let timeout = new Promise( ( resolve, reject ) => {
+            timeoutHandle = setTimeout( () => reject( exceptions.raise( exceptions.exceptionCode.E_COM_SERVICE_EXEC_TIMEOUT ) ), config.getSetting( config.setting.SERVICE_EXECUTION_TIMEOUT ) );
+        } );
+
+        return Promise.race( [ execution, timeout ] ).then( ( result ) => {
+            clearTimeout( timeoutHandle );
+            return result;
+        } ).catch( ( error ) => {
+            logger.log( `Error during service call execution!`, logger.logSeverity.ERROR, error );
+            return {
+                isSuccessful: false,
+                exception: exceptions.raise( error )
+            };
+        } );
+    }
+
+    /**
+     * Once the proper message is received this method will trigger the completion of the pending {@link ServiceCall} execution started in {@link #executeServiceCall}.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @param {Message} message The message for processing.
+     * @override
+     * @public
+     */
+    onMessage( identifier, message ) {
+        let execution = this.#getTaskHandler( message.messageID );
+        if ( typeof ( execution ) === "function" ) {
+            execution( message );
+            this.#removeTaskHandler( message.messageID );
+        } else {
+            logger.log( `Received message with ID '${ message.messageID }' in ServiceCaller that has no registered handler. This is probably a software bug!`, logger.logSeverity.WARNING );
+        }
+    }
+
+    /**
+     * Needs to be invoked by the connection handler when the connection is disrupted.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionDisrupted( identifier ) {
+        super.onConnectionDisrupted( identifier );
+    }
+
+    /**
+     * Needs to be invoked by the connection handler when the connection is recovered.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionRecovered( identifier ) {
+        super.onConnectionRecovered( identifier );
+    }
+
+    /* Private interface */
+
+    /**
+     * Used to verify if the service is registered in the service registry.
+     *
+     * @method
+     * @param {ServiceAddress} serviceAddress
+     * @returns {Promise}
+     * @private
+     */
+    #findServiceInRegistry( serviceAddress ) {
+        return new Promise( ( resolve, reject ) => {
+            let serviceCatalog = config.getSetting( config.setting.SERVICE_REGISTRY_ADDRESS ) + serviceAddress.serviceDomainName;
+            cache.isSetMember( serviceCatalog, serviceAddress.serviceAlias ).then( ( result ) => {
+                if ( result === true ) {
+                    resolve();
+                } else {
+                    reject( exceptions.raise( exceptions.exceptionCode.E_COM_SERVICE_NOT_REGISTERED ) );
+                }
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to assemble and prepare a new {@link ServiceCall} object.
+     *
+     * @method
+     * @param {ServiceAddress} serviceAddress The service address has to define a valid service domain name, service alias, and optionally a service version.
+     * @param {Object} serviceParams Set of named parameters to provide to the called service.
+     * @param {ServiceExecContext} serviceExecContext The context in which the service call is being executed.
+     * @returns {Promise<ServiceCall>}
+     * @private
+     */
+    #prepareServiceCall( serviceAddress, serviceParams, serviceExecContext ) {
+        return new Promise( ( resolve, reject ) => {
+            const ServiceInstance = require( "#service-instance" );
+
+            // assemble the new service call:
+            let chainID = ( serviceExecContext.previousServiceCall ) ? serviceExecContext.previousServiceCall.chainID : tools.getUUID();
+            let chainLevel = ( serviceExecContext.previousServiceCall ) ? serviceExecContext.previousServiceCall.chainLevel + 1 : 0;
+            let source = {
+                instanceID: ServiceInstance.instanceID,
+                route: ServiceInstance.serviceDomainName
+            };
+            let destination = {
+                instanceID: undefined,
+                route: serviceAddress.serviceDomainName
+            };
+            /** @type ServiceCall */
+            let serviceCall = {
+                authToken: serviceExecContext.authToken,
+                chainID: chainID,
+                chainLevel: chainLevel,
+                createdOn: Date.now(),
+                destination: destination,
+                executionTime: 0,
+                exception: undefined,
+                finishedOn: undefined,
+                isCompleted: false,
+                isSuccessful: undefined,
+                messageID: tools.getUUID(),
+                payload: undefined,
+                predecessor: ( serviceExecContext.previousServiceCall ) ? serviceExecContext.previousServiceCall.messageID : undefined,
+                serviceAddress: serviceAddress,
+                serviceParams: serviceParams,
+                source: source,
+                successors: undefined
+            };
+
+            resolve( serviceCall );
+        } );
+    }
+
+    /**
+     * Used to complete the provided {@link ServiceCall} object by setting all required properties to their correct values.
+     *
+     * @method
+     * @param {ServiceCall} serviceCall
+     * @returns {Promise<ServiceCall>}
+     * @private
+     */
+    #completeServiceCall( serviceCall ) {
+        return new Promise( ( resolve, reject ) => {
+            serviceCall.finishedOn = Date.now();
+            serviceCall.executionTime = serviceCall.finishedOn - serviceCall.createdOn;
+            serviceCall.isCompleted = true;
+
+            resolve( serviceCall );
+        } );
+    }
+
+    /**
+     * Used to add a new task handler to the list of current tasks.
+     *
+     * @method
+     * @param {string} taskID
+     * @param {TaskHandler} taskHandler
+     * @private
+     */
+    #addTaskHandler( taskID, taskHandler ) {
+        this.#serviceCallTasks[ taskID ] = taskHandler;
+    }
+
+    /**
+     * Used to fetch a task handler from the list of current tasks.
+     *
+     * @method
+     * @param {string} taskID
+     * @returns {TaskHandler}
+     * @private
+     */
+    #getTaskHandler( taskID ) {
+        return this.#serviceCallTasks[ taskID ];
+    }
+
+    /**
+     * Used to remove a task handler from the list of current tasks.
+     *
+     * @method
+     * @param {string} taskID
+     * @private
+     */
+    #removeTaskHandler( taskID ) {
+        if ( this.#serviceCallTasks[ taskID ] ) {
+            delete this.#serviceCallTasks[ taskID ];
+        }
+    }
+
+}
+
+module.exports = ServiceCaller;

package/components/service-consumer.js

@@ -0,0 +1,112 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const ServiceInstance = require( "#service-instance" );
+const exceptions = require( "#exceptions" );
+const messageDispatcher = require( "#message-dispatcher" );
+
+/**
+ * Abstract class used to define a Service Consumer behavior.
+ * <br/>
+ * NOTE: Inherit this to create an a module that can be started as a microservice consumer instance.
+ * <br/>
+ * NOTE: A service consumer is a microservice that can invoke named business services in the APIs of other
+ * microservices using {@link ServiceCall} objects. The consumer does not need to know the specifics of
+ * the business logic in these services but only the service address and the inbound parameters (if any).
+ * The result of the execution will be returned to the consumer in a {@link ServiceCallResult} object.
+ *
+ * @class ServiceConsumer
+ * @extends ServiceInstance
+ * @abstract
+ * @public
+ */
+class ServiceConsumer extends ServiceInstance {
+
+    #serviceCaller;
+
+    /**
+     * @constructor
+     * @param {string} serviceDomainName The service domain name for this service instance.
+     * @param {Object} [serviceConfig={}] The JSON configuration for this service.
+     */
+    constructor( serviceDomainName, serviceConfig = {} ) {
+        super( serviceDomainName, serviceConfig );
+
+        // make sure this abstract class cannot be instantiated:
+        if ( new.target === ServiceConsumer ) {
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_ABSTRACT_CLASS_INIT, { name: this.constructor.name } );
+        }
+    }
+
+    /* Public interface */
+
+    /**
+     * Perform initialization tasks when the service consumer starts.
+     * <br/>
+     * NOTE: This method will be invoked automatically.
+     * <br/>
+     * NOTE: If you need to add more onStart logic you can override this method but make sure to call it in the
+     * overriding method using: super.onStart()
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    onStart() {
+        return new Promise( ( resolve, reject ) => {
+            const ServiceCaller = require( "#service-caller" );
+
+            this.#serviceCaller = new ServiceCaller();
+
+            super.onStart().then( () => {
+                messageDispatcher.addMessageObserverResponsesIn( this.#serviceCaller );
+                resolve();
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Perform shut down and cleanup tasks when the service consumer stops.
+     * <br/>
+     * NOTE: This method will be invoked automatically.
+     * <br/>
+     * NOTE: If you need to add more onStop logic you can override this method but make sure to call it in the
+     * overriding method using: super.onStop()
+     *
+     * @method
+     * @returns {Promise}
+     * @override
+     * @public
+     */
+    onStop() {
+        return new Promise( ( resolve, reject ) => {
+            super.onStop().then( () => {
+                resolve();
+            } ).catch( ( error ) => {
+                reject( exceptions.raise( error ) );
+            } );
+        } );
+    }
+
+    /**
+     * Used to invoke a business service.
+     *
+     * @method
+     * @param {ServiceAddress} serviceAddress
+     * @param {Object} serviceParams
+     * @param {ServiceExecContext} serviceExecContext
+     * @returns {Promise<ServiceCallResult>}
+     * @public
+     */
+    callService( serviceAddress, serviceParams, serviceExecContext ) {
+        return this.#serviceCaller.executeServiceCall( serviceAddress, serviceParams, serviceExecContext );
+    }
+
+}
+
+module.exports = ServiceConsumer;

package/components/service-executor.js

@@ -0,0 +1,231 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const MessageObserver = require( "#message-observer" );
+const ServiceInstance = require( "#service-instance" );
+const _ = require( "lodash" );
+const exceptions = require( "#exceptions" );
+const logger = require( "#logger" );
+const config = require( "#config" );
+const cache = require( "#cache" );
+const messageDispatcher = require( "#message-dispatcher" );
+
+/**
+ * @typedef {Object} ServiceDefinition
+ * @property {string} serviceAlias Service alias.
+ * @property {string} serviceFile The JS file containing the service itself. This has to be exposed via package.json import structure!
+ * @property {number} [serviceVersion] Service version.
+ */
+
+/**
+ * @callback VerifyAccess
+ * @param {string} authToken
+ * @param {ServiceAddress} serviceAddress
+ * @returns {Promise}
+ */
+
+/**
+ * @callback ServiceHandler
+ * @param {ServiceDefinition} serviceDefinition The service definition as provided during the service registration.
+ * @param {Object} serviceParams Set of named parameters provided to the called service.
+ * @param {ServiceExecContext} serviceExecContext The context in which the service call is being executed.
+ * @returns {Promise<Object|undefined>} Optional payload to be returned to the service caller.
+ */
+
+/**
+ * A class defining a service executor behavior.
+ *
+ * @class ServiceExecutor
+ * @extends MessageObserver
+ * @public
+ */
+class ServiceExecutor extends MessageObserver {
+
+    #serviceInterface = {};
+    /** @type VerifyAccess */
+    #verifyAccess;
+
+    /**
+     * @constructor
+     */
+    constructor() {
+        super();
+
+        this.#verifyAccess = () => {
+            return Promise.resolve();
+        };
+
+        cache.addConnectionObserver( this );
+    }
+
+    /* Public interface */
+
+    /**
+     *
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @param {Message} message The message for processing.
+     * @override
+     * @public
+     */
+    onMessage( identifier, message ) {
+        this.#processServiceCall( message ).then( ( serviceCall ) => {
+            return messageDispatcher.sendResponse( serviceCall );
+        } ).catch( ( error ) => {
+            logger.log( `Failed to send service call response after processing! Service call ID was: '${ message.messageID }'`, logger.logSeverity.ERROR, error );
+        } );
+    }
+
+    /**
+     * Needs to be invoked by the connection handler when the connection is disrupted.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionDisrupted( identifier ) {
+        super.onConnectionDisrupted( identifier );
+    }
+
+    /**
+     * Needs to be invoked by the connection handler when the connection is recovered.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionRecovered( identifier ) {
+        super.onConnectionRecovered( identifier );
+
+        let serviceCatalog = config.getSetting( config.setting.SERVICE_REGISTRY_ADDRESS ) + ServiceInstance.serviceDomainName;
+        _.forOwn( this.#serviceInterface, ( versions, serviceAlias ) => {
+            cache.addToSet( serviceCatalog, serviceAlias ).catch( ( error ) => {
+                logger.log( `Record for service '${ serviceAlias }' could not be added to the service registry.`, logger.logSeverity.ERROR, error );
+            } );
+        } );
+    }
+
+    /**
+     * Used to setup the method for service access verification.
+     *
+     * @method
+     * @param {VerifyAccess} verifyAccess
+     * @public
+     */
+    configureVerifyAccess( verifyAccess ) {
+        if ( typeof ( verifyAccess ) === "function" ) {
+            this.#verifyAccess = verifyAccess;
+        } else {
+            logger.log( `Attempting to setup service verification method that is not a function!`, logger.logSeverity.WARNING );
+        }
+    }
+
+    /**
+     * Used to add a service handler to the service interface.
+     * <br/>
+     * NOTE: If the same version of the service handler already exists, it will be overridden!
+     *
+     * @method
+     * @param {ServiceHandler} serviceHandler
+     * @param {ServiceDefinition} serviceDefinition
+     * @public
+     */
+    addServiceHandler( serviceHandler, serviceDefinition ) {
+        if ( !this.#serviceInterface[ serviceDefinition.serviceAlias ] ) {
+            this.#serviceInterface[ serviceDefinition.serviceAlias ] = {};
+        }
+        if ( this.#serviceInterface[ serviceDefinition.serviceAlias ][ serviceDefinition.serviceVersion ] ) {
+            logger.log( `Service handler for '${ serviceDefinition.serviceAlias }' version '${ serviceDefinition.serviceVersion }' already existed and will be overridden.`, logger.logSeverity.WARNING );
+        }
+        this.#serviceInterface[ serviceDefinition.serviceAlias ][ serviceDefinition.serviceVersion ] = serviceHandler.bind( this, _.cloneDeep( serviceDefinition ) );
+    }
+
+    /* Private interface */
+
+    /**
+     * Used to assemble {@link ServiceExecContext} from the provided service call object.
+     *
+     * @method
+     * @param {ServiceCall} serviceCall
+     * @returns {ServiceExecContext}
+     * @private
+     */
+    static #assembleServiceExecContext( serviceCall ) {
+        return {
+            authToken: serviceCall.authToken,
+            previousServiceCall: {
+                chainID: serviceCall.chainID,
+                chainLevel: serviceCall.chainLevel,
+                destination: serviceCall.destination,
+                messageID: serviceCall.messageID,
+                payload: serviceCall.payload,
+                predecessor: serviceCall.predecessor,
+                serviceAddress: serviceCall.serviceAddress,
+                serviceParams: serviceCall.serviceParams,
+                source: serviceCall.source
+            }
+        };
+    }
+
+    /**
+     * Used to process the actual service call.
+     *
+     * @method
+     * @param {ServiceCall} serviceCall
+     * @returns {Promise<ServiceCall>}
+     * @private
+     */
+    #processServiceCall( serviceCall ) {
+        return new Promise( ( resolve, reject ) => {
+            this.#verifyAccess( serviceCall.authToken, serviceCall.serviceAddress ).then( () => {
+                return this.#identifyService( serviceCall.serviceAddress );
+            } ).then( ( serviceHandler ) => {
+                return serviceHandler( serviceCall.serviceParams, ServiceExecutor.#assembleServiceExecContext( serviceCall ) );
+            } ).then( ( payload ) => {
+                serviceCall.isSuccessful = true;
+                serviceCall.payload = payload;
+                resolve( serviceCall );
+            } ).catch( ( error ) => {
+                serviceCall.isSuccessful = false;
+                serviceCall.exception = exceptions.raise( error ).asJSON();
+                resolve( serviceCall );
+            } );
+        } );
+    }
+
+    /**
+     * Used to identify the service in the service interface and retrieve its definition.
+     *
+     * @method
+     * @param {ServiceAddress} serviceAddress
+     * @returns {Promise<ServiceHandler>}
+     * @private
+     */
+    #identifyService( serviceAddress ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#serviceInterface[ serviceAddress.serviceAlias ] ) {
+                let serviceVersion = serviceAddress.serviceVersion;
+                if ( !serviceVersion ) {
+                    serviceVersion = _.last( _.sortBy( _.keys( this.#serviceInterface[ serviceAddress.serviceAlias ] ) ) );
+                }
+
+                let serviceHandler = this.#serviceInterface[ serviceAddress.serviceAlias ][ serviceVersion ];
+                if ( serviceHandler ) {
+                    resolve( serviceHandler );
+                } else {
+                    reject( exceptions.raise( exceptions.exceptionCode.E_COM_SERVICE_HANDLER_NOT_FOUND ) );
+                }
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_COM_SERVICE_NOT_FOUND ) );
+            }
+        } );
+    }
+
+}
+
+module.exports = ServiceExecutor;