@ti-engine/core 1.0.2 → 1.0.6

package/README.md

@@ -2,12 +2,25 @@
 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. 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:
 1. A local [node.js installation](https://nodejs.org/en/download/) with a minimum version of **14.17.0**
@@ -16,7 +29,17 @@ 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.
+To start using the **ti-engine**, you will have to make sure that all prerequisites are available and operational. If you are working under Windows OS and you need to install Redis, take a look at this [guide](https://redis.com/blog/redis-on-windows-10/).
+
+Once you have all this setup and ready, you should download the **ti-engine** tester module with the command `npm install @ti-engine/tester`. The tester module packages an example microservice that shows the basic approach for using the framework. To make sure everything is working properly, you should try and start the tester service:
+1. Open a command prompt and navigate to the directory of the tester module; it should be something like that `<path to your project>/node_modules/@ti-engine/tester`
+2. 
+
+
+
+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...
 

package/{start-instance.js → bin/start-instance.js}

@@ -5,14 +5,14 @@
 
 "use strict";
 
-// load any ENV variables defined in a .env file:
-require( "dotenv" ).config();
-
 const _ = require( "lodash" );
-const fs = require( "fs-extra" );
+const path = require( "path" );
 const tools = require( "#tools" );
 const logger = require( "#logger" );
 
+// load any ENV variables defined in a .env file:
+require( "dotenv" ).config( { path: path.join( process.cwd(), ".env" ) } );
+
 // 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 || "";
@@ -22,6 +22,7 @@ process.env.TI_INSTANCE_NAME = process.env.TI_INSTANCE_NAME || _.last( _.split(
 
 /**
  * Will be used to gracefully shut down the instance.
+ * <br/>
  * NOTE: Will be overridden below after the instance creation.
  *
  * @method
@@ -74,11 +75,11 @@ 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 serviceConstructor = require( path.join( process.cwd(), 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 );
+    if ( serviceConfigPath ) {
+        serviceConfig = require( path.join( process.cwd(), process.env.TI_INSTANCE_CONFIG ) );
     }
     const mainInstance = new serviceConstructor( process.env.TI_INSTANCE_NAME, serviceConfig );
 

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,7 @@
 
 const ServiceConsumer = require( "#service-consumer" );
 const _ = require( "lodash" );
-const fs = require( "fs-extra" );
+const path = require( "path" );
 const exceptions = require( "#exceptions" );
 const logger = require( "#logger" );
 const messageDispatcher = require( "#message-dispatcher" );
@@ -128,25 +128,20 @@ 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 );
+                let serviceFilePath = path.join( process.cwd(), serviceDefinition.serviceFile );
+                try {
+                    serviceHandler = require( serviceFilePath ).service;
+                } catch ( error ) {
+                    logger.log( `Specified service handler file '${ serviceFilePath }' could not be loaded!`, logger.logSeverity.ERROR, error );
                 }
             } else {
                 if ( typeof ( defaultServiceHandler ) === "function" ) {
@@ -160,7 +155,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 +168,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.2",
+  "version": "1.0.6",
   "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,10 +37,11 @@
     "#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": {
+    "blake2": "^4.0.2",
     "dotenv": "^10.0.0",
     "fs-extra": "^10.0.0",
     "lodash": "^4.17.21",
@@ -49,6 +51,10 @@
   "optionalDependencies": {
     "@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/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 );
     }