@adobe/acc-js-sdk 1.1.5 → 1.1.6

package/.eslintrc.js

@@ -4,7 +4,8 @@ module.exports = {
         "commonjs": true,
         "es2021": true,
         "node": true,
-        "jest": true
+        "jest": true,
+        circus: true
     },
     "extends": "eslint:recommended",
     "parserOptions": {

package/CHANGELOG.md

@@ -5,6 +5,11 @@ This is a node.js SDK for Campaign API. It exposes the Campaign API exactly like
 
 # Changelog 
 
+## Version 1.1.6
+_2022_08_19_
+
+* New auto-refresh mechanism to keep schemas and option caches up-to-date. See `client.startRefreshCaches` and `client.stopRefreshCaches` functions.
+
 ## Version 1.1.5
 _2022/07/07__
 

package/README.md

@@ -693,6 +693,30 @@ It's possible to disable persistent caches using the `noStorage` connection opti
 It is also possible to setup one's own persistent cache, by passing a `storage` object as a connection option. This object should implement 3 methods: `getItem`, `setItem`, and `removeItem` (synchronous)
 
 
+## Auto-refresh caches
+
+The SDK includes a mechnism to maintain the schemas and options caches up-to-date by polling the Campaign server on a regular basis (10 seconds by default). The server returns the list of entities (schemas or options) which have changed since they were cached, and the client removes them from the cache. When a schema changes, the corresponding methods are also removed from the method cache.
+
+This mechanism is not activate by default but can be activated or deactivated by the following functions
+
+```js
+client.startRefreshCaches(30000);   // activate cache auto-refresh mechanism every 30s
+client.stopRefreshCaches();         // de-activate cache auto-refresh
+```
+
+This mechanism is based on the `xtk:session#GetModifiedEntities` SOAP method which is only available in Campaign 8.4 and above only. For other builds of Campaign, the auto-refresh mechanism will not do anything. 
+
+The following changes are handled:
+* If the build number has changed, the whole cache is cleared
+* If more than 10 schemas or options have changed, the whole cache is cleared
+* if less than 10 schemas or options have changed, only those entities are removed from the cache
+
+
+The refresh mechanism includes the following guardrails
+* Both xtk:option and xtk:schema caches are refreshed every n seconds. To avoid issuing two API calls at the same time to the server, the schema cache refresh call is delayed by a few seconds. In the future this delay may change.
+* If the xtk:session#GetModifiedEntities API is not available, the auto refresh mechanism will silently stop automatically
+* If an error occurs while trying to refresh, a warning will be logged to the JavaScript console but the auto refresh will not be stopped. 
+
 ## Passwords
 
 External account passwords can be decrypted using a Cipher. This function is deprecated since version 1.0.0 since it's not guaranteed to work in future versions of Campaign (V8 and above)

package/compile.js

@@ -36,6 +36,7 @@ var resources = [
     { name: "./xtkEntityCache.js" },
     { name: "./methodCache.js" },
     { name: "./optionCache.js" },
+    { name: "./cacheRefresher.js" },
     { name: "./soap.js" },
     { name: "./crypto.js" },
     { name: "./application.js" },

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@adobe/acc-js-sdk",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@adobe/acc-js-sdk",
-      "version": "1.1.5",
+      "version": "1.1.6",
       "license": "ISC",
       "dependencies": {
         "axios": "^0.25.0",
@@ -1402,14 +1402,21 @@
       }
     },
     "node_modules/caniuse-lite": {
-      "version": "1.0.30001301",
-      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001301.tgz",
-      "integrity": "sha512-csfD/GpHMqgEL3V3uIgosvh+SVIQvCh43SNu9HRbP1lnxkKm1kjDG4f32PP571JplkLjfS+mg2p1gxR7MYrrIA==",
+      "version": "1.0.30001378",
+      "resolved": "https://artifactory.corp.adobe.com/artifactory/api/npm/npm-adobe-release/caniuse-lite/-/caniuse-lite-1.0.30001378.tgz",
+      "integrity": "sha512-JVQnfoO7FK7WvU4ZkBRbPjaot4+YqxogSDosHv0Hv5mWpUESmN+UubMU6L/hGz8QlQ2aY5U0vR6MOs6j/CXpNA==",
       "dev": true,
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/browserslist"
-      }
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/browserslist"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/caniuse-lite"
+        }
+      ],
+      "license": "CC-BY-4.0"
     },
     "node_modules/catharsis": {
       "version": "0.9.0",
@@ -6147,9 +6154,9 @@
       "dev": true
     },
     "caniuse-lite": {
-      "version": "1.0.30001301",
-      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001301.tgz",
-      "integrity": "sha512-csfD/GpHMqgEL3V3uIgosvh+SVIQvCh43SNu9HRbP1lnxkKm1kjDG4f32PP571JplkLjfS+mg2p1gxR7MYrrIA==",
+      "version": "1.0.30001378",
+      "resolved": "https://artifactory.corp.adobe.com/artifactory/api/npm/npm-adobe-release/caniuse-lite/-/caniuse-lite-1.0.30001378.tgz",
+      "integrity": "sha512-JVQnfoO7FK7WvU4ZkBRbPjaot4+YqxogSDosHv0Hv5mWpUESmN+UubMU6L/hGz8QlQ2aY5U0vR6MOs6j/CXpNA==",
       "dev": true
     },
     "catharsis": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/acc-js-sdk",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "ACC Javascript SDK",
   "main": "src/index.js",
   "homepage": "https://github.com/adobe/acc-js-sdk#readme",

