@ti-engine/core 1.1.1 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # ti-engine changelog
 
+## Version 1.1.2
+
+* feat(localization): add new functionality for localization based on labels and system language. It is currently utilized by the `exceptions` module for localizing the exception descriptions. The new `localization` module can also be accessed externally in the implementing application's files via standard import
+* feat(config): add new setting `localization.labelsPath` that specifies the file path for the localization labels
+* feat(config): add new setting `localization.language` that specifies the language to be used for the labels
+* feat(config): add new ENV variable `TI_LOCALIZATION_LABELS_PATH` that controls the `localization.labelsPath` setting
+* feat(config): add new ENV variable `TI_LOCALIZATION_LANGUAGE` that controls the `localization.language` setting
+* feat(logger): log exception label instead of system-level description
+* fix(start instance): fix the order of ENV loading in the `start-instance.js` script. It will now properly load the `.env` file first and then proceed with any configuration overrides in `config` module
+* fix(service provider): normalize service file paths on dynamic service handler loading
+* build(npm): update npm dependencies to their latest versions
+
 ## Version 1.1.1
 
 * feat(config): add new ENV variable `TI_AUDITING_LOG_DETAILS` that controls the `auditing.logDetails` setting

package/README.md

@@ -6,10 +6,6 @@ Flexible framework for the creation of microservices with [node.js](https://node
 
 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 architectural concept of the framework is based on a standard _messaging system_ that allows for certain customization but also provides predictability and traceability of its behavior.
 
-Being a messaging 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.
@@ -25,6 +21,10 @@ This is what you gain by using **ti-engine** in your project:
 
 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.
 
+## Overview
+
+Being a messaging 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.
+
 ## Prerequisites & installation
 
 In order to run the basic ti-engine framework you will need a couple of things:

package/bin/localization/labels.json

@@ -0,0 +1,65 @@
+{
+  "labels": {
+    "general": {
+      "exceptions": {
+        "0": {
+          "en": "Unidentified error encountered or unrecognized exception code provided."
+        },
+        "1000": {
+          "en": "Error thrown by internal JS source."
+        },
+        "1001": {
+          "en": "Attempt to construct an abstract class detected."
+        },
+        "1002": {
+          "en": "Attempt to call an abstract method detected."
+        },
+        "1003": {
+          "en": "Invalid or no service domain name provided at microservice startup."
+        },
+        "1004": {
+          "en": "The system cache required for proper engine operation is unavailable."
+        },
+        "1005": {
+          "en": "The provided service handler is not a proper function."
+        },
+        "1006": {
+          "en": "The requested feature is not supported by current configuration or version."
+        },
+        "2000": {
+          "en": "Invalid authorization token provided."
+        },
+        "2001": {
+          "en": "Invalid or expired session encountered."
+        },
+        "2002": {
+          "en": "Attempt for unauthorized access detected."
+        },
+        "2003": {
+          "en": "The system detected tampering with the message received via message exchange."
+        },
+        "3000": {
+          "en": "General error during cross-application communication."
+        },
+        "3001": {
+          "en": "The message sender instance is currently unavailable."
+        },
+        "3002": {
+          "en": "The execution of a service could not complete within the allowed timeout."
+        },
+        "3003": {
+          "en": "The specified service is not found in the service registry."
+        },
+        "3004": {
+          "en": "The specified service is not found in the service definition interface."
+        },
+        "3005": {
+          "en": "No handler found in the interface for the specified service or service version."
+        },
+        "3010": {
+          "en": "Connection retry attempts exceeded the configured limit."
+        }
+      }
+    }
+  }
+}

package/bin/settings.json

@@ -11,6 +11,10 @@
     "logName": "ti-engine",
     "projectID": ""
   },
