@ti-engine/core 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.14.0
+
+* feat(cache): select the backend through the new `memoryCache.provider` setting (`TI_MEMORY_CACHE_PROVIDER`). `"redis"` selects the built-in provider and remains the default; any other value is a module path resolved against the working directory and must export a `CacheProvider` subclass. Without this the provider contract added in 1.13.0 could not actually be pointed at anything else.
+* feat(service-instance): make the message exchange optional through `messageExchange.enabled` (`TI_MESSAGE_EXCHANGE_ENABLED`), defaulting to `true`. When off, neither the exchange nor the dispatcher is initialized or shut down — and the exchange is the only remaining user of the cache primitives a non-Redis backend cannot reasonably provide (`blockingCommand`, pub/sub).
+* feat(service-instance): make health reporting optional through `serviceConfig.healthCheckEnabled`, defaulting to `true`. The default interval is a six-field cron, so this writes once per second for the life of the instance; that is what an orchestrator watching a mesh wants and pure cost for a single instance with nothing reading the key.
+* fix(cache): validate the configured provider class before constructing it. `typeof === "function"` accepts an arrow function, which is not a constructor — `new` on one threw a raw `TypeError` instead of the documented `E_GEN_INVALID_ARGUMENT_TYPE` — and asking `instanceof` after construction meant an unrelated class had its constructor run, executing arbitrary code from a misconfigured path, before anything rejected it. Both now fail the same declared way, without constructing anything.
+* test(cache): cover backend selection and, with a stub backend that reproduces the Redis client's notify-then-resolve ordering, the rollback on a refused start — the 1.13.0 fix that shipped untested because it needed a live server. Verified to fail without the rollback. Core 53 to 60 tests.
+
 ## Version 1.13.0
 
 * feat(cache): introduce `CacheProvider`, an abstract backend contract, and move every Redis-specific detail behind it into `RedisCacheProvider`. `CommonMemoryCache` keeps its public API and now owns only the operational state, the connection observation and one guard shared by all twenty-one data methods.

package/bin/settings.json

