@ti-engine/core 1.3.3 → 1.3.6

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 This document will contain the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.3.6
+* feat(exceptions): add new exception code `E_GEN_INVALID_ARGUMENT_TYPE`
+* feat(exceptions): add public enum with all HTTP codes exported as `httpCode` and typedef `TiHttpCode`. Use it as the type for the `httpCode` exception property
+* feat(tools): add `description` property to enum objects
+* feat(tools): add `contains` property to enum objects
+* feat(tools)!: change enum factory behavior to create a copy of the seed object instead of modifying it (may break code relying on seed object mutation)
+* refactor(exceptions): invalid `httpCode` inputs are coerced to `undefined`; `Exception.asJSON` includes `httpCode` only when defined
+* refactor(tools): deprecate method `getEnumName` in favor of `enum.name`; removal planned for 1.4.0
+* refactor(tools)!: remove method `createCSVFile` as it is unnecessary for the framework's operation. It also eliminates the dependency from `fs-extra` package
+* refactor(tools)!: disallow reserved keys as enum names; make enum properties non-enumerable and freeze the enum object to enforce immutability (may affect code relying on enumeration/extension)
+* fix(tools): fix a bug in the `RetryPolicy` class that caused the `maxAttempts` property to be ignored
+* build(npm): update npm dependencies to their latest versions
+* build(npm): remove `fs-extra` package as it is not used by the framework
+* build(npm)!: bump the minimum supported Node.js version to 18.0.0
+
+## Version 1.3.5
+* fix(redis integration): fix a duplicated log entry on connection ready event if multiple observers are registered
+* feat(service caller)!: change log level of error result in `process` method from `ERROR` to `DEBUG`. Implementers are expected to handle this and decide if the error should be propagated further or not
+* docs: update and fix various issues with the `README.md` file
+
+## Version 1.3.4
+* fix(service instance): fix the way `ServiceConfiguration` is propagated via child classes and remove unnecessary defaults. Also update the relevant JSDoc
+
 ## Version 1.3.3
 * feat(exceptions): add new parameter `includeData` to `Exception.asJSON` method which allows the exclusion of the data parameter from the returned JSON
 * feat(exceptions): remove several excessive exception codes that were unlikely to be used

package/README.md

@@ -1,5 +1,11 @@
 # ti-engine core
 
