@ti-engine/core 1.2.3 → 1.3.1

package/integrations/redis-integration.js

@@ -28,6 +28,7 @@ let cacheCommandsEnum = tools.enum( {
     HASH_GET: [ "hget", "hash get", "https://redis.io/docs/latest/commands/hget/" ],
     HASH_GET_ALL: [ "hgetall", "hash get all", "https://redis.io/docs/latest/commands/hgetall/" ],
     HASH_REMOVE: [ "hdel", "hash remove", "https://redis.io/docs/latest/commands/hdel/" ],
+    HASH_EXPIRE: [ "hexpire", "hash expire", "https://redis.io/docs/latest/commands/hexpire/" ],
     HASH_SET: [ "hset", "", "https://redis.io/docs/latest/commands/hset/" ],
     HASH_SET_MANY: [ "hmset", "(deprecated) use HSET with multiple fields", "https://redis.io/docs/latest/commands/hmset/" ],
     IS_SET_MEMBER: [ "sismember", "", "https://redis.io/docs/latest/commands/sismember/" ],
@@ -43,6 +44,21 @@ let cacheCommandsEnum = tools.enum( {
     UNION_OF_SETS: [ "sunion", "union of sets", "https://redis.io/docs/latest/commands/sunion/" ]
 } );
 
+/**
+ * Enum for listing all client statuses.
+ *
+ * @readonly
+ * @enum {number}
+ */
+let clientStatusEnum = tools.enum( {
+    UNINITIALIZED: [ 0, "uninitialized", "Redis client is offline and not yet initialized." ],
+    CONNECTED: [ 1, "connected", "Redis client is connected and online." ],
+    CONNECTING: [ 2, "connecting", "Redis client is connecting to server." ],
+    DISRUPTED: [ 3, "disrupted", "Redis client is temporarily disconnected from server due to a disruption." ],
+    SHUTTING_DOWN: [ 4, "shutting down", "Redis client is shutting down." ],
+    DISCONNECTED: [ 5, "disconnected", "Redis client is permanently disconnected from server." ]
+} );
+
 /**
  * Enum for listing the Redis key override modes.
  *
@@ -63,6 +79,10 @@ module.exports.cacheCommands = cacheCommandsEnum;
  * @typedef {string} TiRedisOverrideMode
  */
 module.exports.cacheOverrideMode = cacheOverrideModeEnum;
+/**
+ * @typedef {number} TiRedisClientStatus
+ */
+module.exports.clientStatus = clientStatusEnum;
 
 /**
  * Used to create a Redis Cache client.
@@ -76,6 +96,7 @@ module.exports.cacheOverrideMode = cacheOverrideModeEnum;
 class RedisClient {
 
     #clientIdentifier;
+    #clientStatus = clientStatusEnum.UNINITIALIZED;
     #retryMaxInterval = 1000;
     #retryMaxAttempts = undefined;
     #redisConnection = undefined;
@@ -118,6 +139,17 @@ class RedisClient {
         return this.#redisClientID;
     }
 
+    /**
+     * Used to return the Redis client status.
+     *
+     * @property
+     * @returns {number}
+     * @public
+     */
+    get clientStatus() {
+        return this.#clientStatus;
+    }
+
     /**
      * Used to return the Redis server version.
      *
@@ -167,12 +199,6 @@ class RedisClient {
                 } ).then( ( clientID ) => {
                     // Store the client ID:
                     this.#redisClientID = clientID;
-
-                    // Notify all connection observers about the initialization success:
-                    _.forEach( this.#connectionObservers, ( connectionObservers ) => {
-                        connectionObservers.onConnectionRecovered( this.#clientIdentifier );
-                    } );
-
                     resolve();
                 } ).catch( ( error ) => {
                     reject( exceptions.raise( error ) );
@@ -359,6 +385,7 @@ class RedisClient {
     shutDown( timeoutMs = 1000 ) {
         return new Promise( ( resolve ) => {
             let finished = false;
+            this.#clientStatus = clientStatusEnum.SHUTTING_DOWN;
             const done = () => {
                 if ( !finished ) {
                     finished = true;
@@ -403,7 +430,8 @@ class RedisClient {
      * @param {number} defaultDB
      * @param {number} [retryMaxIntervalMs=1000] Optional max backoff interval.
      * @param {number|undefined} [retryMaxAttempts=undefined] Optional max (re)connection attempts before abort.
-     * @public
+     * @returns {Promise}
+     * @private
      */
     #setupClient( host, port, authKey, user, defaultDB, retryMaxIntervalMs, retryMaxAttempts ) {
         return new Promise( ( resolve, reject ) => {
@@ -412,19 +440,22 @@ class RedisClient {
                 this.#retryMaxAttempts = retryMaxAttempts;
 
                 let retryStrategy = ( attempt ) => {
-                    let result = Math.min( attempt * 50, this.#retryMaxInterval );
-
+                    let retryInterval = Math.min( attempt * 50, this.#retryMaxInterval );
                     if ( this.#retryMaxAttempts != null && attempt > this.#retryMaxAttempts ) {
                         logger.log( "In Redis retry strategy: reached max attempts for command retry. Aborting...", logger.logSeverity.WARNING, { attempts: attempt } );
-                        result = exceptions.raise( exceptions.exceptionCode.E_COM_RETRY_ATTEMPTS_EXCEEDED );
+                        retryInterval = exceptions.raise( exceptions.exceptionCode.E_COM_RETRY_ATTEMPTS_EXCEEDED );
                     }
-
-                    return result;
+                    return retryInterval;
                 };
 
                 let reconnectOnError = ( error ) => {
                     logger.log( `In Redis reconnect on error strategy: ${ error.message }`, logger.logSeverity.ERROR, error );
-                    return !!error.message.includes( "READONLY" );
+                    if ( error.message.includes( "READONLY" ) ) {
+                        // Returning 2 will also resubmit the failed command:
+                        return 2;
+                    } else {
+                        return 0;
+                    }
                 };
 
                 let options = {
@@ -441,22 +472,33 @@ class RedisClient {
 
                 /** @type Redis */
                 this.#redisConnection = new Redis( options );
+                this.#clientStatus = clientStatusEnum.CONNECTING;
+
+                this.#redisConnection.once( "ready", () => {
+                    this.#clientStatus = clientStatusEnum.CONNECTED;
+                    this.#notifyConnectionObservers();
+
+                    this.#redisConnection.on( "ready", () => {
+                        this.#clientStatus = clientStatusEnum.CONNECTED;
+                        this.#notifyConnectionObservers();
+                    } );
 
-                this.#redisConnection.on( "ready", () => {
-                    logger.log( `Connection to Redis server ${ host }:${ port } (re)established by client '${ this.identifier }' and is ready to be used.`, logger.logSeverity.INFO );
                     resolve();
                 } );
                 this.#redisConnection.on( "error", ( error ) => {
+                    this.#clientStatus = clientStatusEnum.DISRUPTED;
                     logger.log( `Error received in Redis client '${ this.identifier }'.`, logger.logSeverity.ERROR, error );
-
-                    // Notify all connection observers about this event:
-                    _.forEach( this.#connectionObservers, ( connectionObservers ) => {
-                        connectionObservers.onConnectionDisrupted( this.#clientIdentifier );
-                    } );
+                    this.#notifyConnectionObservers();
+                } );
+                this.#redisConnection.on( "reconnecting", ( retryInterval ) => {
+                    this.#clientStatus = clientStatusEnum.CONNECTING;
+                    logger.log( `Client '${ this.identifier }' reconnecting to Redis server after ${ retryInterval } ms.`, logger.logSeverity.DEBUG );
                 } );
-                this.#redisConnection.on( "reconnecting", ( info ) => {
-                    if ( info.attempt > 1 ) {
-                        logger.log( `Client '${ this.identifier }' reconnecting to Redis server after ${ info.delay } ms. This is attempt ${ info.attempt }.`, logger.logSeverity.DEBUG );
+                this.#redisConnection.on( "end", () => {
+                    if ( this.#clientStatus !== clientStatusEnum.SHUTTING_DOWN ) {
+                        this.#clientStatus = clientStatusEnum.DISCONNECTED;
+                        logger.log( `Client '${ this.identifier }' cannot reconnect to Redis server and has been shut down.`, logger.logSeverity.WARNING );
+                        this.#notifyConnectionObservers();
                     }
                 } );
             } catch ( error ) {
@@ -465,10 +507,31 @@ class RedisClient {
         } );
     }
 
