@ti-engine/core 1.6.0 → 1.7.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 This document contains 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.7.1
+
+* fix(exchange): preserve a configured-but-falsy `securityHashKey` — only a truly absent (`null`/`undefined`) value falls back to the empty key, so a configured `0`/`false` is no longer silently downgraded to the insecure empty-key path (PR #83, CodeRabbit)
+* build(release): bump package version from `1.7.0` to `1.7.1`
+
+## Version 1.7.0
+
+* refactor(core)!: load the `.env` file via native `process.loadEnvFile` instead of `@dotenvx/dotenvx`
+* build(deps)!: remove the `@dotenvx/dotenvx` dependency — core now has three runtime dependencies (`ioredis`, `lodash`, `node-schedule`)
+* build(core)!: raise the minimum Node.js version to `>=20.12.0` (required for `process.loadEnvFile`)
+
+> The native loader matches the prior behavior: a missing `.env` file is tolerated (ENOENT is ignored, as with the previous `quiet: true`) and existing environment variables are not overridden. The `--env` / `--env-file` / `--dotenv` / `--dotenv-path` / `-e` CLI aliases for choosing the env-file path are unchanged. Encrypted `.env` files (a dotenvx-only feature this framework never used) are not supported. Consumers on Node 20.0–20.11 must upgrade to Node ≥ 20.12.
+
+## Version 1.6.1
+
+* build(deps): update `@dotenvx/dotenvx` from ^1.73.1 to ^1.75.1
+* build(deps): remove `zeromq` as optional dependency
+
 ## Version 1.6.0
 
 * refactor(exchange)!: replace the blake2 keyed hash with native `node:crypto` HMAC-SHA256 in the message integrity check

package/README.md

@@ -35,7 +35,7 @@ Being a messaging system, the **ti-engine** relies on a message broker for the a
 
 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 **18.0.0**
+* A local [node.js installation](https://nodejs.org/en/download/) with a minimum version of **20.12.0** (the `core` package requires `process.loadEnvFile`)
 * 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 as it offers a free basic account.
@@ -140,17 +140,50 @@ 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 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).
+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 integrity hashing, 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 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:
+The sequence below shows a full service-call round trip through the default Redis exchange. Each message is split into a lightweight **envelope** (metadata, carrying the integrity hash) and a **payload** (the operational data): the payload is parked in a shared Redis hash while only the envelope travels through the queue.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Caller as ServiceConsumer<br/>(ServiceCaller)
+    participant SOut as MessageSender<br/>(requests-out)
+    participant Redis as Redis<br/>(list queues + payload hash)
+    participant RIn as MessageReceiver<br/>(requests-in)
+    participant Exec as ServiceProvider<br/>(ServiceExecutor)
+
+    rect rgb(232, 243, 255)
+    Note over Caller,Exec: Request path (blue)
+    Caller->>SOut: callService() builds the request envelope
+    SOut->>SOut: stamp HMAC-SHA256 hash over the message
+    SOut->>Redis: HSET payload into ti:messages:store (field = storeID)
+    SOut->>Redis: LPUSH envelope onto ti:messages:pending:{destination}
+    RIn->>Redis: BRPOP ti:messages:pending:{domain} (blocks until a message)
+    Redis-->>RIn: envelope (payload = storeID)
+    RIn->>Redis: HGET + HDEL storeID from ti:messages:store
+    Redis-->>RIn: payload, reassembled into the full message
+    RIn->>RIn: recompute HMAC, constant-time verify
+    RIn->>Exec: deliver the verified message
+    Exec->>Exec: resolve handler by alias + version, then run it
+    end
+
+    rect rgb(255, 235, 235)
+    Note over Caller,Exec: Response path (red, mirrored route)
+    Exec->>Redis: HSET result payload, LPUSH onto ti:messages:processed:{source}:{instanceID}
+    Caller->>Redis: BRPOP ti:messages:processed:{source}:{instanceID} (blocks)
+    Redis-->>Caller: response envelope, reassembled and verified
+    Caller->>Caller: resolve the awaiting Promise with the ServiceCallResult
+    end
+```
 
-![Message Exchange](https://raw.githubusercontent.com/Belleal/ti-engine/master/packages/core/docs/diagram1.png)
+If the recomputed hash does not match the one on the envelope, the receiver rejects the message with `E_SEC_MESSAGE_TAMPERING_DETECTED` instead of delivering it.
 
-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.
+The same queue can be consumed by _n_ identical receivers, which is how you scale a service domain horizontally. 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 is the blue (request) path in the diagram above.
 
-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 is the red (response) path in the diagram above.
 
 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.
 
@@ -162,6 +195,22 @@ The modules associated with this tier are all located in the `components/exchang
 * 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.
 
+The exchange classes form the hierarchy below. `MessageHandler` is the shared abstract base that owns the integrity hash; the concrete `Default*` classes are the Redis implementation you replace to swap brokers:
+
+```mermaid
+classDiagram
+    direction LR
+    MessageHandler <|-- MessageSender
+    MessageHandler <|-- MessageReceiver
+    MessageObserver <|-- MessageExchange
+    MessageSender <|-- DefaultMessageSender
+    MessageReceiver <|-- DefaultMessageReceiver
+    MessageExchange <|-- DefaultMessageExchange
+    class MessageHandler {
+        +createMessageHash()
+    }
+```
+
 ### Tier 2 - Service domains
 
 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:

package/bin/start-instance.js

@@ -29,7 +29,15 @@ const envFilePath = ( () => {
     return envPath;
 } )();
 
-require( "@dotenvx/dotenvx" ).config( { path: envFilePath, quiet: true } );
+// Load the resolved .env file using the native Node loader (Node >= 20.12). A missing file is not fatal —
+// environment variables may be supplied entirely by the OS/container. Existing process.env values are NOT overridden.
+try {
+    process.loadEnvFile( envFilePath );
+} catch ( error ) {
+    if ( error.code !== "ENOENT" ) {
+        throw error;
+    }
+}
 
 const tools = require( "#tools" );
 const logger = require( "#logger" );

package/components/exchange/message-handler.js

@@ -123,7 +123,8 @@ class MessageHandler extends ConnectionObserver {
      * @public
      */
     createMessageHash( message ) {
-        let key = config.getSetting( config.setting.MESSAGE_EXCHANGE_SECURITY_HASH_KEY );
+        const rawKey = config.getSetting( config.setting.MESSAGE_EXCHANGE_SECURITY_HASH_KEY );
+        let key = rawKey == null ? "" : String( rawKey );
         if ( keyWarningEmitted === false ) {
             keyWarningEmitted = true;
             if ( !key || key === OLD_DEFAULT_HASH_KEY ) {
@@ -131,7 +132,7 @@ class MessageHandler extends ConnectionObserver {
             }
         }
         let transformed = tools.decomposeJSON( tools.decycle( message ) );
-        let hmac = crypto.createHmac( "sha256", Buffer.from( key ) );
+        let hmac = crypto.createHmac( "sha256", Buffer.from( key, "utf8" ) );
         hmac.update( Buffer.from( transformed ) );
         return hmac.digest( "hex" );
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "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.",
   "keywords": [
     "microservices",
@@ -59,7 +59,6 @@
     "#tools": "./utils/tools.js"
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.73.1",
     "ioredis": "^5.11.1",
     "lodash": "^4.18.1",
     "node-schedule": "^2.1.1"
@@ -86,6 +85,6 @@
   },
   "homepage": "https://github.com/Belleal/ti-engine/tree/master/packages/core#readme",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.12.0"
   }
 }