@ti-engine/core 1.0.1 → 1.0.2

package/README.md

@@ -6,7 +6,7 @@ The **@ti-engine/core** is an open source, free to use - both for personal and c
 
 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.
 
-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.
 
 ## prerequisites & installation
 In order to run the basic ti-engine framework you will need a couple of things:
@@ -16,6 +16,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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",
@@ -40,13 +40,14 @@
     "#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"
   },
   "engines": {
     "node": ">=14.17.0"

package/start-instance.js

@@ -0,0 +1,107 @@
+/*
+ * 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.
+ * 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/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 ) {