package/src/application.js

@@ -65,20 +65,46 @@ function propagateImplicitValues(xtkDesc, labelOnly) {
 // ========================================================================================
 // Schema Cache
 // ========================================================================================
+
+/**
+ * A cache of schemas of type `XtkSchema` instead of plain XML or JSON objects
+ * 
+ * @private
+ * @class
+ * @constructor
+ * @memberof Campaign
+ */
+
 class SchemaCache {
     constructor(client) {
         this._client = client;
         this._schemas = {};
     }
+
+    /**
+      * Get a schema by id from schema cache of type `XtkSchema` 
+     * 
+     * @param {string} schemaId 
+     * @returns {Campaign.XtkSchema} the schema, or null if the schema was not found
+     */
     async getSchema(schemaId) {
         let schema = this._schemas[schemaId];
         if (schema === undefined) {
             schema = await this._client.application._getSchema(schemaId);
             if (!schema) schema = null; // null = not found
-        this._schemas[schemaId] = schema;
+            this._schemas[schemaId] = schema;
         }
         return schema;
     }
+
+    /**
+      * Remove a schema from schema cache. The callback function when refreshing cache in cacheRefresher 
+     * 
+     * @param {string} schemaId 
+     */
+    invalidateCacheItem(schemaId) {
+        this._schemas[schemaId] = undefined;
+    }
 }
 
 // ========================================================================================
@@ -1237,6 +1263,13 @@ class Application {
         }
     }
 
+    _registerCacheChangeListener() {
+        this.client._registerCacheChangeListener(this._schemaCache);
+    }
+
+    _unregisterCacheChangeListener() {
+        this.client._unregisterCacheChangeListener(this._schemaCache);
+    }
     /**
      * Get a schema by id. This function returns an XtkSchema object or null if the schema is not found.
      * Using the `XtkSchema` API makes it easier to navigate schemas than using a plain XML or JSON object
@@ -1248,7 +1281,7 @@ class Application {
         return this._schemaCache.getSchema(schemaId);
     }
 
-    // Private function: get a schema without using the cache
+    // Private function: get a schema without using the SchemaCache
     async _getSchema(schemaId) {
         const xml = await this.client.getSchema(schemaId, "xml");
         if (!xml)

package/src/cache.js

@@ -123,6 +123,7 @@ class SafeStorage {
     } catch(ex) { /* Ignore errors in safe class */
     }
   }