+  "localization": {
+    "labelsPath": "../core/bin/localization/labels.json",
+    "language": "en"
+  },
   "memoryCache": {
     "authKey": null,
     "redisDB": 0,

package/bin/start-instance.js

@@ -7,12 +7,13 @@
 
 const _ = require( "lodash" );
 const path = require( "path" );
-const tools = require( "#tools" );
-const logger = require( "#logger" );
 
-// load any ENV variables defined in a .env file:
+// load any ENV variables defined in a .env file - before including any framework files:
 require( "dotenv" ).config( { path: path.join( process.cwd(), ".env" ) } );
 
+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 || "";

package/components/service-provider.js

@@ -138,7 +138,7 @@ class ServiceProvider extends ServiceConsumer {
             /** @type {ServiceHandlerMethod} */
             let serviceHandler = null;
             if ( serviceDefinition.serviceFile ) {
-                let serviceFilePath = path.join( process.cwd(), serviceDefinition.serviceFile );
+                let serviceFilePath = path.normalize( path.join( process.cwd(), serviceDefinition.serviceFile ) );
                 try {
                     serviceHandler = require( serviceFilePath ).service;
                 } catch ( error ) {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.1.1",
+  "version": "1.1.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",
   "exports": {
     "./exceptions": "./utils/exceptions.js",
+    "./localization": "./utils/localization.js",
     "./logger": "./utils/logger.js",
     "./service-consumer": "./components/service-consumer.js",
     "./service-instance": "./components/service-instance.js",
@@ -22,6 +23,7 @@
     "#default-message-sender": "./components/exchange/default/default-message-sender.js",
     "#exceptions": "./utils/exceptions.js",
     "#gcloud-integration": "./integrations/gcloud-integration.js",
+    "#localization": "./utils/localization.js",
     "#logger": "./utils/logger.js",
     "#message-dispatcher": "./components/exchange/message-dispatcher.js",
     "#message-exchange": "./components/exchange/message-exchange.js",
@@ -43,7 +45,7 @@
   "dependencies": {
     "blake2": "^5.0.0",
     "dotenv": "^16.3.1",
-    "fs-extra": "^11.1.1",
+    "fs-extra": "^11.2.0",
     "lodash": "^4.17.21",
     "node-schedule": "^2.1.1",
     "ioredis": "^5.3.2"
@@ -54,7 +56,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/Belleal/ti-engine.git"
+    "url": "git+https://github.com/Belleal/ti-engine.git"
   },
   "engines": {
     "node": ">=14.17.0"

package/utils/config.js

@@ -24,6 +24,8 @@ const tools = require( "#tools" );
  * @property {EnvironmentVariable} env.TI_AUDITING_LOG_DETAILS
  * @property {EnvironmentVariable} env.TI_AUDITING_LOG_MIN_LEVEL
  * @property {EnvironmentVariable} env.TI_AUDITING_LOG_USES_JSON
+ * @property {EnvironmentVariable} env.TI_LOCALIZATION_LABELS_PATH
+ * @property {EnvironmentVariable} env.TI_LOCALIZATION_LANGUAGE
  * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_AUTH_KEY
  * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_DB
  * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_HOST
@@ -43,6 +45,7 @@ const tools = require( "#tools" );
  * @typedef {Object} SettingsMain
  * @property {SettingsAuditing} auditing
  * @property {SettingsGcloudIntegration} gcloudIntegration
+ * @property {SettingsLocalization} localization
  * @property {SettingsMemoryCache} memoryCache
  * @property {SettingsMessageExchange} messageExchange
  * @property {SettingsServiceConfig} serviceConfig
@@ -63,6 +66,12 @@ const tools = require( "#tools" );
  * @property {string} projectID
  */
 
+/**
+ * @typedef {Object} SettingsLocalization
+ * @property {string} labelsPath
+ * @property {string} language
+ */
+
 /**
  * @typedef {Object} SettingsMemoryCache
  * @property {string} authKey
@@ -105,6 +114,8 @@ let settingsEnum = tools.enum( {
     AUDITING_LOG_USES_JSON: [ "auditing.logUsesJSON", "logUsesJSON", "" ],
     GCLOUD_API_KEY: [ "gcloudIntegration.apiKey", "apiKey", "" ],
     GCLOUD_PROJECT_ID: [ "gcloudIntegration.projectID", "projectID", "" ],
+    LOCALIZATION_LABELS_PATH: [ "localization.labelsPath", "labelsPath", "" ],
+    LOCALIZATION_LANGUAGE: [ "localization.language", "language", "" ],
     MEMORY_CACHE_AUTH_KEY: [ "memoryCache.authKey", "authKey", "" ],
     MEMORY_CACHE_REDIS_DB: [ "memoryCache.redisDB", "redisDB", "" ],
     MEMORY_CACHE_REDIS_HOST: [ "memoryCache.redisHost", "redisHost", "" ],
@@ -140,6 +151,10 @@ if ( settings.auditing ) {
     settings.auditing.logMinLevel = ( process.env.TI_AUDITING_LOG_MIN_LEVEL !== undefined ) ? process.env.TI_AUDITING_LOG_MIN_LEVEL : settings.auditing.logMinLevel;
     settings.auditing.logUsesJSON = ( process.env.TI_AUDITING_LOG_USES_JSON !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_USES_JSON ) : settings.auditing.logUsesJSON;
 }
+if ( settings.localization ) {
+    settings.localization.labelsPath = ( process.env.TI_LOCALIZATION_LABELS_PATH !== undefined ) ? process.env.TI_LOCALIZATION_LABELS_PATH : settings.localization.labelsPath;
+    settings.localization.language = ( process.env.TI_LOCALIZATION_LANGUAGE !== undefined ) ? process.env.TI_LOCALIZATION_LANGUAGE : settings.localization.language;
+}
 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_REDIS_DB !== undefined ) ? process.env.TI_MEMORY_CACHE_REDIS_DB : settings.memoryCache.redisDB;

package/utils/localization.js

@@ -0,0 +1,27 @@
+/*
+ * SPDX-FileCopyrightText: © 2021-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * SPDX-License-Identifier: ICU
+ */
+
+const _ = require( "lodash" );
+const path = require( "path" );
+const config = require( "#config" );
+
+const labelsPath = path.normalize( path.join( process.cwd(), config.getSetting( config.setting.LOCALIZATION_LABELS_PATH ) ) );
+const labels = require( labelsPath );
+const defaultEmptyLabel = "!!! label not found !!!";
+
+// prevent further modifications to the labels object:
+Object.freeze( labels );
+
+/**
+ * Used to return the textual value for a label based on the current system language.
+ *
+ * @method
+ * @param {string} label This should be a dot-separated JSON path string.
+ * @returns {string}
+ * @public
+ */
+module.exports.getLabel = ( label ) => {
+    return _.get( labels, label + "." + config.getSetting( config.setting.LOCALIZATION_LANGUAGE ), defaultEmptyLabel );
+};

package/utils/logger.js

@@ -6,6 +6,7 @@
 const _ = require( "lodash" );
 const tools = require( "#tools" );
 const exceptions = require( "#exceptions" );
+const localization = require( "#localization" );
 
 /**
  * Enum for specifying the log entry severity. This is based on the Google Stackdriver severity levels.
@@ -52,7 +53,7 @@ module.exports.getSeverityName = ( severity ) => {
 const exceptionToLog = ( exception ) => {
     return {
         exceptionID: exception.id,
-        description: exception.description,
+        description: localization.getLabel( exception.label ),
         details: !_.isEmpty( exception.data ) ? exception.data : undefined
     };
 };