@ti-engine/core 1.12.3 → 1.14.0

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.12.3",
+  "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",
@@ -68,6 +68,14 @@
       "types": "./types/utils/cache.d.ts",
       "default": "./utils/cache.js"
     },
+    "#cache-capability": {
+      "types": "./types/components/cache/cache-capability.d.ts",
+      "default": "./components/cache/cache-capability.js"
+    },
+    "#cache-provider": {
+      "types": "./types/components/cache/cache-provider.d.ts",
+      "default": "./components/cache/cache-provider.js"
+    },
     "#config": {
       "types": "./types/utils/config.d.ts",
       "default": "./utils/config.js"
@@ -137,6 +145,10 @@
       "types": "./types/components/exchange/message-tracer.d.ts",
       "default": "./components/exchange/message-tracer.js"
     },
+    "#redis-cache-provider": {
+      "types": "./types/components/cache/redis-cache-provider.d.ts",
+      "default": "./components/cache/redis-cache-provider.js"
+    },
     "#redis-integration": {
       "types": "./types/integrations/redis-integration.d.ts",
       "default": "./integrations/redis-integration.js"

package/types/components/cache/cache-capability.d.ts

@@ -0,0 +1,23 @@
+export { cacheCapabilityEnum as cacheCapability };
+export type TiCacheCapability = string;
+/**
+ * Enum for listing the optional behaviors a cache backend may or may not provide.
+ * <br/>
+ * NOTE: A backend declares what it supports through {@link CacheProvider#capabilities}; an application declares what it
+ * requires through the 'memoryCache.requiredCapabilities' setting. The two are reconciled once, during startup, so that
+ * a backend which cannot do what the application needs fails where somebody is watching rather than inside a request
+ * weeks later.
+ *
+ * @readonly
+ * @enum {string}
+ * @typedef {string} TiCacheCapability
+ */
+declare const cacheCapabilityEnum: import("../definitions.types").TiEnumOf<{
+    KEY_EXPIRY: string[];
+    KEY_PATTERN_MATCH: string[];
+    LISTS: string[];
+    SETS: string[];
+    HASH_FIELDS: string[];
+    JSON_DOCUMENTS: string[];
+    ATOMIC_JSON_EDIT: string[];
+}>;

package/types/components/cache/cache-provider.d.ts

@@ -0,0 +1,326 @@
+export = CacheProvider;
+import type ConnectionObserver from "#connection-observer";
+/** @import ConnectionObserver from "#connection-observer" */
+/**
+ * An abstract class that defines the storage behavior required by the {@link CommonMemoryCache}.
+ * <br/>
+ * NOTE: This sets the contract between the cache and whatever actually holds the values. It has to be inherited and
+ * implemented with the specifics of a given backend. For a working example please see the {@link RedisCacheProvider} class.
+ * <br/>
+ * NOTE: Implementations must NOT check whether the cache is operational. {@link CommonMemoryCache} performs that check
+ * once, before it delegates, so every backend inherits the same guard instead of restating it in each of its methods.
+ *
+ * @class CacheProvider
+ * @abstract
+ * @public
+ */
+declare class CacheProvider {
+    /**
+     * @constructor
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     */
+    constructor();
+    /**
+     * Property returning the optional behaviors this backend provides.
+     * <br/>
+     * NOTE: Some capabilities can only be established once a connection exists — RedisJSON, for example, is a server-side
+     * module that has to be probed. Read this after {@link CacheProvider#initialize} has resolved, never before.
+     *
+     * @property
+     * @returns {string[]} Values drawn from {@link TiCacheCapability}.
+     * @abstract
+     * @public
+     */
+    get capabilities(): string[];
+    /**
+     * Used to verify whether this backend provides a given capability.
+     *
+     * @method
+     * @param {string} capability A value from {@link TiCacheCapability}.
+     * @returns {boolean}
+     * @public
+     */
+    hasCapability(capability: string): boolean;
+    /**
+     * Used to initialize the backend and establish whatever connection it requires.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    initialize(): Promise<any>;
+    /**
+     * Used to gracefully shut the backend down.
+     *
+     * @method
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    shutDown(): Promise<any>;
+    /**
+     * Used to register a new {@link ConnectionObserver} for events related to the backend connection state.
+     *
+     * @method
+     * @param {ConnectionObserver} connectionObserver The {@link ConnectionObserver} that will be notified of any changes.
+     * @abstract
+     * @public
+     */
+    addConnectionObserver(connectionObserver: ConnectionObserver): void;
+    /**
+     * Used to search for keys by a given pattern.
+     *
+     * @method
+     * @param {string} pattern
+     * @returns {Promise<Array>}
+     * @requires {TiCacheCapability.KEY_PATTERN_MATCH}
+     * @abstract
+     * @public
+     */
+    matchKeys(pattern: string): Promise<any[]>;
+    /**
+     * Used to set a specific string value.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} value
+     * @param {number} [expiration] Expiration value is in seconds.
+     * @returns {Promise<string>}
+     * @abstract
+     * @public
+     */
+    setValue(key: string, value: string, expiration?: number): Promise<string>;
+    /**
+     * Used to set multiple string values.
+     *
+     * @method
+     * @param {Object} keyValues
+     * @param {string} [prefix]
+     * @param {number} [expiration] Expiration value is in seconds.
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    setValues(keyValues: Object, prefix?: string, expiration?: number): Promise<any>;
+    /**
+     * Used to get a string value.
+     *
+     * @method
+     * @param {string} key
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    getValue(key: string): Promise<any>;
+    /**
+     * Used to get multiple string values.
+     *
+     * @method
+     * @param {string[]} keys
+     * @param {string} [prefix]
+     * @returns {Promise}
+     * @abstract
+     * @public
+     */
+    getValues(keys: string[], prefix?: string): Promise<any>;
+    /**
+     * Used to delete a value / item.
+     *
+     * @method
+     * @param {string} key
+     * @returns {Promise<boolean>}
+     * @abstract
+     * @public
+     */
+    deleteValue(key: string): Promise<boolean>;
+    /**
+     * Used to set expiration in seconds to an existing key.
+     *
+     * @method
+     * @param {string} key
+     * @param {number} seconds
+     * @param {string} [name] If a field in a hash set is to be expired instead, the name of that set.
+     * @returns {Promise<number>}
+     * @requires {TiCacheCapability.KEY_EXPIRY}
+     * @abstract
+     * @public
+     */
+    expireValue(key: string, seconds: number, name?: string): Promise<number>;
+    /**
+     * Used to add the specified values to a list.
+     *
+     * @method
+     * @param {string} listName
+     * @param {Object[]} values
+     * @returns {Promise<number>}
+     * @requires {TiCacheCapability.LISTS}
+     * @abstract
+     * @public
+     */
+    listPushValue(listName: string, values: Object[]): Promise<number>;
+    /**
+     * Used to add the specified value to a set.
+     *
+     * @method
+     * @param {string} key
+     * @param {string|Object} value
+     * @returns {Promise}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    addToSet(key: string, value: string | Object): Promise<any>;
+    /**
+     * Used to add multiple values to multiple sets in one transactional request.
+     *
+     * @method
+     * @param {string[]} keys
+     * @param {string[]} values
+     * @returns {Promise}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    addToSetMulti(keys: string[], values: string[]): Promise<any>;
+    /**
+     * Used to verify whether a value is a member of a set.
+     *
+     * @method
+     * @param {string} setName
+     * @param {string|Object} value
+     * @returns {Promise<boolean>}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    isSetMember(setName: string, value: string | Object): Promise<boolean>;
+    /**
+     * Used to fetch all members of a set.
+     *
+     * @method
+     * @param {string} key
+     * @returns {Promise<Array>}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    membersOfSet(key: string): Promise<any[]>;
+    /**
+     * Used to fetch the union of the provided sets.
+     *
+     * @method
+     * @param {string[]} keys
+     * @returns {Promise<Array>}
+     * @requires {TiCacheCapability.SETS}
+     * @abstract
+     * @public
+     */
+    unionOfSets(keys: string[]): Promise<any[]>;
+    /**
+     * Used to set a single field in a hash set.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} name
+     * @param {string|Object} value
+     * @returns {Promise}
+     * @requires {TiCacheCapability.HASH_FIELDS}
+     * @abstract
+     * @public
+     */
+    hashSetField(key: string, name: string, value: string | Object): Promise<any>;
+    /**
+     * Used to set multiple fields in a hash set.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} fields
+     * @returns {Promise}
+     * @requires {TiCacheCapability.HASH_FIELDS}
+     * @abstract
+     * @public
+     */
+    hashSetFields(key: string, fields: Object): Promise<any>;
+    /**
+     * Used to fetch a single field from a hash set.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} field
+     * @returns {Promise}
+     * @requires {TiCacheCapability.HASH_FIELDS}
+     * @abstract
+     * @public
+     */
+    hashGetField(key: string, field: string): Promise<any>;
+    /**
+     * Used to delete a single field from a hash set.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} field
+     * @returns {Promise}
+     * @requires {TiCacheCapability.HASH_FIELDS}
+     * @abstract
+     * @public
+     */
+    hashDeleteField(key: string, field: string): Promise<any>;
+    /**
+     * Used to store a JSON document, or a branch of one.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} value
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments.
+     * @param {number} [overrideMode=0] 0 allows full override; 1 sets only if absent; 2 sets only if present.
+     * @returns {Promise}
+     * @requires {TiCacheCapability.JSON_DOCUMENTS}
+     * @abstract
+     * @public
+     */
+    setJSON(key: string, value: Object, path?: string | string[], overrideMode?: number): Promise<any>;
+    /**
+     * Used to fetch a JSON document, or a branch of one.
+     *
+     * @method
+     * @param {string} key
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments.
+     * @returns {Promise<Object>}
+     * @requires {TiCacheCapability.JSON_DOCUMENTS}
+     * @abstract
+     * @public
+     */
+    getJSON(key: string, path?: string | string[]): Promise<Object>;
+    /**
+     * Used to merge a value into an existing JSON document at the given path.
+     * <br/>
+     * NOTE: Callers rely on this being applied atomically by the backend when {@link TiCacheCapability.ATOMIC_JSON_EDIT}
+     * is declared — two concurrent edits to different paths of the same document must both survive. A backend that can
+     * only read-modify-write must NOT declare that capability, because the loss is silent: nothing throws, and one of
+     * the two writes is simply gone.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} value
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments.
+     * @returns {Promise}
+     * @requires {TiCacheCapability.JSON_DOCUMENTS}
+     * @abstract
+     * @public
+     */
+    editJSON(key: string, value: Object, path?: string | string[]): Promise<any>;
+    /**
+     * Used to append a value to an array inside a JSON document.
+     *
+     * @method
+     * @param {string} key
+     * @param {Object} value
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments.
+     * @returns {Promise}
+     * @requires {TiCacheCapability.JSON_DOCUMENTS}
+     * @abstract
+     * @public
+     */
+    arrayAppendJSON(key: string, value: Object, path?: string | string[]): Promise<any>;
+}