+
 }
 
 /**
@@ -243,7 +244,7 @@ class Cache {
 
   /**
    * Put a value from the cache
-   * @param {*} key the key or keys of the value to retreive
+   * @param {*} key the key or keys of the value to retrieve
    * @param {*} value the value to cache
    * @returns {CachedObject} a cached object containing the cached value
    */
@@ -266,6 +267,15 @@ class Cache {
       this._cache = {};
       this._saveLastCleared();
   }
+
+  /**
+   * Remove a key from the cache
+   * @param {string} key the key to remove
+   */
+  remove(key) {
+      delete this._cache[key];
+      this._remove(key);
+  }
 }
 
 // Public expots

package/src/cacheRefresher.js

@@ -0,0 +1,227 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+(function () {
+    "use strict";
+
+    const { DomUtil } = require("./domUtil.js");
+    const XtkCaster = require('./xtkCaster.js').XtkCaster;
+    const { Cache } = require('./cache.js');
+    const { CampaignException } = require('./campaign.js');
+
+    /**
+     * @private
+     * @class
+     * @constructor
+     * @memberof Campaign
+     */
+    class RefresherStateCache extends Cache {
+
+        /**
+         * A cache to store state of the refresher. Not intended to be used directly,
+         * but an internal cache for the Campaign.Client object
+         * 
+         * Cached object are made of
+         * - the key is the propertie name
+         * - the value is a string
+         * 
+         * @param {Storage} storage is an optional Storage object, such as localStorage or sessionStorage
+         * @param {string} rootKey is an optional root key to use for the storage object
+         * @param {number} ttl is the TTL for objects in ms. Defaults to 5 mins
+         */
+        constructor(storage, rootKey, ttl) {
+            super(storage, rootKey, ttl);
+        }
+
+        /**
+         * Cache a property of the refresh (buildNumber, last refresh time) and its value
+         * 
+         * @param {string} name is the propertie name
+         * @param {string} rawValue string value
+         */
+        put(name, rawValue) {
+            return super.put(name, { value: rawValue });
+        }
+
+        /**
+         * Get the value of a property of the refresh (buildNumber, last refresh time)
+         * 
+         * @param {string} name the propertie name
+         * @returns {*} the value
+         */
+        get(name) {
+            const option = super.get(name);
+            return option ? option.value : undefined;
+        }
+    }
+
+    class CacheRefresher {
+
+        /**
+        * A class to refresh regulary a Cache every n seconds, by sending a query to get the last modified entities.
+        * The refresh mechanism can be activated by calling client.startRefreshCaches().
+        * This mechanism depends on the xtk:session:GetModifiedEntities API which is introduced in ACC 8.4 and above.
+        *
+        * @param {Cache} cache is the cache to refresh
+        * @param {Client} client is the ACC API Client.
+        * @param {string} cacheSchemaId is the id of the schema present in the cache to be refreshed every 10 seconds
+        * @param {string} rootKey is used as the root key of cache items in the refresher state cache
+        */
+        constructor(cache, client, cacheSchemaId, rootKey) {
+            const connectionParameters = client._connectionParameters;
+            this._cache = cache;
+            this._client = client;
+            this._connectionParameters = connectionParameters;
+            this._cacheSchemaId = cacheSchemaId;
+
+            this._storage = connectionParameters._options._storage;
+            this._refresherStateCache  = new RefresherStateCache(this._storage, `${rootKey}.RefresherStateCache`, 1000*3600);
+
+            this._lastTime = undefined;
+            this._buildNumber = undefined;
+            this._intervalId = null;
+            this._running = false;
+        }
+
+        /**
+         * Start auto refresh
+         * @param {integer} refreshFrequency frequency of the refresh in ms (default value is 10,000 ms)
+         */
+        startAutoRefresh(refreshFrequency) {
+            if (this._intervalId != null) {
+                clearInterval(this._intervalId);
+            }
+            this._intervalId = setInterval(() => {
+                this._safeCallAndRefresh();
+            }, refreshFrequency || 10000); // every 10 seconds by default
+        }
+
+        // Protect _callAndRefresh from reentrance
+        async _safeCallAndRefresh() {
+            if (this._running) {
+                // This call is already running and maybe taking a long time to complete. Do not make things
+                // harder and just skip this run
+                return;
+            }
+            this._running = true;
+            try {
+                await this._callAndRefresh();
+            } catch(ex) {
+                if (ex.errorCode === "SDK-000010") {
+                    // client is not logged, this is not an error.
+                    return;
+                }
+                console.warn(`Failed to refresh cache for ${this._cacheSchemaId}`, ex);
+            }
+              finally {
+                this._running = false;
+            }
+        }
+
+        // Get last modified entities for the Campaign server and remove from cache last modified entities
+        async _callAndRefresh() {
+            const that = this;
+            const soapCall = this._client._prepareSoapCall("xtk:session", "GetModifiedEntities", true, this._connectionParameters._options.extraHttpHeaders);
+
+            if (this._lastTime === undefined) {
+                const storedTime = this._refresherStateCache.get("time");
+                if (storedTime != undefined) {
+                    this._lastTime = storedTime;
+                }
+            }
+            if (this._buildNumber === undefined) {
+                const storedBuildNumber = this._refresherStateCache.get("buildNumber");
+                if (storedBuildNumber != undefined) {
+                    this._buildNumber = storedBuildNumber;
+                }
+            }
+
+            // Use Json because xtk:schema does not work directly in DomUtil.parse(`<cache buildNumber="9469" time="2022-06-30T00:00:00.000"><xtk:schema></xtk:schema></cache>`);
+            // due to the colon character
+            let jsonCache;
+            if (this._lastTime === undefined || this._buildNumber === undefined) {
+                jsonCache = {
+                    [this._cacheSchemaId]: {}
+                };
+            } else {
+                jsonCache = {
+                    buildNumber: this._buildNumber,
+                    lastModified: this._lastTime,
+                    [this._cacheSchemaId]: {}
+                };
+            }
+
+            const xmlDoc = DomUtil.fromJSON("cache", jsonCache, 'SimpleJson');
+            soapCall.writeDocument("cacheEntities", xmlDoc);
+
+            // Client is not logged: do not attempt to refresh caches at all
+            if (!this._client.isLogged())
+              throw CampaignException.NOT_LOGGED_IN(soapCall, `Cannot call GetModifiedEntities: session not connected`);
+
+            // Do a soap call GetModifiedEntities instead of xtksession.GetModifiedEnties because we don't want to go through methodCache 
+            // which might not contain the method GetModifiedEntities just after a build updgrade from a old version of acc 
+            return this._client._makeSoapCall(soapCall)
+                .then(() => {
+                    let doc = soapCall.getNextDocument();
+                    soapCall.checkNoMoreArgs();
+                    doc = that._client._toRepresentation(doc, 'xml');
+                    that._lastTime = DomUtil.getAttributeAsString(doc, "time"); // save time to be able to send it as an attribute in the next soap call
+                    that._buildNumber = DomUtil.getAttributeAsString(doc, "buildNumber");
+                    that._refresh(doc);
+                    that._refresherStateCache.put("time", that._lastTime);
+                    that._refresherStateCache.put("buildNumber", that._buildNumber);
+                })
+                .catch((ex) => {
+                    // if the method GetModifiedEntities is not found in this acc version we disable the autoresfresh of the cache
+                    if (soapCall.methodName == "GetModifiedEntities" && ex.errorCode == "SOP-330006") {
+                        this.stopAutoRefresh();
+                    } else {
+                        throw ex;
+                    }
+                });
+        }
+
+        // Refresh Cache : remove entities modified recently listed in xmlDoc
+        _refresh(xmlDoc) {
+            const clearCache = XtkCaster.asBoolean(DomUtil.getAttributeAsString(xmlDoc, "emptyCache"));
+            if (clearCache == true) {
+                this._cache.clear();
+            } else {
+                var child = DomUtil.getFirstChildElement(xmlDoc, "entityCache");
+                while (child) {
+                    const pkSchemaId = DomUtil.getAttributeAsString(child, "pk");
+                    const schemaId = DomUtil.getAttributeAsString(child, "schema");
+                    if (schemaId === this._cacheSchemaId) {
+                        this._cache.remove(pkSchemaId);
+                        // Notify listeners to refresh in SchemaCache
+                        if (schemaId === "xtk:schema") {
+                            const schemaIds = pkSchemaId.split("|");
+                            this._client._notifyCacheChangeListeners(schemaIds[1]);
+                        }
+                    }
+                    child = DomUtil.getNextSiblingElement(child);
+                }
+            }
+        }
+
+        /**
+         * Stop auto refreshing the cache
+         */
+        stopAutoRefresh() {
+            clearInterval(this._intervalId);
+            this._intervalId = null;
+        }
+    }
+
+    // Public exports
+    exports.CacheRefresher = CacheRefresher;
+
+})();

