@ti-engine/core 1.0.1 → 1.0.5

package/README.md

@@ -2,11 +2,24 @@
 Flexible framework for the creation of microservices with [node.js](https://nodejs.org/).
 
 ## introduction
-The **@ti-engine/core** is an open source, free to use - both for personal and commercial projects - framework for the creation of microservice-based solutions using **node.js**. The general architectural concept of the framework is based on a standard messenger system that allows certain customization but also provides predictability and traceability of its behavior.
+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**. The general architectural concept of the framework is based on a standard messenger system that allows certain customization but also provides predictability and traceability of its behavior.
 
-Being a messenger system, the **@ti-engine/core** relies on a message broker for the actual exchange of messages between microservice instances. The default implementation of the framework uses [Redis](https://redis.io/) cache, however, you could create your own implementation using something like [Rabbit MQ](https://www.rabbitmq.com/). See the [advanced topics](#advanced-topics) section of this documentation for guides on how to do this.
+Being a messenger system, the **ti-engine** relies on a message broker for the actual exchange of messages between microservice instances. The default implementation of the framework uses [Redis](https://redis.io/) cache, however, you could create your own implementation using something like [Rabbit MQ](https://www.rabbitmq.com/). See the [advanced topics](#advanced-topics) section of this documentation for guides on how to do this.
 
-Please be aware, that this framework is under active development and will expand in the near future. Make sure to keep an eye on the changes in case you want to use it in the meantime.
+Please be aware, that this framework is under active development and will expand in the near future. Also, this documentation is still in the process of being created and refined. Make sure to keep an eye on the changes in case you want to use it in the meantime.
+
+## why ti-engine?
+The framework is created based on a decade of professional experience with the utilized technologies and architectural approach. It's primary goal is to provide you with a lightweight and flexible solution that can help you build quickly a microservice ecosystem with any degree of size and complexity.
+
+This is what you gain by using **ti-engine** in your project:
+* Simplicity - begin productive work within minutes and get to codding you business logic
+* Flexibility - go as complex as you need to in your implementation
+* Reliability - message exchange between the services is constantly tracked across the entire ecosystem
+* Security - messages are encrypted in transit and cannot be modified by external agents
+* Scalability - serve mullions of requests by multiplying stateless service instances (hardware limitations still apply)
+* Containerization - go with containers from the very start as the framework is designed to work in such an environment
+
+These are just some benefits **ti-engine** offers. Get to know it better to find out more ways in which it can help you improve productivity.
 
 ## prerequisites & installation
 In order to run the basic ti-engine framework you will need a couple of things:
@@ -16,6 +29,8 @@ In order to run the basic ti-engine framework you will need a couple of things:
 To get the framework itself, use the command `npm install @ti-engine/core`. And to include it directly in your package.json dependencies execute `npm install @ti-engine/core --save-prod`.
 
 ## getting started
+To start using the ti-engine, you will have to make sure that the framework is properly configured and able to run. More details and instructions will be provided in the next version of this documentation. For now please take a look at the included file `start-instance.js`. It should give you an idea of how the engine operates and what to do in order to create and run your own microservice instance.
+
 Under development...
 
 ## architecture

package/bin/start-instance.js

@@ -0,0 +1,108 @@
+/*
+ * SPDX-FileCopyrightText: © 2021 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+"use strict";
+
+// load any ENV variables defined in a .env file:
+require( "dotenv" ).config();
+
+const _ = require( "lodash" );
+const fs = require( "fs-extra" );
+const tools = require( "#tools" );
+const logger = require( "#logger" );
+
+// configure the current instance variables before requiring any platform modules and store the necessary ones in memory cache:
+process.env.TI_INSTANCE_ID = "ti-" + tools.getUUID();
+process.env.TI_INSTANCE_CLASS = process.env.TI_INSTANCE_CLASS || "";
+process.env.TI_INSTANCE_NAME = process.env.TI_INSTANCE_NAME || _.last( _.split( process.env.TI_INSTANCE_CLASS, "/" ) );
+
+// configure the process error handlers:
+
+/**
+ * Will be used to gracefully shut down the instance.
+ * <br/>
+ * NOTE: Will be overridden below after the instance creation.
+ *
+ * @method
+ * @param {number} exitCode
+ * @abstract
+ * @private
+ */
+let shutDownInstance = ( exitCode ) => {
+};
+
+// this event will handle the process termination (Ctrl + C):
+process.on( "SIGINT", () => {
+    logger.log( `SIGINT event detected in main instance process.`, logger.logSeverity.NOTICE );
+    shutDownInstance( 0 );
+} );
+
+// this event will handle the process termination (CMD close):
+process.on( "SIGHUP", () => {
+    logger.log( `SIGHUP event detected in main instance process.`, logger.logSeverity.NOTICE );
+    shutDownInstance( 0 );
+} );
+
+// this event will handle the process termination:
+process.on( "SIGTERM", () => {
+    logger.log( `SIGTERM event detected in main instance process.`, logger.logSeverity.NOTICE );
+    shutDownInstance( 0 );
+} );
+
+process.on( "unhandledRejection", ( reason, promise ) => {
+    logger.log( `Unhandled promise rejection identified! Make sure this isn't a software bug.`, logger.logSeverity.WARNING, {
+        reason: reason,
+        promise: tools.stringifyJSON( promise )
+    } );
+} );
+
+process.on( "multipleResolves", ( type, promise, reason ) => {
+    logger.log( `Multiple promise resolves detected! Make sure this isn't a software bug.`, logger.logSeverity.WARNING, {
+        reason: reason,
+        promise: tools.stringifyJSON( promise )
+    } );
+} );
+
+process.on( "uncaughtException", ( error ) => {
+    logger.log( `Some nasty and uncaught error just occurred in the application!`, logger.logSeverity.ALERT, error );
+    setImmediate( () => process.exit( 1 ) );
+} );
+
+// start the instance:
+try {
+    logger.log( `Starting new instance of type '${ process.env.TI_INSTANCE_NAME }' with instance ID '${ process.env.TI_INSTANCE_ID }'.`, logger.logSeverity.NOTICE );
+
+    /** @type ServiceInstance */
+    const serviceConstructor = require( process.env.TI_INSTANCE_CLASS );
+    const serviceConfigPath = process.env.TI_INSTANCE_CONFIG;
+    let serviceConfig = {};
+    if ( fs.existsSync( serviceConfigPath ) ) {
+        serviceConfig = require( process.env.TI_INSTANCE_CONFIG );
+    }
+    const mainInstance = new serviceConstructor( process.env.TI_INSTANCE_NAME, serviceConfig );
+
+    /** @override */
+    shutDownInstance = ( code ) => {
+        mainInstance.stop().then( () => {
+            setImmediate( () => process.exit( code ) );
+        } ).catch( ( error ) => {
+            logger.log( `Error occurred during shut down of instance '${ process.env.TI_INSTANCE_ID }'! Exit code changed from '${ code }' to '1'.`, logger.logSeverity.ERROR, error );
+            setImmediate( () => process.exit( 1 ) );
+        } );
+    };
+
+    if ( mainInstance.isServiceInstance ) {
+        mainInstance.start().catch( ( error ) => {
+            logger.log( `Error detected during instance '${ process.env.TI_INSTANCE_ID }' startup!`, logger.logSeverity.ALERT, error );
+            setImmediate( () => process.exit( 1 ) );
+        } );
+    } else {
+        logger.log( `Attempting to start a module that does not implement the ServiceInstance abstract class!`, logger.logSeverity.ERROR );
+        setImmediate( () => process.exit( 1 ) );
+    }
+} catch ( error ) {
+    logger.log( `Error detected in the instance startup script!`, logger.logSeverity.ALERT, error );
+    setImmediate( () => process.exit( 1 ) );
+}

package/components/service-consumer.js

@@ -94,7 +94,7 @@ class ServiceConsumer extends ServiceInstance {
     }
 
     /**
-     * Used to invoke a business service.
+     * Used to invoke a business service in any {@link ServiceInstance}.
      *
      * @method
      * @param {ServiceAddress} serviceAddress

package/components/service-executor.js

@@ -20,14 +20,14 @@ const messageDispatcher = require( "#message-dispatcher" );
  */
 
 /**
- * @callback VerifyAccess
+ * @callback VerifyAccessMethod
  * @param {string} authToken
  * @param {ServiceAddress} serviceAddress
  * @returns {Promise}
  */
 
 /**
- * @callback ServiceHandler
+ * @callback ServiceHandlerMethod
  * @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.
@@ -44,7 +44,7 @@ const messageDispatcher = require( "#message-dispatcher" );
 class ServiceExecutor extends MessageObserver {
 
     #serviceInterface = {};
-    /** @type VerifyAccess */
+    /** @type VerifyAccessMethod */
     #verifyAccess;
 
     /**
@@ -114,7 +114,7 @@ class ServiceExecutor extends MessageObserver {
      * Used to setup the method for service access verification.
      *
      * @method
-     * @param {VerifyAccess} verifyAccess
+     * @param {VerifyAccessMethod} verifyAccess
      * @public
      */
     configureVerifyAccess( verifyAccess ) {
@@ -131,18 +131,19 @@ class ServiceExecutor extends MessageObserver {
      * NOTE: If the same version of the service handler already exists, it will be overridden!
      *
      * @method
-     * @param {ServiceHandler} serviceHandler
+     * @param {ServiceHandlerMethod} serviceHandler
      * @param {ServiceDefinition} serviceDefinition
+     * @param {ServiceInstance} serviceInstance This will be used as context to bind all business services.
      * @public
      */
-    addServiceHandler( serviceHandler, serviceDefinition ) {
+    addServiceHandler( serviceHandler, serviceDefinition, serviceInstance ) {
         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 ) );
+        this.#serviceInterface[ serviceDefinition.serviceAlias ][ serviceDefinition.serviceVersion ] = serviceHandler.bind( serviceInstance, _.cloneDeep( serviceDefinition ) );
     }
 
     /* Private interface */
@@ -203,7 +204,7 @@ class ServiceExecutor extends MessageObserver {
      *
      * @method
      * @param {ServiceAddress} serviceAddress
-     * @returns {Promise<ServiceHandler>}
+     * @returns {Promise<ServiceHandlerMethod>}
      * @private
      */
     #identifyService( serviceAddress ) {

package/components/service-provider.js

@@ -5,7 +5,6 @@
 
 const ServiceConsumer = require( "#service-consumer" );
 const _ = require( "lodash" );
-const fs = require( "fs-extra" );
 const exceptions = require( "#exceptions" );
 const logger = require( "#logger" );
 const messageDispatcher = require( "#message-dispatcher" );
@@ -128,25 +127,19 @@ class ServiceProvider extends ServiceConsumer {
      *
      * @method
      * @param {ServiceDefinition} serviceDefinition Full service definition object.
-     * @param {ServiceHandler} [defaultServiceHandler=undefined] A default service handler in case there is one.
+     * @param {ServiceHandlerMethod} [defaultServiceHandler=undefined] A default service handler in case there is one.
      * @return {Promise}
      * @public
      */
     registerService( serviceDefinition, defaultServiceHandler = undefined ) {
         return new Promise( ( resolve, reject ) => {
-            /** @type {ServiceHandler} */
+            /** @type {ServiceHandlerMethod} */
             let serviceHandler = null;
             if ( serviceDefinition.serviceFile ) {
-                let filePath = process.cwd() + serviceDefinition.serviceFile + ( ( _.endsWith( serviceDefinition.serviceFile, ".js" ) ) ? "" : ".js" );
-                if ( fs.existsSync( filePath ) ) {
-                    // try to load the service handler dynamically from the file:
-                    try {
-                        serviceHandler = require( filePath ).service;
-                    } catch ( error ) {
-                        logger.log( `Specified service handler file '${ serviceDefinition.serviceFile }' could not be loaded!`, logger.logSeverity.ERROR, error );
-                    }
-                } else {
-                    logger.log( `Specified service handler file '${ serviceDefinition.serviceFile }' was not found in the specified location!`, logger.logSeverity.WARNING );
+                try {
+                    serviceHandler = require( serviceDefinition.serviceFile ).service;
+                } catch ( error ) {
+                    logger.log( `Specified service handler file '${ serviceDefinition.serviceFile }' could not be loaded!`, logger.logSeverity.ERROR, error );
                 }
             } else {
                 if ( typeof ( defaultServiceHandler ) === "function" ) {
@@ -160,7 +153,7 @@ class ServiceProvider extends ServiceConsumer {
             if ( typeof ( serviceHandler ) === "function" ) {
                 // make sure we have a version and parent service provider specified:
                 serviceDefinition.serviceVersion = serviceDefinition.serviceVersion || 1;
-                this.#serviceExecutor.addServiceHandler( serviceHandler, serviceDefinition );
+                this.#serviceExecutor.addServiceHandler( serviceHandler, serviceDefinition, this );
                 resolve();
             } else {
                 reject( exceptions.raise( exceptions.exceptionCode.E_GEN_BAD_SERVICE_HANDLER ) );
@@ -173,7 +166,7 @@ class ServiceProvider extends ServiceConsumer {
      *
      * @method
      * @param {ServiceDefinition[]} serviceDefinitions
-     * @param {ServiceHandler} [defaultServiceHandler=undefined]
+     * @param {ServiceHandlerMethod} [defaultServiceHandler=undefined]
      * @return {Promise}
      * @public
      */

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.0.1",
+  "version": "1.0.5",
   "description": "The ti-engine is an open source, free to use - both for personal and commercial projects - framework for the creation of microservice-based solutions using node.js.",
   "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
   "license": "ISC",
   "exports": {
+    "./exceptions": "./utils/exceptions.js",
+    "./logger": "./utils/logger.js",
     "./service-consumer": "./components/service-consumer.js",
     "./service-instance": "./components/service-instance.js",
     "./service-provider": "./components/service-provider.js",
-    "./exceptions": "./utils/exceptions.js",
     "./tools": "./utils/tools.js"
   },
   "imports": {
@@ -36,17 +37,22 @@
     "#service-executor": "./components/service-executor.js",
     "#service-instance": "./components/service-instance.js",
     "#service-provider": "./components/service-provider.js",
-    "#settings": "./settings.json",
+    "#settings": "./bin/settings.json",
     "#tools": "./utils/tools.js"
   },
   "dependencies": {
+    "dotenv": "^10.0.0",
     "fs-extra": "^10.0.0",
     "lodash": "^4.17.21",
     "node-schedule": "^2.0.0",
-    "ioredis": "^4.27.7"
+    "ioredis": "^4.28.1"
   },
   "optionalDependencies": {
-    "@google-cloud/error-reporting": "^2.0.2"
+    "@google-cloud/error-reporting": "^2.0.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Belleal/ti-engine.git"
   },
   "engines": {
     "node": ">=14.17.0"

package/utils/config.js

@@ -23,6 +23,10 @@ const tools = require( "#tools" );
  * @property {EnvironmentVariable} env.TI_LOG_CONSOLE_ENABLED
  * @property {EnvironmentVariable} env.TI_LOG_MIN_LEVEL
  * @property {EnvironmentVariable} env.TI_LOG_USED_JSON
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_AUTH_KEY
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_DB
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_HOST
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_PORT
  * @property {EnvironmentVariable} env.TI_OPERATION_MODE
  */
 
@@ -116,10 +120,16 @@ const settings = require( "#settings" );
 
 // override remaining settings with ENV variables (if provided):
 if ( settings.auditing ) {
-    settings.auditing.logMinLevel = ( process.env.TI_LOG_MIN_LEVEL !== undefined ) ? process.env.TI_LOG_CONSOLE_ENABLED : settings.auditing.logMinLevel;
+    settings.auditing.logMinLevel = ( process.env.TI_LOG_MIN_LEVEL !== undefined ) ? process.env.TI_LOG_MIN_LEVEL : settings.auditing.logMinLevel;
     settings.auditing.logConsoleEnabled = ( process.env.TI_LOG_CONSOLE_ENABLED !== undefined ) ? tools.toBool( process.env.TI_LOG_CONSOLE_ENABLED ) : settings.auditing.logConsoleEnabled;
     settings.auditing.logUsesJSON = ( process.env.TI_LOG_USED_JSON !== undefined ) ? tools.toBool( process.env.TI_LOG_USED_JSON ) : settings.auditing.logUsesJSON;
 }
+if ( settings.memoryCache ) {
+    settings.memoryCache.authKey = ( process.env.TI_MEMORY_CACHE_AUTH_KEY !== undefined ) ? process.env.TI_MEMORY_CACHE_AUTH_KEY : settings.memoryCache.authKey;
+    settings.memoryCache.redisDB = ( process.env.TI_MEMORY_CACHE_DB !== undefined ) ? process.env.TI_MEMORY_CACHE_DB : settings.memoryCache.redisDB;
+    settings.memoryCache.redisHost = ( process.env.TI_MEMORY_CACHE_HOST !== undefined ) ? process.env.TI_MEMORY_CACHE_HOST : settings.memoryCache.redisHost;
+    settings.memoryCache.redisPort = ( process.env.TI_MEMORY_CACHE_PORT !== undefined ) ? process.env.TI_MEMORY_CACHE_PORT : settings.memoryCache.redisPort;
+}
 
 // make sure GCloud is enabled before trying to setup it:
 if ( process.env.TI_GCLOUD_ENABLED === true && settings.gcloudIntegration ) {

package/utils/exceptions.js

@@ -69,8 +69,9 @@ class Exception {
      * @param {string} id The unique ID to be assigned to this exception.
      * @param {TiExceptionCode} exceptionCode An unique exception identifier. If this is not recognized, the default error code will be used instead.
      * @param {Object} [data] Any additional data to insert into the exception.
+     * @param {string} [description] Description of the exception.
      */
-    constructor( id, exceptionCode, data ) {
+    constructor( id, exceptionCode, data, description ) {
         exceptionCode = ( exceptionCodeEnum.properties[ exceptionCode ] ) ? exceptionCode : module.exports.exceptionCode.E_UNKNOWN_ERROR;
 
         this.#id = id;
@@ -184,7 +185,8 @@ class Exception {
             code: this.code,
             httpCode: this.httpCode,
             label: this.label,
-            description: this.description
+            description: this.description,
+            data: this.data
         };
     }
 }
@@ -211,6 +213,8 @@ module.exports.raise = ( source, data, exceptionID ) => {
         exception = new Exception( exceptionID || tools.getUUID(), module.exports.exceptionCode.E_GEN_JS_INTERNAL_ERROR, {
             message: source
         } );
+    } else if ( _.isObjectLike( source ) ) {
+        exception = new Exception( exceptionID || ( source.id || tools.getUUID() ), source.code || module.exports.exceptionCode.E_GEN_JS_INTERNAL_ERROR, source.data, source.description );
     } else {
         exception = new Exception( exceptionID || tools.getUUID(), ( exceptionCodeEnum.properties[ source ] ) ? source : module.exports.exceptionCode.E_UNKNOWN_ERROR );
     }