vrpc 3.7.0 → 3.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vrpc",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Variadic Remote Procedure Calls",
   "main": "index.js",
   "directories": {
@@ -15,7 +15,7 @@
     "test": "npm run test:adapter && npm run test:agent && npm run test:client && npm run test:persistor && npm run test:production",
     "test:adapter": "./node_modules/.bin/mocha tests/adapter/*.js --exit",
     "test:native": "./node_modules/.bin/mocha tests/native/*.js --exit",
-    "test:agent": "tests/agent/test.sh" ,
+    "test:agent": "tests/agent/test.sh",
     "test:client": "tests/client/test.sh",
     "test:performance": "tests/performance/test.sh",
     "test:persistor": "./node_modules/.bin/mocha tests/persistor/*.js --timeout 30000 --exit",
@@ -47,7 +47,7 @@
   },
   "homepage": "https://docs.heisenware.com/developers/vrpc",
   "devDependencies": {
-    "@heisenware/storage": "^1.2.2",
+    "@heisenware/storage": "^3.0.2",
     "chai": "^4.3.10",
     "crypto-browserify": "^3.12.1",
     "dockerode": "^4.0.9",
@@ -78,11 +78,11 @@
     "process": "^0.11.10"
   },
   "peerDependencies": {
-    "@heisenware/storage": "^1.2.2"
+    "@heisenware/storage": "^1.2.2 || ^2.0.0 || ^3.0.0"
   },
   "peerDependenciesMeta": {
     "@heisenware/storage": {
       "optional": true
     }
   }
-}
+}

package/vrpc/VrpcAgent.js