package/src/client.js

@@ -31,6 +31,7 @@ const Cipher = require('./crypto.js').Cipher;
 const DomUtil = require('./domUtil.js').DomUtil;
 const MethodCache = require('./methodCache.js').MethodCache;
 const OptionCache = require('./optionCache.js').OptionCache;
+const CacheRefresher = require('./cacheRefresher.js').CacheRefresher;
 const request = require('./transport.js').request;
 const Application = require('./application.js').Application;
 const EntityAccessor = require('./entityAccessor.js').EntityAccessor;
@@ -532,13 +533,16 @@ class Client {
         const rootKey = `acc.js.sdk.${sdk.getSDKVersion().version}.${instanceKey}.cache`;
 
         this._entityCache = new XtkEntityCache(this._storage, `${rootKey}.XtkEntityCache`, connectionParameters._options.entityCacheTTL);
+        this._entityCacheRefresher = new CacheRefresher(this._entityCache, this, "xtk:schema", `${rootKey}.XtkEntityCache`);
         this._methodCache = new MethodCache(this._storage, `${rootKey}.MethodCache`, connectionParameters._options.methodCacheTTL);
         this._optionCache = new OptionCache(this._storage, `${rootKey}.OptionCache`, connectionParameters._options.optionCacheTTL);
+        this._optionCacheRefresher = new CacheRefresher(this._optionCache, this, "xtk:option", `${rootKey}.OptionCache`);
         this.NLWS = new Proxy(this, clientHandler());
 
         this._transport = connectionParameters._options.transport;
         this._traceAPICalls = connectionParameters._options.traceAPICalls;
         this._observers = [];
+        this._cacheChangeListeners = [];
         this._refreshClient = connectionParameters._options.refreshClient;
 
         // expose utilities
@@ -849,6 +853,7 @@ class Client {
             that._sessionToken = credentials._sessionToken;
             that._securityToken = "";
             that.application = new Application(that);
+            that.application._registerCacheChangeListener();
             return Promise.resolve();
         }
         else if (credentials._type == "SecurityToken") {
@@ -857,6 +862,7 @@ class Client {
             that._sessionToken = "";
             that._securityToken = credentials._securityToken;
             that.application = new Application(that);
+            that.application._registerCacheChangeListener();
             return Promise.resolve();
         }
         else if (credentials._type == "UserPassword" || credentials._type == "BearerToken") {
@@ -908,6 +914,7 @@ class Client {
                 that._securityToken = securityToken;
 
                 that.application = new Application(that);
+                that.application._registerCacheChangeListener();
             });
         }
         else {
@@ -933,10 +940,13 @@ class Client {
     logoff() {
         var that = this;
         if (!that.isLogged()) return;
+        that.application._unregisterCacheChangeListener();
+        that._unregisterAllCacheChangeListeners();
+        this.stopRefreshCaches();
         const credentials = this._connectionParameters._credentials;
         if (credentials._type != "SessionToken" && credentials._type != "AnonymousUser") {
             var soapCall = that._prepareSoapCall("xtk:session", "Logoff", false, this._connectionParameters._options.extraHttpHeaders);
-                return this._makeSoapCall(soapCall).then(function() {
+            return this._makeSoapCall(soapCall).then(function() {
                 that._sessionToken = "";
                 that._securityToken = "";
                 that.application = null;
@@ -958,15 +968,15 @@ class Client {
      * @return the option value, casted in the expected data type. If the option does not exist, it will return null.
      */
     async getOption(name, useCache = true) {
-        var value;
-        if (useCache)
-            value = this._optionCache.get(name);
-        if (value === undefined) {
-            const option = await this.NLWS.xtkSession.getOption(name);
-            value = this._optionCache.put(name, option);
-            this._optionCache.put(name, option);
-        }
-        return value;
+      var value;
+      if (useCache) {
+        value = this._optionCache.get(name);
+      }
+      if (value === undefined) {
+        const option = await this.NLWS.xtkSession.getOption(name);
+        value = this._optionCache.put(name, option);
+      }
+      return value;
     }
 
     /**
@@ -1032,6 +1042,50 @@ class Client {
         this.clearOptionCache();
     }
 
+    /**
+     * Start auto refresh of all caches
+     * @param {integer} refreshFrequency refresh frequency in ms. 10000 ms by default.
+     */
+    startRefreshCaches(refreshFrequency) {
+        if (refreshFrequency === undefined || refreshFrequency === null)
+            refreshFrequency = 10000;
+        this._optionCacheRefresher.startAutoRefresh(refreshFrequency);
+        // Start auto refresh for entityCache a little later
+        setTimeout(() => { this._entityCacheRefresher.startAutoRefresh(refreshFrequency); }, refreshFrequency/2);
+    }
+    /**
+     * Stop auto refresh of all caches
+     */
+    stopRefreshCaches() {
+        this._optionCacheRefresher.stopAutoRefresh();
+        this._entityCacheRefresher.stopAutoRefresh();
+    }
+
+    // Register a callback to be called when a schema has been modified and should be removed
+    // from the caches
+    _registerCacheChangeListener(listener) {
+        this._cacheChangeListeners.push(listener);
+    }
+
+    // Unregister a cache change listener
+    _unregisterCacheChangeListener(listener) {
+        for (var i = 0; i < this._cacheChangeListeners.length; i++) {
+            if (this._cacheChangeListeners[i] == listener) {
+                this._cacheChangeListeners.splice(i, 1);
+                break;
+            }
+        }
+    }
+
+    // Unregister all cache change listener
+    _unregisterAllCacheChangeListeners() {
+        this._cacheChangeListeners = [];
+    }
+
+    _notifyCacheChangeListeners(schemaId) {
+        this._cacheChangeListeners.map((listener) => listener.invalidateCacheItem(schemaId));
+    }
+
     /**
      * Tests if a package is installed
      * 
@@ -1101,11 +1155,12 @@ class Client {
         var that = this;
         var entity = that._entityCache.get("xtk:schema", schemaId);
         if (!entity) {
-            entity = await that.getEntityIfMoreRecent("xtk:schema", schemaId, "xml", internal);
-        }
-        if (entity)
+          entity = await that.getEntityIfMoreRecent("xtk:schema", schemaId, "xml", internal);
+          if (entity) {
             that._entityCache.put("xtk:schema", schemaId, entity);
-
+            that._methodCache.put(entity);
+          }
+        }
         entity = that._toRepresentation(entity, representation);
         return entity;
     }

package/test/application.test.js

@@ -1097,7 +1097,6 @@ describe('Application', () => {
                     </GetEntityIfMoreRecentResponse>
                 </SOAP-ENV:Body>
                 </SOAP-ENV:Envelope>`));
-
                 const nodes = await link.joinNodes();
                 expect(nodes).toMatchObject([]);
                 const reverseLink = await link.reverseLink();
@@ -2156,4 +2155,5 @@ describe('Application', () => {
             expect(client.application.version).toBe('6.7.0');
         })
     })
-});
+});
+