+    /**
+     * Used to notify all connection observers about the current connection state.
+     *
+     * @method
+     * @private
+     */
+    #notifyConnectionObservers() {
+        // Notify all connection observers about the event:
+        _.forEach( this.#connectionObservers, ( connectionObservers ) => {
+            if ( this.#clientStatus === clientStatusEnum.CONNECTED ) {
+                logger.log( `Connection to Redis server ${ this.#redisConnection.options.host }:${ this.#redisConnection.options.port } (re)established by client '${ this.identifier }' and is ready to be used.`, logger.logSeverity.INFO );
+                connectionObservers.onConnectionRecovered( this.#clientIdentifier );
+            } else if ( this.#clientStatus === clientStatusEnum.DISRUPTED ) {
+                connectionObservers.onConnectionDisrupted( this.#clientIdentifier );
+            } else if ( this.#clientStatus === clientStatusEnum.DISCONNECTED ) {
+                connectionObservers.onConnectionLost( this.#clientIdentifier );
+            }
+        } );
+    }
+
     /**
      * Used to fetch and store Redis server information.
      *
      * @method
+     * @returns {Promise}
      * @private
      */
     #fetchServerInfo() {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.2.3",
+  "version": "1.3.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.",
   "author": "Boris Kostadinov <kostadinov.boris@gmail.com>",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./bin/start-instance.js",
+    "./cache": "./utils/cache.js",
     "./exceptions": "./utils/exceptions.js",
     "./localization": "./utils/localization.js",
     "./logger": "./utils/logger.js",

package/utils/cache.js

@@ -124,6 +124,22 @@ class CommonMemoryCache extends ConnectionObserver {
         }
     }
 