@@ -23,7 +23,7 @@ class VrpcAgent extends EventEmitter {
    * @param {String} defaults.agent This agent's name
    * @param {String} defaults.username MQTT username (if no token is used)
    * @param {String} defaults.password MQTT password (if no token is provided)
-   * @param {String} defaults.token Access token as generated by: https://app.vrpc.io
+   * @param {String} defaults.token Access token
    * @param {String} defaults.broker Broker url in form: `<scheme>://<host>:<port>`
    * @param {String} defaults.version The (user-defined) version of this agent
    * @returns {Agent} Agent instance
@@ -641,11 +641,13 @@ class VrpcAgent extends EventEmitter {
   }
 
   _handleClientInfoMessage (topic, json) {
-    // Client went offline
-    const clientId = topic.slice(0, -15) // /__clientInfo__ = 15
+    // A client connection went offline. The topic carries the connection
+    // id (unique per VrpcClient instance) - the key of all bookkeeping -
+    // so ending one connection never touches others sharing its identity.
+    const connectionId = topic.slice(0, -15) // /__clientInfo__ = 15
     if (json.status === 'offline') {
-      VrpcAdapter._unregisterClient(clientId)
-      const entry = this._isolatedInstances.get(clientId)
+      VrpcAdapter._unregisterClient(connectionId)
+      const entry = this._isolatedInstances.get(connectionId)
       if (entry) {
         entry.forEach(instanceId => {
           const json = { f: '__delete__', a: [instanceId], r: null }
@@ -655,8 +657,10 @@ class VrpcAgent extends EventEmitter {
           }
         })
       }
-      this._mqttUnsubscribe(`${clientId}/__clientInfo__`)
-      this.emit('clientGone', clientId)
+      this._mqttUnsubscribe(`${connectionId}/__clientInfo__`)
+      // clientId: the identity-derived id shared by all connections of one
+      // identity (undefined for clients < 3.8.0)
+      this.emit('clientGone', connectionId, { clientId: json.clientId })
     }
   }
 
@@ -825,10 +829,14 @@ class VrpcAgent extends EventEmitter {
 /**
  * Event 'clientGone'
  *
- * Emitted when a tracked VRPC client exited.
+ * Emitted when a tracked VRPC client connection ended. Listeners receive
+ * the connection id (unique per VrpcClient instance) and an info object
+ * whose `clientId` is the identity-derived id shared by all connections
+ * of one identity (undefined for clients < 3.8.0).
  *
  * @event VrpcAgent#clientGone
- * @type {String} clientId
+ * @type {String} connectionId
+ * @type {Object} info
  */
 
 module.exports = VrpcAgent

package/vrpc/VrpcBrowserAgent.js

@@ -495,11 +495,13 @@ class VrpcAgent extends EventEmitter {
   }
 
   _handleClientInfoMessage (topic, json) {
-    // Client went offline
-    const clientId = topic.slice(0, -15) // /__clientInfo__ = 15
+    // A client connection went offline. The topic carries the connection
+    // id (unique per VrpcClient instance) - the key of all bookkeeping -
+    // so ending one connection never touches others sharing its identity.
+    const connectionId = topic.slice(0, -15) // /__clientInfo__ = 15
     if (json.status === 'offline') {
-      VrpcAdapter._unregisterClient(clientId)
-      const entry = this._isolatedInstances.get(clientId)
+      VrpcAdapter._unregisterClient(connectionId)
+      const entry = this._isolatedInstances.get(connectionId)
       if (entry) {
         entry.forEach(instanceId => {
           const json = { f: '__delete__', a: [instanceId], r: null }
@@ -509,8 +511,10 @@ class VrpcAgent extends EventEmitter {
           }
         })
       }
-      this._mqttUnsubscribe(`${clientId}/__clientInfo__`)
-      this.emit('clientGone', clientId)
+      this._mqttUnsubscribe(`${connectionId}/__clientInfo__`)
+      // clientId: the identity-derived id shared by all connections of one
+      // identity (undefined for clients < 3.8.0)
+      this.emit('clientGone', connectionId, { clientId: json.clientId })
     }
   }
 
@@ -679,10 +683,14 @@ class VrpcAgent extends EventEmitter {
 /**
  * Event 'clientGone'
  *
- * Emitted when a tracked VRPC client exited.
+ * Emitted when a tracked VRPC client connection ended. Listeners receive
+ * the connection id (unique per VrpcClient instance) and an info object
+ * whose `clientId` is the identity-derived id shared by all connections
+ * of one identity (undefined for clients < 3.8.0).
  *
  * @event VrpcAgent#clientGone
- * @type {String} clientId
+ * @type {String} connectionId
+ * @type {Object} info
  */
 
 module.exports = VrpcAgent

package/vrpc/VrpcClient.js

@@ -74,7 +74,7 @@ class VrpcClient extends EventEmitter {
    * @example
    * const client = new VrpcClient({
    *   domain: 'vrpc',
-   *   broker: 'mqtt://vrpc.io'
+   *   broker: 'mqtts://broker.hivemq.com:8883'
    * })
    */
   constructor ({
@@ -127,6 +127,7 @@ class VrpcClient extends EventEmitter {
     this._instance = nanoid(8)
     this._mqttClientId = mqttClientId || this._createMqttClientId()
     this._vrpcClientId = this._createVrpcClientId()
+    this._vrpcConnectionId = this._createVrpcConnectionId()
     this._agents = {}
     this._eventEmitter = new EventEmitter()
     this._invokeId = 0
@@ -147,7 +148,13 @@ class VrpcClient extends EventEmitter {
   }
 
   /**
-   * Provides a unique id for this client instance
+   * Provides the identity-derived id of this client
+   *
+   * Every client constructed with the same domain, host and identity
+   * reports the same client id: it names the principal, not the
+   * connection. Agents receive it as `clientId` in the presence messages
+   * and can group the connections (e.g. browser tabs) of one identity by
+   * it. See getConnectionId() for the id that is unique per instance.
    *
    * @returns {String} clientId
    */
@@ -155,6 +162,21 @@ class VrpcClient extends EventEmitter {
     return this._vrpcClientId
   }
 
+  /**
+   * Provides the unique id of this connection
+   *
+   * Unique per VrpcClient instance: two clients sharing one identity still
+   * have distinct connection ids. Agents key all their bookkeeping by it
+   * (response routing, event listeners, isolated instances, presence), so
+   * one connection ending never disturbs the others of the same identity.
+   * Without an identity the connection id equals the client id.
+   *
+   * @returns {String} connectionId
+   */
+  getConnectionId () {
+    return this._vrpcConnectionId
+  }
+
   /**
    * Actually connects to the MQTT broker.
    *
@@ -184,8 +206,11 @@ class VrpcClient extends EventEmitter {
       rejectUnauthorized: false,
       connectTimeout: this._timeout,
       will: {
-        topic: `${this._vrpcClientId}/__clientInfo__`,
-        payload: JSON.stringify({ status: 'offline' })
+        topic: `${this._vrpcConnectionId}/__clientInfo__`,
+        payload: JSON.stringify({
+          status: 'offline',
+          clientId: this._vrpcClientId
+        })
       }
     }
     if (username === undefined) delete options.username
@@ -236,7 +261,7 @@ class VrpcClient extends EventEmitter {
           )
         }
         // Single wildcard catches BOTH RPC responses (length 3) AND events (length 4)
-        await this._mqttSubscribe(`${this._vrpcClientId}/#`)
+        await this._mqttSubscribe(`${this._vrpcConnectionId}/#`)
 
         // Re-subscribe to all cached event topics
         this._log.debug('Restoring event subscriptions after reconnect...')
@@ -409,7 +434,7 @@ class VrpcClient extends EventEmitter {
       f: isIsolated ? '__createIsolated__' : '__createShared__',
       a: [instance, ...args],
       i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
-      s: this._vrpcClientId,
+      s: this._vrpcConnectionId,
       v: VRPC_PROTOCOL_VERSION
     }
     const proxy = await this._getProxy(agent, className, json)
@@ -462,7 +487,7 @@ class VrpcClient extends EventEmitter {
       f: '__delete__',
       a: [instance],
       i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
-      s: this._vrpcClientId,
+      s: this._vrpcConnectionId,
       v: VRPC_PROTOCOL_VERSION
     }
     const topic = `${this._domain}/${agent}/${className}/__static__/__delete__`
@@ -502,7 +527,7 @@ class VrpcClient extends EventEmitter {
       f: functionName,
       a: wrapped,
       i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
-      s: this._vrpcClientId,
+      s: this._vrpcConnectionId,
       v: VRPC_PROTOCOL_VERSION
     }
     const topic = `${this._domain}/${agent}/${className}/__static__/${functionName}`
@@ -545,7 +570,7 @@ class VrpcClient extends EventEmitter {
       f: functionName,
       a: [],
       i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
-      s: this._vrpcClientId,
+      s: this._vrpcConnectionId,
       v: VRPC_PROTOCOL_VERSION
     }
     if (agent === '*') {
@@ -708,7 +733,7 @@ class VrpcClient extends EventEmitter {
   /**
    * Reconnects to the broker by using a different token
    *
-   * @param {String} token Access token as generated by: https://app.vrpc.io
+   * @param {String} token Access token
    * @param {Object} [options]
    * @param {String} options.agent Agent name. If not provided class default is used
    * @returns {Promise} Promise that resolves once re-connected
@@ -752,8 +777,12 @@ class VrpcClient extends EventEmitter {
   async end () {
     if (!this._client) return
     this._mqttPublish(
-      `${this._vrpcClientId}/__clientInfo__`,
-      JSON.stringify({ status: 'offline', v: VRPC_PROTOCOL_VERSION })
+      `${this._vrpcConnectionId}/__clientInfo__`,
+      JSON.stringify({
+        status: 'offline',
+        clientId: this._vrpcClientId,
+        v: VRPC_PROTOCOL_VERSION
+      })
     )
     this._eventEmitter.removeAllListeners()
     this.removeAllListeners()
@@ -819,6 +848,14 @@ class VrpcClient extends EventEmitter {
     return `${this._domain}/${os.hostname()}/${identity}`
   }
 
+  _createVrpcConnectionId () {
+    // Without an identity the client id already is unique per instance.
+    // With one, the instance token makes every connection of that identity
+    // distinct while keeping the three-segment layout agents parse.
+    if (!this._identity) return this._vrpcClientId
+    return `${this._vrpcClientId}:${this._instance}`
+  }
+
   _mqttPublish (topic, message, options) {
     this._client.publish(
       topic,
@@ -981,6 +1018,7 @@ class VrpcClient extends EventEmitter {
     const proxyId = `${this._instance}-${this._proxyId++}`
     const proxy = {
       vrpcClientId: this._vrpcClientId,
+      vrpcConnectionId: this._vrpcConnectionId,
       vrpcInstanceId: instance,
       vrpcProxyId: proxyId
     }
@@ -1027,7 +1065,7 @@ class VrpcClient extends EventEmitter {
               i: `${this._instance}-${
                 this._invokeId++ % Number.MAX_SAFE_INTEGER
               }`,
-              s: this._vrpcClientId,
+              s: this._vrpcConnectionId,
               v: VRPC_PROTOCOL_VERSION
             }
             this._mqttPublish(
@@ -1061,7 +1099,7 @@ class VrpcClient extends EventEmitter {
             i: `${this._instance}-${
               this._invokeId++ % Number.MAX_SAFE_INTEGER
             }`,
-            s: this._vrpcClientId,
+            s: this._vrpcConnectionId,
             v: VRPC_PROTOCOL_VERSION
           }
           this._mqttPublish(
@@ -1096,7 +1134,7 @@ class VrpcClient extends EventEmitter {
             i: `${this._instance}-${
               this._invokeId++ % Number.MAX_SAFE_INTEGER
             }`,
-            s: this._vrpcClientId,
+            s: this._vrpcConnectionId,
             v: VRPC_PROTOCOL_VERSION
           }
           this._mqttPublish(
@@ -1280,7 +1318,7 @@ class VrpcClient extends EventEmitter {
     const topicId = VrpcClient._createHash(hashInput, 12)
 
     // Route directly to the client's single event inbox wildcard
-    const topic = `${this._vrpcClientId}/${topicId}`
+    const topic = `${this._vrpcConnectionId}/${topicId}`
     const id = `__e__${topic}`
 
     const handler = ({ a }) => callback.apply(null, a)

package/vrpc/VrpcPersistor.js

@@ -47,6 +47,9 @@ const VrpcAdapter = require('./VrpcAdapter')
  * for an 'update' event on instances to persist their state after creation.
  *
  * @requires @heisenware/storage - This peer dependency must be installed.
+ * Storage 1.x (synchronous constructor) and >= 2.x (async `Storage.open`)
+ * are both supported; the layer is opened lazily and every operation waits
+ * for it.
  */
 class VrpcPersistor {
   /**
@@ -76,8 +79,8 @@ class VrpcPersistor {
         .toLocaleLowerCase()
         .replace(/[^a-zA-Z0-9]/g, '-')}`
 
-    this._storage = new Storage({ log: this._log, dir: this._dir })
-    this._isInitialized = this._init()
+    this._storage = null
+    this._isInitialized = this._init(Storage)
 
     this._log.info(
       `[VrpcPersistor] Persistence layer enabled. Storage path: ${this._dir}`
@@ -166,8 +169,12 @@ class VrpcPersistor {
    * Initializes the persistor by attaching listeners to VRPC adapter events.
    * @private
    */
-  async _init () {
+  async _init (Storage) {
     try {
+      // Listeners go first and synchronously: an instance created right
+      // after construction must be caught. The operations they trigger wait
+      // for the storage layer opened below.
+
       // Persist new instance creation
       VrpcAdapter.on('create', async ({ instance, className, args }) => {
         this._log.info(
@@ -211,6 +218,14 @@ class VrpcPersistor {
           )
         )
       })
+
+      // storage >= 2 constructs through the async factory only; 1.x has a
+      // synchronous constructor. No watcher: this persistor is the sole
+      // writer of its directory.
+      this._storage =
+        typeof Storage.open === 'function'
+          ? await Storage.open({ dir: this._dir, log: this._log, watch: false })
+          : new Storage({ dir: this._dir, log: this._log })
     } catch (err) {
       this._log.error(
         `[VrpcPersistor] Could not initialize persistence layer: ${err.message}`
@@ -225,6 +240,7 @@ class VrpcPersistor {
    * @private
    */
   async _persist (id, className, args) {
+    await this._isInitialized
     await this._storage.setItem(id, { className, args }, { folder: className })
   }
 
@@ -233,6 +249,7 @@ class VrpcPersistor {
    * @private
    */
   async _delete (id) {
+    await this._isInitialized
     await this._storage.removeItem(id)
   }
 }