@@ -17,6 +17,7 @@
   },
   "memoryCache": {
     "authKey": null,
+    "provider": "redis",
     "redisDB": 0,
     "redisHost": "127.0.0.1",
     "redisPort": 6379,
@@ -24,6 +25,7 @@
     "user": "default"
   },
   "messageExchange": {
+    "enabled": true,
     "messageQueuePrefix": "ti:messages:",
     "messageStore": "ti:messages:store",
     "securityHashEnabled": true,
@@ -35,6 +37,7 @@
   "serviceConfig": {
     "executionTimeout": 180000,
     "healthCheckAddress": "ti:services:registry:health:",
+    "healthCheckEnabled": true,
     "healthCheckInterval": "*/1 * * * * *",
     "healthCheckTimeout": 3,
     "serviceRegistryAddress": "ti:services:registry:catalog:"

package/components/service-instance.js

@@ -86,6 +86,23 @@ class ServiceInstance {
         return ServiceInstance.#instanceID;
     }
 
+    /**
+     * Property returning whether the message exchange is enabled for this instance.
+     * <br/>
+     * NOTE: When this is off the instance neither initializes nor shuts down the message dispatcher, and therefore
+     * touches none of the primitives the exchange needs from the cache backend - blocking reads and pub/sub, which are
+     * the only parts of the cache surface a non-Redis backend cannot reasonably provide. A single-instance deployment
+     * with no mesh to talk to is the case this exists for. Defaults to enabled, so an existing deployment is
+     * unaffected.
+     *
+     * @property
+     * @returns {boolean}
+     * @public
+     */
+    static get isMessageExchangeEnabled() {
+        return config.getSetting( config.setting.MESSAGE_EXCHANGE_ENABLED, true ) !== false;
+    }
+
     /**
      * Property returning the current service domain name.
      *
@@ -160,6 +177,11 @@ class ServiceInstance {
     onStart() {
         return new Promise( ( resolve, reject ) => {
             cache.instance.initialize().then( () => {
+                if ( ServiceInstance.isMessageExchangeEnabled === false ) {
+                    logger.log( `Message exchange is disabled for instance '${ ServiceInstance.instanceID }' - it will neither send nor receive service messages.`, logger.logSeverity.NOTICE );
+                    return undefined;
+                }
+
                 const DefaultMessageExchange = require( "#default-message-exchange" );
                 const ServiceProvider = require( "#service-provider" );
                 const ServiceConsumer = require( "#service-consumer" );
@@ -214,6 +236,13 @@ class ServiceInstance {
      */
     onStop() {
         return new Promise( ( resolve, reject ) => {
+            // Symmetrical with onStart: a dispatcher that was never initialized has nothing to shut down, and asking
+            // it to would fail a stop that has nothing wrong with it.
+            if ( ServiceInstance.isMessageExchangeEnabled === false ) {
+                resolve();
+                return;
+            }
+
             messageDispatcher.instance.shutDown().then( () => {
                 resolve();
             } ).catch( ( error ) => {
@@ -274,9 +303,17 @@ class ServiceInstance {
     #postStart() {
         return new Promise( ( resolve ) => {
             // Schedule regular health check:
-            this.#reportHealthyJob = schedule.scheduleJob( config.getSetting( config.setting.SERVICE_HEALTH_CHECK_INTERVAL ), () => {
-                this.reportHealthy();
-            } );
+            // The default interval is a six-field cron, so this writes once per second for as long as the instance
+            // lives. That is what an orchestrator watching a mesh of instances wants, and pure cost anywhere else -
+            // a single instance with nothing reading the key, or a host that already knows whether the process is
+            // running, pays a write per second for nothing.
+            if ( config.getSetting( config.setting.SERVICE_HEALTH_CHECK_ENABLED, true ) === false ) {
+                logger.log( `Health check reporting is disabled for instance '${ ServiceInstance.instanceID }'.`, logger.logSeverity.NOTICE );
+            } else {
+                this.#reportHealthyJob = schedule.scheduleJob( config.getSetting( config.setting.SERVICE_HEALTH_CHECK_INTERVAL ), () => {
+                    this.reportHealthy();
+                } );
+            }
 
             logger.log( `Instance '${ ServiceInstance.instanceID }' started successfully.`, logger.logSeverity.NOTICE, {
                 nodeVersion: process.version,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Microservice framework for Node.js: a Redis-backed message exchange with end-to-end call tracing, retries and tamper-evident message envelopes.",
   "keywords": [
     "microservices",

package/types/components/service-instance.d.ts

@@ -28,6 +28,20 @@ declare class ServiceInstance {
      * @public
      */
     static get instanceID(): string;
+    /**
+     * Property returning whether the message exchange is enabled for this instance.
+     * <br/>
+     * NOTE: When this is off the instance neither initializes nor shuts down the message dispatcher, and therefore
+     * touches none of the primitives the exchange needs from the cache backend - blocking reads and pub/sub, which are
+     * the only parts of the cache surface a non-Redis backend cannot reasonably provide. A single-instance deployment
+     * with no mesh to talk to is the case this exists for. Defaults to enabled, so an existing deployment is
+     * unaffected.
+     *
+     * @property
+     * @returns {boolean}
+     * @public
+     */
+    static get isMessageExchangeEnabled(): boolean;
     /**
      * Property returning the current service domain name.
      *

package/types/utils/cache.d.ts

@@ -4,15 +4,51 @@ export declare var decodeCommandValue: typeof import("#redis-cache-provider").de
 export declare var mapCommandValues: typeof import("#redis-cache-provider").mapCommandValues;
 export { cacheCapability };
 export { findMissingCapabilities };
+export { createConfiguredProvider };
+export { isCacheProviderClass };
+import CacheProvider = require("#cache-provider");
 import ConnectionObserver = require("#connection-observer");
 import RedisCacheProvider = require("#redis-cache-provider");
 import { cacheCapability } from "#cache-capability";
+/**
+ * Determines whether a value is a class extending {@link CacheProvider}, without constructing it.
+ * <br/>
+ * NOTE: A `typeof === "function"` test is not enough, and constructing first to ask `instanceof` afterwards is worse.
+ * An arrow function passes the `typeof` test but is not a constructor, so `new` on it throws a raw TypeError instead
+ * of the documented exception; and an unrelated class would have its constructor RUN - arbitrary code from a
+ * misconfigured path - before anything rejected it. Walking the prototype chain answers the question without
+ * executing anything.
+ *
+ * @method
+ * @param {*} candidate The value exported by the configured provider module.
+ * @returns {boolean}
+ * @public
+ */
+declare function isCacheProviderClass(candidate: any): boolean;
+/**
+ * Creates the cache backend named by the 'memoryCache.provider' setting.
+ * <br/>
+ * NOTE: The built-in name "redis" selects {@link RedisCacheProvider}. Any other value is treated as a module path
+ * resolved against the process working directory, much as 'TI_INSTANCE_CLASS' already is, and must export a class
+ * extending {@link CacheProvider}. Resolution uses `path.resolve` rather than `path.join` so that an absolute path is
+ * taken as given instead of being appended to the working directory.
+ * <br/>
+ * NOTE: This runs while the singleton is being constructed, which is to say at require time. A bad provider name
+ * therefore fails the process immediately rather than at the first cache call - which is the point: a deployment
+ * pointed at a backend that does not exist should not reach the code that assumes one.
+ *
+ * @method
+ * @param {string} connectionIdentifier The identifier under which the backend's connection is observed.
+ * @returns {CacheProvider}
+ * @throws {TiException.E_GEN_INVALID_ARGUMENT_TYPE} If the configured module does not export a {@link CacheProvider}.
+ * @public
+ */
+declare function createConfiguredProvider(connectionIdentifier: string): CacheProvider;
 /**
  * Determines which of the required capabilities a backend does not provide.
  * <br/>
- * NOTE: This lives outside the class, and is exported, for the same reason the Redis decoders are: the cache singleton
- * builds its own backend in its constructor, so the reconciliation cannot be driven without a live server. This is the
- * pure half of it, and it is the half that decides whether an instance starts.
+ * NOTE: This lives outside the class, and is exported, for the same reason the Redis decoders are: it is the pure half
+ * of the reconciliation, and the half that decides whether an instance starts.
  *
  * @method
  * @param {string[]} [required] Capabilities the application declared it needs.

package/types/utils/config.d.ts

@@ -18,6 +18,7 @@ declare const settingsEnum: import("../components/definitions.types").TiEnumOf<{
     LOCALIZATION_LABELS_PATH: string[];
     LOCALIZATION_LANGUAGE: string[];
     MEMORY_CACHE_AUTH_KEY: string[];
+    MEMORY_CACHE_PROVIDER: string[];
     MEMORY_CACHE_REDIS_DB: string[];
     MEMORY_CACHE_REDIS_HOST: string[];
     MEMORY_CACHE_REDIS_PORT: string[];
@@ -25,6 +26,7 @@ declare const settingsEnum: import("../components/definitions.types").TiEnumOf<{
     MEMORY_CACHE_RETRY_MAX_ATTEMPTS: string[];
     MEMORY_CACHE_RETRY_MAX_INTERVAL: string[];
     MEMORY_CACHE_USER: string[];
+    MESSAGE_EXCHANGE_ENABLED: string[];
     MESSAGE_EXCHANGE_QUEUE_PREFIX: string[];
     MESSAGE_EXCHANGE_MESSAGE_STORE: string[];
     MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED: string[];
@@ -34,6 +36,7 @@ declare const settingsEnum: import("../components/definitions.types").TiEnumOf<{
     MESSAGE_EXCHANGE_TRACE_REPOSITORY: string[];
     SERVICE_EXECUTION_TIMEOUT: string[];
     SERVICE_HEALTH_CHECK_ADDRESS: string[];
+    SERVICE_HEALTH_CHECK_ENABLED: string[];
     SERVICE_HEALTH_CHECK_INTERVAL: string[];
     SERVICE_HEALTH_CHECK_TIMEOUT: string[];
     SERVICE_REGISTRY_ADDRESS: string[];

package/utils/cache.js

@@ -15,19 +15,81 @@
  * limitations under the License.
 */
 
+const CacheProvider = require( "#cache-provider" );
 const ConnectionObserver = require( "#connection-observer" );
 const RedisCacheProvider = require( "#redis-cache-provider" );
 const _ = require( "lodash" );
 const config = require( "#config" );
 const exceptions = require( "#exceptions" );
+const path = require( "path" );
 const { cacheCapability } = require( "#cache-capability" );
 
+/**
+ * Determines whether a value is a class extending {@link CacheProvider}, without constructing it.
+ * <br/>
+ * NOTE: A `typeof === "function"` test is not enough, and constructing first to ask `instanceof` afterwards is worse.
+ * An arrow function passes the `typeof` test but is not a constructor, so `new` on it throws a raw TypeError instead
+ * of the documented exception; and an unrelated class would have its constructor RUN - arbitrary code from a
+ * misconfigured path - before anything rejected it. Walking the prototype chain answers the question without
+ * executing anything.
+ *
+ * @method
+ * @param {*} candidate The value exported by the configured provider module.
+ * @returns {boolean}
+ * @public
+ */
+function isCacheProviderClass( candidate ) {
+    return typeof candidate === "function" && candidate.prototype instanceof CacheProvider;
+}
+
+/**
+ * Creates the cache backend named by the 'memoryCache.provider' setting.
+ * <br/>
+ * NOTE: The built-in name "redis" selects {@link RedisCacheProvider}. Any other value is treated as a module path
+ * resolved against the process working directory, much as 'TI_INSTANCE_CLASS' already is, and must export a class
+ * extending {@link CacheProvider}. Resolution uses `path.resolve` rather than `path.join` so that an absolute path is
+ * taken as given instead of being appended to the working directory.
+ * <br/>
+ * NOTE: This runs while the singleton is being constructed, which is to say at require time. A bad provider name
+ * therefore fails the process immediately rather than at the first cache call - which is the point: a deployment
+ * pointed at a backend that does not exist should not reach the code that assumes one.
+ *
+ * @method
+ * @param {string} connectionIdentifier The identifier under which the backend's connection is observed.
+ * @returns {CacheProvider}
+ * @throws {TiException.E_GEN_INVALID_ARGUMENT_TYPE} If the configured module does not export a {@link CacheProvider}.
+ * @public
+ */
+function createConfiguredProvider( connectionIdentifier ) {
+    let selected = config.getSetting( config.setting.MEMORY_CACHE_PROVIDER, "redis" );
+
+    if ( selected === "redis" ) {
+        return new RedisCacheProvider( connectionIdentifier );
+    }
+
+    let ProviderClass;
+    try {
+        ProviderClass = require( path.resolve( process.cwd(), selected ) );
+    } catch ( error ) {
+        throw exceptions.raise( exceptions.exceptionCode.E_GEN_INVALID_ARGUMENT_TYPE, {
+            details: `Could not load the cache provider configured as '${ selected }': ${ error.message }`
+        } );
+    }
+
+    if ( isCacheProviderClass( ProviderClass ) === false ) {
+        throw exceptions.raise( exceptions.exceptionCode.E_GEN_INVALID_ARGUMENT_TYPE, {
+            details: `The cache provider configured as '${ selected }' does not export a class extending CacheProvider.`
+        } );
+    }
+
+    return new ProviderClass( connectionIdentifier );
+}
+
 /**
  * Determines which of the required capabilities a backend does not provide.
  * <br/>
- * NOTE: This lives outside the class, and is exported, for the same reason the Redis decoders are: the cache singleton
- * builds its own backend in its constructor, so the reconciliation cannot be driven without a live server. This is the
- * pure half of it, and it is the half that decides whether an instance starts.
+ * NOTE: This lives outside the class, and is exported, for the same reason the Redis decoders are: it is the pure half
+ * of the reconciliation, and the half that decides whether an instance starts.
  *
  * @method
  * @param {string[]} [required] Capabilities the application declared it needs.
@@ -68,7 +130,7 @@ class CommonMemoryCache extends ConnectionObserver {
         super();
 
         if ( !CommonMemoryCache.#instance ) {
-            this.#provider = new RedisCacheProvider( this.#connectionIdentifier );
+            this.#provider = createConfiguredProvider( this.#connectionIdentifier );
             this.#provider.addConnectionObserver( this );
 
             CommonMemoryCache.#instance = this;
@@ -564,5 +626,7 @@ module.exports.mapCommandValues = RedisCacheProvider.mapCommandValues;
 // Re-exported so a consumer can name a capability without reaching past this module's exports map.
 module.exports.cacheCapability = cacheCapability;
 
-// Exported for testing, per the note on the function itself.
+// Exported for testing, per the notes on the functions themselves.
 module.exports.findMissingCapabilities = findMissingCapabilities;
+module.exports.createConfiguredProvider = createConfiguredProvider;
+module.exports.isCacheProviderClass = isCacheProviderClass;

package/utils/config.js

@@ -35,6 +35,7 @@ const settingsEnum = tools.enum( {
     LOCALIZATION_LABELS_PATH: [ "localization.labelsPath", "labelsPath", "" ],
     LOCALIZATION_LANGUAGE: [ "localization.language", "language", "" ],
     MEMORY_CACHE_AUTH_KEY: [ "memoryCache.authKey", "authKey", "" ],
+    MEMORY_CACHE_PROVIDER: [ "memoryCache.provider", "provider", "" ],
     MEMORY_CACHE_REDIS_DB: [ "memoryCache.redisDB", "redisDB", "" ],
     MEMORY_CACHE_REDIS_HOST: [ "memoryCache.redisHost", "redisHost", "" ],
     MEMORY_CACHE_REDIS_PORT: [ "memoryCache.redisPort", "redisPort", "" ],
@@ -42,6 +43,7 @@ const settingsEnum = tools.enum( {
     MEMORY_CACHE_RETRY_MAX_ATTEMPTS: [ "memoryCache.retryMaxAttempts", "retryMaxAttempts", "" ],
     MEMORY_CACHE_RETRY_MAX_INTERVAL: [ "memoryCache.retryMaxInterval", "retryMaxInterval", "" ],
     MEMORY_CACHE_USER: [ "memoryCache.user", "user", "" ],
+    MESSAGE_EXCHANGE_ENABLED: [ "messageExchange.enabled", "enabled", "" ],
     MESSAGE_EXCHANGE_QUEUE_PREFIX: [ "messageExchange.messageQueuePrefix", "messageQueuePrefix", "" ],
     MESSAGE_EXCHANGE_MESSAGE_STORE: [ "messageExchange.messageStore", "messageStore", "" ],
     MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED: [ "messageExchange.securityHashEnabled", "securityHashEnabled", "" ],
@@ -51,6 +53,7 @@ const settingsEnum = tools.enum( {
     MESSAGE_EXCHANGE_TRACE_REPOSITORY: [ "messageExchange.traceRepository", "traceRepository", "" ],
     SERVICE_EXECUTION_TIMEOUT: [ "serviceConfig.executionTimeout", "executionTimeout", "" ],
     SERVICE_HEALTH_CHECK_ADDRESS: [ "serviceConfig.healthCheckAddress", "healthCheckAddress", "" ],
+    SERVICE_HEALTH_CHECK_ENABLED: [ "serviceConfig.healthCheckEnabled", "healthCheckEnabled", "" ],
     SERVICE_HEALTH_CHECK_INTERVAL: [ "serviceConfig.healthCheckInterval", "healthCheckInterval", "" ],
     SERVICE_HEALTH_CHECK_TIMEOUT: [ "serviceConfig.healthCheckTimeout", "healthCheckTimeout", "" ],
     SERVICE_REGISTRY_ADDRESS: [ "serviceConfig.serviceRegistryAddress", "serviceRegistryAddress", "" ],
@@ -76,6 +79,7 @@ if ( settings.localization ) {
 }
 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.provider = ( process.env.TI_MEMORY_CACHE_PROVIDER !== undefined ) ? process.env.TI_MEMORY_CACHE_PROVIDER : settings.memoryCache.provider;
     settings.memoryCache.redisDB = ( process.env.TI_MEMORY_CACHE_REDIS_DB !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_DB ) : settings.memoryCache.redisDB;
     settings.memoryCache.redisHost = ( process.env.TI_MEMORY_CACHE_REDIS_HOST !== undefined ) ? process.env.TI_MEMORY_CACHE_REDIS_HOST : settings.memoryCache.redisHost;
     settings.memoryCache.redisPort = ( process.env.TI_MEMORY_CACHE_REDIS_PORT !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_PORT ) : settings.memoryCache.redisPort;
@@ -90,6 +94,7 @@ if ( settings.memoryCache ) {
     settings.memoryCache.user = ( process.env.TI_MEMORY_CACHE_USER !== undefined ) ? process.env.TI_MEMORY_CACHE_USER : settings.memoryCache.user;
 }
 if ( settings.messageExchange ) {
+    settings.messageExchange.enabled = ( process.env.TI_MESSAGE_EXCHANGE_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_ENABLED ) : settings.messageExchange.enabled;
     settings.messageExchange.securityHashEnabled = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED ) : settings.messageExchange.securityHashEnabled;
     settings.messageExchange.securityHashKey = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY !== undefined ) ? process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY : settings.messageExchange.securityHashKey;
     settings.messageExchange.traceLogEnabled = ( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED ) : settings.messageExchange.traceLogEnabled;