+    /**
+     * Needs to be invoked by the connection handler when the connection is irrevocably lost.
+     *
+     * @method
+     * @param {string} identifier The identifier of the observed connection.
+     * @override
+     * @public
+     */
+    onConnectionLost( identifier ) {
+        if ( identifier === this.#connectionIdentifier ) {
+            this.#isOperational = false;
+            // TODO: implement forced shut down of the service instance instead of crashing it outright
+            throw exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE );
+        }
+    }
+
     /**
      * Used to register a new {@link ConnectionObserver} for events related to the underlying Redis connection state.
      *
@@ -317,13 +333,19 @@ class CommonMemoryCache extends ConnectionObserver {
      * @method
      * @param {string} key
      * @param {number} seconds
+     * @param {string} [name] If you need to expire a field in a hash set instead, provide the name of the set here.
      * @returns {Promise<number>} This will resolve with the seconds as provided initially by the caller.
      * @public
      */
-    expireValue( key, seconds ) {
+    expireValue( key, seconds, name ) {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
-                let commandExpire = [ redis.cacheCommands.EXPIRE, key, seconds ];
+                let commandExpire = [];
+                if ( name ) {
+                    commandExpire = [ redis.cacheCommands.HASH_EXPIRE, name, seconds, "FIELDS", 1, key ];
+                } else {
+                    commandExpire = [ redis.cacheCommands.EXPIRE, key, seconds ];
+                }
                 this.#redisClient.executeCommands( [ commandExpire ] ).then( () => {
                     resolve( seconds );
                 } ).catch( ( error ) => {
@@ -508,7 +530,7 @@ class CommonMemoryCache extends ConnectionObserver {
     hashSetField( key, name, value ) {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
-                let commandHashSetField = [ redis.cacheCommands.HASH_SET_MANY, key, name, tools.stringifyJSON( value ) ];
+                let commandHashSetField = [ redis.cacheCommands.HASH_SET, key, name, tools.stringifyJSON( value ) ];
                 this.#redisClient.executeCommands( [ commandHashSetField ] ).then( () => {
                     resolve();
                 } ).catch( ( error ) => {
@@ -535,10 +557,10 @@ class CommonMemoryCache extends ConnectionObserver {
     hashSetFields( key, fields ) {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
-                let commandHashSetFields = [ redis.cacheCommands.HASH_SET_MANY, key ];
+                let commandHashSetFields = [ redis.cacheCommands.HASH_SET, key ];
                 _.forEach( fields, ( field ) => {
                     commandHashSetFields.push( field.name );
-                    commandHashSetFields.push( _.isObjectLike( field.value ) ? tools.stringifyJSON( field.value ) : field.value );
+                    commandHashSetFields.push( tools.stringifyJSON( field.value ) );
                 } );
                 this.#redisClient.executeCommands( [ commandHashSetFields ] ).then( () => {
                     resolve();
@@ -576,6 +598,31 @@ class CommonMemoryCache extends ConnectionObserver {
         } );
     }
 
+    /**
+     * Used to remove a single field from a hash.
+     *
+     * @method
+     * @param {string} key
+     * @param {string} field
+     * @return {Promise<boolean>} Will return 'true' if the field was removed, 'false' otherwise.
+     * @public
+     */
+    hashDeleteField( key, field ) {
+        return new Promise( ( resolve, reject ) => {
+            if ( this.#isOperational === true ) {
+                let commandHashGetField = [ redis.cacheCommands.HASH_REMOVE, key, field ];
+                this.#redisClient.executeCommands( [ commandHashGetField ] ).then( ( results ) => {
+                    results = results[ 0 ];
+                    resolve( ( results && results.length > 1 ) ? tools.toBool( results[ 1 ] ) : false );
+                } ).catch( ( error ) => {
+                    reject( error );
+                } );
+            } else {
+                reject( exceptions.raise( exceptions.exceptionCode.E_GEN_SYSTEM_CACHE_UNAVAILABLE ) );
+            }
+        } );
+    }
+
     /**
      * Used to store a JSON variable.
      * <br/>

package/utils/exceptions.js

@@ -38,6 +38,7 @@ let exceptionCodeEnum = tools.enum( {
     E_COM_SERVICE_NOT_FOUND: [ 3004, "service not found", "The specified service is not found in the service definition interface." ],
     E_COM_SERVICE_HANDLER_NOT_FOUND: [ 3005, "service handler not found", "No handler found in the interface for the specified service or service version." ],
     E_COM_MESSAGE_RECEIVER_UNAVAILABLE: [ 3006, "message receiver unavailable", "The message receiver instance is currently unavailable." ],
+    E_COM_MESSAGE_EXCHANGE_BROKEN: [ 3007, "message exchange broken", "The message exchange is irrevocably broken and cannot be used any longer." ],
     // E_COM_UNRECOGNIZED_API_URL: [ 301, "unrecognized api url", "Attempt to access unrecognized or invalid API URL." ],
     // E_COM_MISSING_REQUIRED_ARGUMENTS: [ 302, "missing required arguments", "Attempt to execute operation without all required arguments." ],
     // E_COM_UNRECOGNIZED_RESPONSE_STRUCTURE: [ 303, "unrecognized response structure", "The received response has unrecognized structure and cannot be parsed or examined." ],
@@ -248,4 +249,4 @@ module.exports.raise = ( source, data, exceptionID ) => {
  */
 module.exports.isException = ( object ) => {
     return ( object instanceof Exception );
-};
+};

package/utils/tools.js

@@ -319,8 +319,7 @@ module.exports.retrocycle = ( $ ) => {
  * @public
  */
 module.exports.stringifyJSON = ( value ) => {
-    let transformed = module.exports.decycle( value );
-    return _.isObjectLike( transformed ) ? JSON.stringify( _.toPlainObject( transformed ) ) : value;
+    return _.isObjectLike( value ) ? JSON.stringify( _.toPlainObject( module.exports.decycle( value ) ) ) : value;
 };
 
 /**
@@ -537,4 +536,4 @@ class RetryPolicy {
 
 }
 
-module.exports.RetryPolicy = RetryPolicy;
+module.exports.RetryPolicy = RetryPolicy;