+![GitHub top language](https://img.shields.io/github/languages/top/Belleal/ti-engine)
+![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/Belleal/ti-engine)
+![npms.io (scoped package)](https://img.shields.io/npms-io/maintenance-score/%40ti-engine/core)
+![npms.io (scoped package)](https://img.shields.io/npms-io/popularity-score/%40ti-engine/core)
+![npms.io (scoped package)](https://img.shields.io/npms-io/quality-score/%40ti-engine/core)
+
 Flexible framework for the creation of microservices with [node.js](https://nodejs.org/).
 
 ## Introduction
@@ -8,32 +14,32 @@ The **ti-engine** is an open source, free to use—both for personal and commerc
 
 ## 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.
+The framework is created based on a decade of professional experience with the utilized technologies and architectural approach. Its primary goal is to provide you with a lightweight and flexible solution that can help you quickly build 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
+* **Simplicity**: Begin productive work within minutes and get to codding your 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
 
-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. For now let's focus on the default setup.
+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. For now let's focus on the default setup.
 
-In order to run the basic ti-engine framework, you will need a couple of things:
+To run the basic **ti-engine** framework, you will need a couple of things:
 
-* A local [node.js installation](https://nodejs.org/en/download/) with a minimum version of **14.17.0**
+* A local [node.js installation](https://nodejs.org/en/download/) with a minimum version of **18.0.0**
 * A local or remote [Redis cache installation](https://redis.io/download) with a minimum version of **5.0.14**
 
-If you are working under Windows 10+ OS and you need to install Redis, take a look at this [guide](https://redis.com/blog/redis-on-windows-10/). You could also use [Redis Cloud](https://app.redislabs.com/) for development purposes as it offers free basic account. You can configure your connection to a remote Redis server using the following ENV variables:
+If you are working under Windows 10+ OS and you need to install Redis, take a look at this [guide](https://redis.com/blog/redis-on-windows-10/). You could also use [Redis Cloud](https://app.redislabs.com/) for development as it offers a free basic account. You can configure your connection to a remote Redis server using the following ENV variables:
 
 * `TI_MEMORY_CACHE_AUTH_KEY` can be used to provide the Redis password if there is any at all.
-* `TI_MEMORY_CACHE_REDIS_DB` can be used to specify the Redis DB you want to use. Make sure to set the correct number as for example Redis Cloud only uses DB `0`.
+* `TI_MEMORY_CACHE_REDIS_DB` can be used to specify the Redis DB you want to use. Make sure to set the correct number as, for example, Redis Cloud only uses DB `0`.
 * `TI_MEMORY_CACHE_REDIS_HOST` can be used to provide the remote host. This can be an IP or URL depending on your setup.
 * `TI_MEMORY_CACHE_REDIS_PORT` can be used to provide the remote port. By default, Redis uses `6379` however many implementations might use a custom port that needs to be specified in the connection settings.
 
@@ -41,10 +47,10 @@ To get the framework itself, use the command `npm install @ti-engine/core`. And
 
 ## Getting started
 
-To start using the **ti-engine**, you will have to make sure that all prerequisites are available and operational. However, before we get to the fun part you need to also consider a couple of very important things while working with this framework:
+To start using the **ti-engine**, you will have to make sure that all prerequisites are available and operational. However, before we get to the fun part, you need to also consider a couple of crucial things while working with this framework:
 
 1. The runtime configuration of the framework can be customized using ENV variables. These can be provided to node.js in all the standard ways, but there is also an option to include an `.env` file.
-2. It loads your framework-related custom scripts and files dynamically, but it always assumes their provided paths are relative to the _current working directory_ (i.e. it uses `process.cwd()`). Be mindful of that whenever you declare file paths in the various settings.
+2. It loads your framework-related custom scripts and files dynamically, but it always assumes their provided paths are relative to the _current working directory_ (i.e., it uses `process.cwd()` to resolve the file paths). Be mindful of that whenever you declare file paths in the various settings.
 
 Once you have everything else 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:
 
@@ -54,54 +60,59 @@ Once you have everything else ready, you should download the **ti-engine** teste
 3. If everything was done properly, you should see the following output:
 
 ```text
-[timestamp]: [instance-id] - notice - Starting new instance of type 'tester-service' with instance ID '[instance-id]'.
+[timestamp]: [instance-id] - notice - Starting new instance of type 'ti-tester-service' with instance ID '[instance-id]'.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'system-cache' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'connection-msg-responses-out' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'connection-msg-requests-in' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'connection-msg-requests-out' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'connection-msg-responses-in' and is ready to be used.
 [timestamp]: [instance-id] - info - Starting service registration process. There is NO default service handler provided.
 [timestamp]: [instance-id] - info - Registration of defined services completed with 2 successful out of 2 total.
 [timestamp]: [instance-id] - notice - Instance '[instance-id]' started successfully.
-   » {"nodeVersion":[node-version]}
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'connection-msg-responses-out' and is ready to be used.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'system-cache' and is ready to be used.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'connection-msg-requests-in' and is ready to be used.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'connection-msg-requests-out' and is ready to be used.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'connection-msg-responses-in' and is ready to be used.
-[timestamp]: [instance-id] - notice - Execution of service1 result:
+   » {"nodeVersion":[node-version],"operationMode":[mode]}
+[timestamp]: [instance-id] - info - Execution of 'Test 1: Service call to a simple service without chained services' successful.
    » {"isSuccessful":true,"payload":{"s1Timestamp":[timestamp]}}
-[timestamp]: [instance-id] - notice - Execution of service2 result:
+[timestamp]: [instance-id] - info - Execution of 'Test 2: Service call to a simple service with one chained service' successful.
    » {"isSuccessful":true,"payload":{"s1Timestamp":[timestamp],"s2TimestampStart":[timestamp],"s2TimestampEnd":[timestamp]}}
+[timestamp]: [instance-id] - info - Execution of 'Test 3: Service call to a non-existent service' successful.
+   » {"isSuccessful":false,"exception":{"exceptionID":[exception-id],"description":"The specified service is not found in the service registry."}}
+[timestamp]: [instance-id] - notice - All service tests completed. Passed 3 out of 3.
 ```
 
-Now let's analyse that output. For the sake of completeness, the `[timestamp]` and `[instance-id]` are placeholders of the actual values you'll see there. The timestamps are in UTC and show a date followed by time.
+Now let's analyze that output. For the sake of completeness, the `[timestamp]` and `[instance-id]` are placeholders of the actual values you'll see there. The timestamps are in UTC and show a date followed by time.
 
-At the start of the output log you can see a NOTICE that tells you a couple of important things:
+At the start of the output log, you can see a `NOTICE` that tells you a couple of important things:
 
-* The instance name - in this case `tester-service`. In the terminology of the framework, this is also known as a _service domain name_.
+* The instance name - in this case `ti-tester-service`. In the terminology of the framework, this is also known as a _service domain name_.
 * The _instance identifier_. It is an uuid string with a `ti-` prefix, that is generated by the framework at process start. It can and will be used to trace the messages during their movement through the microservice ecosystem. But more on that later.
 
-Following that come a couple of INFO lines that inform you about the microservice interface state. The framework starts with the process of registration of _business services_ within the service domain of the microservice `tester-service` and successfully adds 2 such services. The necessary information for this is read from a JSON config file included in the package. We'll get into more details on what this all means in the section [Creating a microservice](#creating-a-microservice).
+The following five `INFO` lines inform you about the successful connections to Redis. The default configuration assumes that your Redis is running on localhost and uses the default port. If you have a different setup, you can provide the host and port via ENV variables. We'll cover that in the section [Using the framework](#using-the-framework).
+
+Following that come a couple of `INFO` lines that inform you about the microservice interface state. The framework starts with the process of _business services_ registration within the service domain of the microservice `ti-tester-service` and successfully adds two such services. The necessary information for this is read from a JSON config file included in the package. We'll get into more details on what this all means in the section [Creating a microservice](#creating-a-microservice).
+
+Once the initialization sequence has completed, the framework informs you that the microservice instance has started successfully with a `NOTICE` entry.
 
-Once the initialization sequence has completed the framework informs you that the microservice instance has started successfully. If the framework encountered an error during initialization instead, you would see something like this:
+If the framework encountered an error during initialization instead, you would see something like this instead:
 
 ```text
-[timestamp]: [instance-id] - notice - Starting new instance of type 'tester-service' with instance ID '[instance-id]'.
+[timestamp]: [instance-id] - notice - Starting new instance of type 'ti-tester-service' with instance ID '[instance-id]'.
 [timestamp]: [instance-id] - alert - Error detected in the instance startup script!
 ```
 
-The following 5 lines inform you about the successful connection to Redis. The default configuration assumes that your Redis is running on localhost and uses the default port. If you have a different setup, you can provide the host and port via ENV variables. We'll cover that in the section [Using the framework](#using-the-framework).
-
-Finally, you should see a couple of execution statements with their results in JSON format.
+Finally, you should see a sequence of test execution statements with their results in JSON format. These are the results of three business service calls that are part of the default tester microservice. The final `NOTICE` should indicate that all three tests have been completed successfully.
 
 You can now kill the node process which should show you the following two lines:
 
 ```text
-[timestamp]: [instance-id] - notice - SIGINT event detected in main instance process.
+[timestamp]: [instance-id] - notice - [signal-code] event detected in main instance process.
 [timestamp]: [instance-id] - notice - Instance '[instance-id]' shut down successfully.
 ```
 
-The framework will always try to capture the shut-down event and log it. This should work even in container environment, but it might depend on your setup whether the last two entries will reach the logging system or not.
+The framework will always try to capture the shut-down event and log it with the correct `[signal-code]`. This should work even in a container environment, but it might depend on your setup whether the last two entries will reach the logging system or not.
 
 The tester module gets its starting configuration from an `.env` file included in the package. You can find more information about it later in the [Creating a microservice](#creating-a-microservice) section.
 
-Before moving on, also take a good look at the file `bin/start-instance.js`. It should give you an idea on how to the process of starting and stopping a microservice operates. In most cases this file should be sufficient as a starting script for your **ti-engine** based microservice applications. You can, of course, create your own starting script, but then you'll have to consider all necessary steps to properly handle the microservice instance.
+Before moving on, also take a good look at the file `bin/start-instance.js`. It should give you an idea of how the process of starting and stopping a microservice operates. In most cases this file should be enough as a starting script for your **ti-engine** based microservice applications. You can, of course, create your own starting script, but then you'll have to consider all necessary steps to properly handle the microservice instance.
 
 ## Architecture
 
@@ -117,46 +128,46 @@ See the following sections for more information on each of them.
 
 ### Tier 1 - Message exchange
 
-This is the lowest framework tier, unless we count the actual data objects processed by the framework. As you already know, the foundational **ti-engine** concept is that of a messaging system. Therefore, the first tier provides an abstraction over a chosen message broker (Redis by default). That abstraction makes it easy to switch between message brokers whenever you want to without having to change anything above tier 1. It also provides several added bonuses that can accelerate your work—message encryption, message tracing, message observers, and others. More details about each of these features will be covered in section [Using the framework](#using-the-framework).
+This is the lowest framework tier, unless we count the actual data objects processed by the framework. As you already know, the foundational **ti-engine** concept is that of a messaging system. Therefore, the first tier provides an abstraction over a chosen message broker (Redis by default). That abstraction makes it easy to switch between message brokers whenever you want to without having to change anything above tier 1. It also provides several bonuses that can speed up your work—message encryption, message tracing, message observers, and others. More details about each of these features will be covered in the section [Using the framework](#using-the-framework).
 
-Another important aspect for you to remember is that the message exchange is entirely _asynchronous_. This helps reduce system load and optimizes the usage of the available resources. Even so each node.js process can handle a limited amount of load. Therefore, you should plan for running multiple identical senders and receives in order to scale your solution. But more on that later.
+Another important aspect for you to remember is that the message exchange is entirely _asynchronous_. This helps reduce the system load and optimizes the usage of the available resources. Even so, each node.js process can handle a limited load. Therefore, you should plan for running multiple identical senders and receives to scale your solution. But more on that later.
 
 For now, take a look at the following diagram:
 
-![Message Exchange](https://github.com/Belleal/ti-engine/blob/master/core/docs/diagram1.png)
+![Message Exchange](https://github.com/Belleal/ti-engine/blob/master/packages/core/docs/diagram1.png)
 
-It shows the standard flow of a message exchange between one sender and _n_ identical message receivers. The sender splits each message into an _envelope_ and a _payload_, then stores the payload in the shared cache and enqueues the envelope in the requests (destination) queue. Receivers can subscribe to that queue in order to fetch enqueued messages and process their contents. During the fetch sequence a receiver assembles the full message by getting the payload from the storage. This process is depicted by the blue flow lines.
+It shows the standard flow of a message exchange between one sender and _n_ identical message receivers. The sender splits each message into an _envelope_ and a _payload_, then stores the payload in the shared cache and enqueues the envelope in the requests (destination) queue. Receivers can subscribe to that queue to fetch enqueued messages and process their contents. During the fetch sequence a receiver assembles the full message by getting the payload from the storage. This process is depicted by the blue flow lines.
 
-After the processing is done the message payload is modified and the receiver sends the message back to the original sender using the same mechanism. It again splits the message into an envelope and a payload, stores the payload in the storage and enqueues the envelope in the sender response (source) queue. The sender will then assemble the message back and process the contained results. This process is depicted by the red flow lines.
+After the processing is done, the message payload is modified, and the receiver sends the message back to the original sender using the same mechanism. It again splits the message into an envelope and a payload, stores the payload in the storage and enqueues the envelope in the sender response (source) queue. The sender will then assemble the message back and process the contained results. This process is depicted by the red flow lines.
 
-In this scenario the framework utilizes _Redis lists_ as queues for the message envelopes and _Redis hash_ as message payload storage. The splitting between envelope and payload is done in order to avoid unnecessary transportation of potentially large volumes of operational data between the microservices. Other message brokers might utilize a slightly different approach, but they should still adhere to the same logical flow.
+In this scenario the framework uses _Redis lists_ as queues for the message envelopes and _Redis hash_ as message payload storage. The splitting between envelope and payload is done to avoid unnecessary transportation of potentially large volumes of operational data between the microservices. Other message brokers might use a slightly different approach, but they should still adhere to the same logical flow.
 
 The modules associated with this tier are all located in the `components/exchange/` folder. This is a short list of some terminology used here and in the JDoc inside the sourcecode itself:
 
-* Message - this is the actual data object processed by the framework. It consists of two parts: an envelope containing service information and a payload containing the actual data to be processed.
-* Message sender - a specialized connector that is responsible for sending a message on its way to its destination. It does not handle the actual dispatch and delivery.
-* Message receiver - a specialized connector that is responsible for receiving messages at predefined destination.
-* Message exchange - this is the actual message processing engine. It handles sending and receiving messages via preconfigured message senders and message receivers.
-* Message observer - a custom event listener that can be used to react on message `sent` and `received` events.
+* Class `Message`: a message is the actual data object processed by the framework. It consists of two parts—an envelope containing service information and a payload containing the actual data to be processed.
+* Class `MessageSender`: a sender a specialized connector that is responsible for sending a message on its way to its destination. It does not handle the actual dispatch and delivery.
+* Class `MessageReceiver`: a receiver is a specialized connector that is responsible for receiving messages at a predefined destination.
+* Class `MessageExchange`: the exchange is the actual message processing engine. It handles sending and receiving messages via preconfigured message senders and message receivers.
+* Class `MessageObserver`: an observer is a custom event listener that can be used to react on message `sent` and `received` events.
 
 ### Tier 2 - Service domains
 
-This tier focuses on hosting and executing the _business logic_ of your application. It's comprised of _business services_ that process input data and return the result of the processing as output data. The business services are grouped in _service domains_, which are in turn hosted inside stateless _microservices_ also named _service instances_. There are two types of service instances in **ti-engine**:
+This tier focuses on hosting and executing the _business logic_ of your application. It consists of _business services_ that process input data and return the result of the processing as output data. The business services are grouped in _service domains_, which are in turn hosted inside stateless _microservices_ also named _service instances_. All microservices are based on the `ServiceInstance` class, which establishes the basic framework structure and provides the basic functionality for the microservice lifecycle. It should not be used directly, however. Instead, there are two child types of `ServiceInstance` in **ti-engine** that you should use to implement your solution:
 
-* Service consumers - these are service instances, that can call business services in any connected and available service domain.
-* Service providers - these are service instances, that host and run a set of business services in a particular service domain. Every service provider is also a service consumer.
+* Class `ServiceConsumer`: consumers are service instances that can call business services in any connected and available service domain.
+* Class `ServiceProvider`: providers are service instances that host and run a set of business services in a particular service domain. Every service provider is also a service consumer.
 
-The various service instances in a solution represent a network of interconnected service domains that contain the business logic of your application. All business services exchange data via _service calls_ using abstract _service addresses_. These service calls are transported from one address in the microservice network to another via the underlying message exchange tier. This, however, is completely transparent to the service instances. In essence, tier 2 does not care about the actual data transportation method or protocol. You could in fact change completely the tier 1 approach without having to modify anything in your business logic and business flow.
+The various service instances in a solution represent a network of interconnected service domains that contain the business logic of your application. All business services exchange data via _service calls_ using abstract _service addresses_. These service calls are transported from one address in the microservice network to another via the underlying message exchange tier. This, however, is completely transparent to the service instances. In essence, tier 2 does not care about the actual data transportation method or protocol. You could, in fact, completely change the tier 1 approach without having to modify anything in your business logic and business flow.
 
-This tier is the place to utilize any databases, file storages, integrations with other applications, scheduling jobs, and so on. In general, it should focus on executing any granular tasks that are essential to the backbone operation of your application. The business logic here should remain **stateless** and any user context should be provided at runtime to each invoked business service. We'll see more concrete examples for that later in section [Using the framework](#using-the-framework).
+This tier is the place to use any databases, file storages, integrations with other applications, scheduling jobs, and so on. In general, it should focus on executing any granular tasks that are essential to the backbone operation of your application. The business logic here should remain **stateless** and any user context should be provided at runtime to each invoked business service. We'll see more concrete examples for that later in the section [Using the framework](#using-the-framework).
 
 ### Tier 3 - Solution implementation
 
-This tier comprises the actual implementation of your application. Its structure and behavior depends entirely on your vision and business goals. There are still a couple of points that remain constant while using **ti-engine**:
+This tier comprises the actual implementation of your application. Its structure and behavior depend entirely on your vision and business goals. There are still a couple of points that remain constant while using **ti-engine**:
 
-* It needs to utilize the business logic defined in tier 2 by calling the business services
-* It needs to take care of any type of stateful behavior like user sessions or transactions
-* It needs to act as the primary interface between users and your application thus handling access management and user interactions
+* It needs to use the business logic defined in tier 2 by calling the business services.
+* It needs to take care of any type of stateful behavior like user sessions or transactions.
+* It needs to act as the primary interface between users and your application, thus handling access management and user interactions.
 
 Depending on the type of software you are building, tier 3 can be an API Gateway, a Web application, backend for a Mobile application or anything like that.
 
@@ -215,31 +226,31 @@ TI_INSTANCE_NAME=tester-service
 TI_AUDITING_LOG_MIN_LEVEL=200
 ```
 
-The ENV initialization file provides the minimal settings for the proper tester microservice operation. The first three are usually _mandatory_ for every microservice you create while the last is provided for the needs of the tester demonstration. Let's review them and see what they do:
+The ENV initialization file provides the minimal settings for the proper tester microservice operation. The first three are usually _mandatory_ for every microservice you create, while the last is provided for the needs of the tester demonstration. Let's review them and see what they do:
 
-* `TI_INSTANCE_CLASS` specifies the relative path to the implementation of the `ServiceInstance` framework class—in this case a `ServiceProvider`. As stated above, the path is relative to the working directory of the `node` process. This variable is mandatory for every microservice you create with the **ti-engine**. If it is not provided the microservice won't be able to start at all, and you will get an exception.
-* `TI_INSTANCE_CONFIG` specifies the relative path to the configuration data for the microservice. We'll delve into the specific settings below. Technically, you can omit this variable and the microservice will still start successfully with an empty configuration. There are very few cases, however, where this would be applicable.
-* `TI_INSTANCE_NAME` is the _service domain_ name provided for the microservice. It has to be _unique_ in the context of the microservice ecosystem. If not provided, the framework will attempt to extract this information from the name of the implementation file. That is not a recommended approach though as it might cause hard to identify errors later.
-* `TI_AUDITING_LOG_MIN_LEVEL` specifies the minimum log level that should be sent to the log output stream. With a setting of `200` (corresponding to INFO) we filter out all `DEFAULT(0)` and `DEBUG(100)` entries as we don't need them for the purposes of the tester microservice.
+* `TI_INSTANCE_CLASS` specifies the relative path to the implementation of the `ServiceInstance` framework class—in this case a `ServiceProvider`. As stated above, the path is relative to the working directory of the `node` process. This variable is mandatory for every microservice you create with the **ti-engine**. If it is not provided, the microservice won't be able to start at all, and you will get an exception.
+* `TI_INSTANCE_CONFIG` specifies the relative path to the configuration data for the microservice. We'll delve into the specific settings below. Technically, you can omit this variable, and the microservice will still start successfully with an empty configuration. There are very few cases, however, where this would be applicable.
+* `TI_INSTANCE_NAME` is the _service domain_ name provided for the microservice. It has to be _unique_ in the context of the microservice ecosystem. If not provided, the framework will attempt to extract this information from the name of the implementation file. That is not a recommended approach, though, as it might cause hard to identify errors later.
+* `TI_AUDITING_LOG_MIN_LEVEL` specifies the minimum log level that should be sent to the log output stream. With a setting of `200` (corresponding to INFO) we filter out all `DEFAULT(0)` and `DEBUG(100)` entries as we don't need them for the tester microservice.
 
 You can find the full list of available ENV variables and what they do below in [Using the framework](#using-the-framework) section.
 
-#### Application specific files
+#### Application-specific files
 
 Now let's look inside the `bin` folder. The two files there are the ones specified in the `.env` file. The `tester-service.js` contains the implementation of the `ServiceProvider` class. It has just a few methods that contain its behavior:
 
-* Method `onStart` overrides the base one from the parent class and is invoked automatically by the framework once initialization of the microservice is complete. In this case the method invokes the execution of the test sequence just once and then the microservice remains dormant but active.
+* Method `onStart` overrides the base one from the parent class and is invoked automatically by the framework once initialization of the microservice is complete. In this case the method invokes the execution of the test sequence just once, and then the microservice remains dormant but active.
 * Method `reportHealthy` overrides but essentially just calls the same base method. Its only purpose here is to draw your attention to its existence and the possibility to implement your own health status reporting functionality if you want.
 * Method `verifyAccess` also overrides the base method and shows a very basic example of how to implement user access verification on business service level. Each time a service in the `ti-tester-service` is called, the framework will trigger this method and will only allow processing if there is a non-undefined value inside the `authToken` variable.
-* Method `#executeTests` is a custom private method that contains the test sequence itself. It is called by the `onStart` method just once per microservice start. Inside you can see two examples of calling a business service—in both cases the tester microservice is calling itself. In more practical situation, however, these calls would be directed towards other service domains.
+* Method `#executeTests` is a custom private method that contains the test sequence itself. It is called by the `onStart` method just once per microservice start. Inside you can see two examples of calling a business service—in both cases the tester microservice is calling itself. In a more practical situation, however, these calls would be directed towards other service domains.
 
-The file `tester-service.json` contains framework configuration for the tester microservice. It will be automatically loaded inside the `ServiceInstance` class during initialization and will already be available inside the `onStart` method for usage. In this case the configuration is related to the two business services that will be provided by the microservice. More on this topic will be covered in section [Using the framework](#using-the-framework). For now just pay attention to the `serviceFile` parameter and that it once again provides a relative path to the actual file containing the business logic.
+The file `tester-service.json` contains framework configuration for the tester microservice. It will be automatically loaded inside the `ServiceInstance` class during initialization and will already be available inside the `onStart` method for usage. In this case the configuration is related to the two business services that will be provided by the microservice. More on this topic will be covered in the section [Using the framework](#using-the-framework). For now pay attention to the `serviceFile` parameter and that it once again provides a relative path to the actual file containing the business logic.
 
-The final two files are located in `bin/services/v1/` folder. They contain the definitions and business logic of the two business services that will be loaded at initialization time and provided by the tester microservice. In this case `service1.js` contains a very simple service that returns the current timestamp. The `service2.js` file contains a slightly more complex example of a service calling another service (in this case `service1`) before also returning two timestamps taken at the beginning and end of execution. Pay attention to the way the methods inside are declared and exported as this is the proper way to do this while using the **ti-engine** framework. Once again, we'll delve into the details and specifics of creating business services in section [Using the framework](#using-the-framework).
+The final two files are located in `bin/services/v1/` folder. They contain the definitions and business logic of the two business services that will be loaded at initialization time and provided by the tester microservice. In this case `service1.js` contains a basic service that returns the current timestamp. The `service2.js` file contains a slightly more complex example of a service calling another service (in this case `service1`) before also returning two timestamps taken at the beginning and end of execution. Pay attention to the way the methods inside are declared and exported as this is the proper way to do this while using the **ti-engine** framework. Once again, we'll delve into the details and specifics of creating business services in the section [Using the framework](#using-the-framework).
 
 ### Creating your own microservice
 
-Now that we've seen the structure of the tester microservice, let's create a new one and make it call `service2`. Let's use similar file structure as for the tester. Create a folder `my-service` and in it create a `package.json` file. Make sure to include a dependency to `"@ti-engine/core": "latest"` in it. After that create a `.env` file and add the following entries in it:
+Now that we've seen the structure of the tester microservice, let's create a new one and make it call `service2`. Let's use the same file structure as for the tester. Create a folder `my-service` and in it create a `package.json` file. Make sure to include a dependency to `"@ti-engine/core": "latest"` in it. After that create a `.env` file and add the following entries in it:
 
 ```text
 TI_INSTANCE_CLASS=bin/my-service.js
@@ -258,7 +269,7 @@ class MyService extends ServiceConsumer {}
 module.exports = MyService;
 ```
 
-Don't forget to also export your new class at the end, otherwise the framework won't be able to initialize it.
+Remember to also export your new class at the end, otherwise the framework won't be able to initialize it.
 
 To make use of all the inherited features of the `ServiceConsumer` class we have to add a `constructor` that invokes the base one in the parent class:
 
@@ -274,7 +285,7 @@ class MyService extends ServiceConsumer {
 module.exports = MyService;
 ```
 
-And now let's add a service call that is executed at microservice start after `500` milliseconds timeout:
+And now let's add a service call executed at microservice start after `500` milliseconds timeout:
 
 ```js
 const ServiceConsumer = require( "@ti-engine/core/service-consumer" );
@@ -311,40 +322,40 @@ class MyService extends ServiceConsumer {
 module.exports = MyService;
 ```
 
-Now let's start the new microservice with `node .\node_modules\@ti-engine\core\bin\start-instance.js` command. Remember, you need to execute this inside the `my-service` folder you created for this exercise. If everything was configured correctly you should get the following output:
+Now let's start the new microservice with `node .\node_modules\@ti-engine\core\bin\start-instance.js` command. Remember, you need to execute this inside the `my-service` folder you created for this exercise. If everything was configured correctly, you should get the following output:
 
 ```text
 [timestamp]: [instance-id] - notice - Starting new instance of type 'my-service' with instance ID '[instance-id]'.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'connection-msg-responses-in' and is ready to be used.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'connection-msg-requests-out' and is ready to be used.
-[timestamp]: [instance-id] - info - Connection to Redis server 127.0.0.1:6379 (re)established by client 'system-cache' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'system-cache' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'connection-msg-responses-in' and is ready to be used.
+[timestamp]: [instance-id] - info - Connection to Redis server '127.0.0.1:6379' established by client 'connection-msg-requests-out' and is ready to be used.
 ```
 
 If you haven't started anything else, this is all you should see at this point.
 
-Now without exiting this node process let's start the original tester microservice as well. Once it initializes and does its work take a look at the output logs of the `my-service` process:
+Now without exiting this node process, let's start the original tester microservice as well. Once it initializes and does its work take a look at the output logs of the `my-service` process:
 
 ```text
 ...
-[timestamp]: [instance-id] - notice - Execution of service2 result:
-   » {"isSuccessful":true,"payload":{"s1Timestamp":[timestamp],"s2TimestampStart":[timestamp],"s2TimestampEnd":[timestamp]}}
 [timestamp]: [instance-id] - notice - Instance [instance-id] started successfully.
    » {"nodeVersion":[node-version]}
+[timestamp]: [instance-id] - notice - Execution of service2 result:
+   » {"isSuccessful":true,"payload":{"s1Timestamp":[timestamp],"s2TimestampStart":[timestamp],"s2TimestampEnd":[timestamp]}}
 ```
 
-This means the service call processing was successful and result was returned to `my-service`. Because we made the receiving of the result blocking and part of the initialization sequence, the new microservice did not report successful startup until it received that response from `ti-tester-service`.
+This means the service call processing was successful and a result was returned to `my-service`. Because we made the receiving of the result blocking and part of the initialization sequence, the new microservice did not report successful startup until it received that response from `ti-tester-service`.
 
-And with this step we are done. The new microservice is now operational. You can continue to tweak and play with it in order to understand better how it all works. For more details on the **ti-engine** inner working please see the following sections.
+And with this step we are done. The new microservice is now operational. You can continue to tweak and play with it to understand better how it all works. For more details on the **ti-engine** inner working, please see the following sections.
 
 ## Using the framework
 
 ### Environment variables
 
-These are the system-level ENV variables that can be used to configure the framework. Use a .env file or corresponding containerization features to set the variables you need. Not all of these are mandatory or even required for every microservice you create. Consult the documentation for more details.
+These are the system-level ENV variables that can be used to configure the framework. Use an `.env` file or corresponding containerization features to set the variables you need. Not all of these are mandatory or even required for every microservice you create. Consult the documentation for more details.
 
 TI_AUDITING_LOG_MIN_LEVEL
 : Type: Optional
-: Specifies the minimum log level that should be sent to the log output stream. The framework will filter out all log entries with level below this value. The default value is `200` (corresponding to INFO).
+: Specifies the minimum log level that should be sent to the log output stream. The framework will filter out all log entries with a level below this value. The default value is `200` (corresponding to INFO).
 
 TI_FAIL_FAST_ON_UNHANDLED_OFF
 : Type: Optional
@@ -352,39 +363,39 @@ TI_FAIL_FAST_ON_UNHANDLED_OFF
 
 TI_INSTANCE_CLASS
 : Type: Required
-: Specifies the relative path to the implementation of the `ServiceInstance` framework class—in this case a `ServiceProvider`. As stated above, the path is relative to the working directory of the `node` process. This variable is mandatory for every microservice you create with the **ti-engine**. If it is not provided the microservice won't be able to start at all, and you will get an exception.
+: Specifies the relative path to the implementation of the `ServiceInstance` framework class—in this case a `ServiceProvider`. As stated above, the path is relative to the working directory of the `node` process. This variable is mandatory for every microservice you create with the **ti-engine**. If it is not provided, the microservice won't be able to start at all, and you will get an exception.
 
 TI_INSTANCE_CONFIG
 : Type: Optional
-: Specifies the relative path to the configuration data for the microservice. Technically, you can omit this variable and the microservice will still start successfully with an empty configuration. There are very few cases, however, where this would be applicable.
+: Specifies the relative path to the configuration data for the microservice. Technically, you can omit this variable, and the microservice will still start successfully with an empty configuration. There are very few cases, however, where this would be applicable.
 
 TI_INSTANCE_NAME
 : Type: Required
-: Specifies the _service domain_ name provided for the microservice. It has to be _unique_ in the context of the microservice ecosystem. If not provided, the framework will attempt to extract this information from the name of the implementation file. That is not a recommended approach though as it might cause hard to identify errors later.
+: Specifies the _service domain_ name provided for the microservice. It has to be _unique_ in the context of the microservice ecosystem. If not provided, the framework will attempt to extract this information from the name of the implementation file. That is not a recommended approach, though, as it might cause hard to identify errors later.
 
 ### Framework settings
 
-Here you can find all settings used by **ti-engine** together with information on what they do. They are defined inside the `config` module and the full list can be accessed through the public `setting` enum. To get the current value of a setting, you can use the public method `getSetting` from the same module. Some settings can be overridden by providing ENV variables as specified below at node application start up.
+Here you can find all settings used by **ti-engine** together with information on what they do. They are defined inside the `config` module and the full list can be accessed through the public `setting` enum. To get the current value of a setting, you can use the public method `getSetting` from the same module. Some settings can be overridden by providing ENV variables as specified below at node application startup.
 
 AUDITING_LOG_CONSOLE_ENABLED
 : JSON path `auditing.logConsoleEnabled`, type `boolean`, default `true`
 : ENV variable `TI_AUDITING_LOG_CONSOLE_ENABLED`
-: This setting controls whether the `auditing` module will send the log entries to the OS console or not. In some cases, like Cloud environments, you might want to disable this, especially if the OS console is not made available. This functions independently of other logging outputs like for example GCloud error reporting.
+: This setting controls whether the `auditing` module will send the log entries to the OS console or not. In some cases, like Cloud environments, you might want to disable this, especially if the OS console is not made available. This functions independently of other logging outputs like, for example, GCloud error reporting.
 
 AUDITING_LOG_DETAILS
 : JSON path `auditing.logDetails`, type `boolean`, default `true`
 : ENV variable `TI_AUDITING_LOG_DETAILS`
-: This setting controls whether the `auditing` module will include the log entry details (located in the `data` property) in the final log output. You might want to disable this if you want a leaner log output or the log entry details are not something you plan to use for analysis later.
+: This setting controls whether the `auditing` module will include the log entry details (located in the `data` property) in the final log output. You might want to disable this if you want a leaner log output, or the log entry details are not something you plan to use for analysis later.
 
 AUDITING_LOG_MIN_LEVEL
 : JSON path `auditing.logMinLevel`, type `number`, default `0`
 : ENV variable `TI_AUDITING_LOG_MIN_LEVEL`
-: This setting controls the minimum log severity level that the framework will log in the log output. You can and should set this to `200` (INFO) for production environments in order to filter out the DEBUG and the low-level DEFAULT entries.
+: This setting controls the minimum log severity level that the framework will log in the log output. You can and should set this to `200` (INFO) for production environments to filter out the DEBUG and the low-level DEFAULT entries.
 
 AUDITING_LOG_USES_JSON
 : JSON path `auditing.logUsesJSON`, type `boolean`, default `false`
 : ENV variable `TI_AUDITING_LOG_USES_JSON`
-: This setting controls whether the log entries would be sent to output formatted as JSONs or not. By default, the framework outputs log entries as prettified text. In some cases however you might want to have the entire entry as a JSON for further processing (for example if you're sending all logs to Elasticsearch).
+: This setting controls whether the log entries would be sent to output formatted as JSONs or not. By default, the framework outputs log entries as prettified text. In some cases, however, you might want to have the entire entry as a JSON for further processing (for example, if you're sending all logs to Elasticsearch).
 
 GCLOUD_API_KEY (Alpha)
 : JSON path `gcloudIntegration.apiKey`
@@ -397,7 +408,7 @@ GCLOUD_PROJECT_ID (Alpha)
 LOCALIZATION_LABELS_PATH
 : JSON path `localization.labelsPath`, type `Array<string>`, default `[]`
 : ENV variable `TI_LOCALIZATION_LABELS_PATH`
-: This setting holds a list of paths to custom `.json` files containing additional localization information. By default, the framework also provides such a file with english texts that can be customized further. All additional JSONs in these files have to follow the rules and structure of the `localization` module. The ENV variable currently supports providing only a single custom path.
+: This setting holds a list of paths to custom `.json` files containing additional localization information. By default, the framework also provides such a file with English texts that can be customized further. All additional JSONs in these files have to follow the rules and structure of the `localization` module. The ENV variable currently supports providing only a single custom path.
 
 LOCALIZATION_LANGUAGE
 : JSON path `localization.language`, type `string`, default `en`
@@ -407,12 +418,12 @@ LOCALIZATION_LANGUAGE
 MEMORY_CACHE_AUTH_KEY
 : JSON path `memoryCache.authKey`, type `string`, default `undefined`
 : ENV variable `TI_MEMORY_CACHE_AUTH_KEY`
-: This setting holds the Redis password for accessing the Redis server if such password is required.
+: This setting holds the Redis password for accessing the Redis server if such a password is required.
 
 MEMORY_CACHE_REDIS_DB
 : JSON path `memoryCache.redisDB`, type `number`, default `0`
 : ENV variable `TI_MEMORY_CACHE_REDIS_DB`
-: This setting specifies the Redis DB to be used for all operations. When setting this make sure that the Redis server actually supports multiple DBs (for example Redis Cloud has only one DB with ID `0`).
+: This setting specifies the Redis DB to be used for all operations. When setting this make sure that the Redis server actually supports multiple DBs (for example, Redis Cloud has only one DB with ID `0`).
 
 MEMORY_CACHE_REDIS_HOST
 : JSON path `memoryCache.redisHost`, type `string`, default `127.0.0.1`
@@ -427,7 +438,7 @@ MEMORY_CACHE_REDIS_PORT
 MEMORY_CACHE_RETRY_MAX_ATTEMPTS
 : JSON path `memoryCache.retryMaxAttempts`, type `number`, default `undefined`
 : ENV variable `TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS`
-: This setting holds the maximum number of attempts to (re)connect to the Redis server. By default there is no limit.
+: This setting holds the maximum number of attempts to (re)connect to the Redis server. By default, there is no limit.
 
 MEMORY_CACHE_RETRY_MAX_INTERVAL
 : JSON path `memoryCache.retryMaxInterval`, type `number`, default `1000`
@@ -450,12 +461,12 @@ MESSAGE_EXCHANGE_MESSAGE_STORE (Advanced)
 MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED (Advanced)
 : JSON path `messageExchange.securityHashEnabled`, type `boolean`, default `true`
 : ENV variable `TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED`
-: This setting controls whether the message exchange will use a control hash mechanism to ensure there is no tampering with the messages in between service calls. In most cases you would want to keep this enabled since it ensures the integrity of your data. If you are concerned about performance (hashing with `blake2` is very fast, but it still eats some milliseconds) you might want to try and disable this to see if it makes any notable difference.
+: This setting controls whether the message exchange will use a control hash mechanism to ensure there is no tampering with the messages in between service calls. In most cases you would want to keep this enabled since it ensures the integrity of your data. If you are concerned about performance (hashing with `blake2` is rapid, but it still eats some milliseconds) you might want to try and disable this to see if it makes any notable difference.
 
 MESSAGE_EXCHANGE_SECURITY_HASH_KEY (Advanced)
 : JSON path `messageExchange.securityHashKey`, type `string`, default `random uuid`
 : ENV variable `TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY`
-: This setting holds the encryption key used by the message exchange control hash mechanism. By default, this has a random uuid value that can be used for development purposes only. For production environments you absolutely must provide your own encryption key via the ENV variable. Depending on your configuration and infrastructure it might come from a secure storage, HSM, key vault, etc.
+: This setting holds the encryption key used by the message exchange control hash mechanism. By default, this has a random uuid value that can be used for development only. For production environments you absolutely must provide your own encryption key via the ENV variable. Depending on your configuration and infrastructure, it might come from a secure storage, HSM, key vault, etc.
 
 MESSAGE_EXCHANGE_TRACE_EXPIRATION_TIME
 : JSON path `messageExchange.traceExpirationTime`, type `number`, default `3600`
@@ -464,7 +475,7 @@ MESSAGE_EXCHANGE_TRACE_EXPIRATION_TIME
 MESSAGE_EXCHANGE_TRACE_LOG_ENABLED
 : JSON path `messageExchange.traceLogEnabled`, type `boolean`, default `false`
 : ENV variable `TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED`
-: This setting controls whether the `auditing` module should output all trace messages as normal log entries or not. Normally, you don't want that since it will clutter the standard log quite a lot. All traces go their own storage and can be reviewed and processed separately from the log entries. In some cases, however, as in debugging, enabling this can help you identify hard to track problem.
+: This setting controls whether the `auditing` module should output all trace messages as normal log entries or not. Normally, you don't want that since it will clutter the standard log quite a lot. All traces go to their own storage and can be reviewed and processed separately from the log entries. In some cases, however, as in debugging, enabling this can help you identify a hard to track problem.
 
 MESSAGE_EXCHANGE_TRACE_REPOSITORY (Advanced)
 : JSON path `messageExchange.traceRepository`, type `string`, default `ti:messages:trace`
@@ -488,7 +499,7 @@ SERVICE_HEALTH_CHECK_TIMEOUT (Advanced)
 
 SERVICE_REGISTRY_ADDRESS (Advanced)
 : JSON path `serviceConfig.serviceRegistryAddress`, type `string`, default `ti:services:registry:catalog:`
-: This setting holds the prefix of the Redis key name used as business service registry. If the microservice is a `ServiceProvider`, on start up it will register its business service portfolio in that Redis set. Also, on each service call that same registry will be searched for the existence of the called business service. This is not something you should modify unless you are making a customized implementation of the tier 1 architectural layer.
+: This setting holds the prefix of the Redis key name used as a business service registry. If the microservice is a `ServiceProvider`, on start up it will register its business service portfolio in that Redis set. Also, on each service call that same registry will be searched for the existence of the called business service. This is not something you should modify unless you are making a customized implementation of the tier 1 architectural layer.
 
 OPERATION_MODE
 : JSON path `operationMode`, type `string`, default `production`