vrpc 3.6.0 → 3.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vrpc",
-  "version": "3.6.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",
@@ -45,9 +45,9 @@
   "bugs": {
     "url": "https://github.com/heisenware/vrpc/issues"
   },
-  "homepage": "https://vrpc.io",
+  "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
@@ -235,11 +260,8 @@ class VrpcClient extends EventEmitter {
             `${this._domain}/${agent}/+/__classInfoConcise__`
           )
         }
-        // RPC responses
-        await this._mqttSubscribe(this._vrpcClientId)
-
-        // Single wildcard subscription for ALL continuous remote events
-        await this._mqttSubscribe(`${this._vrpcClientId}/__e__/#`)
+        // Single wildcard catches BOTH RPC responses (length 3) AND events (length 4)
+        await this._mqttSubscribe(`${this._vrpcConnectionId}/#`)
 
         // Re-subscribe to all cached event topics
         this._log.debug('Restoring event subscriptions after reconnect...')
@@ -412,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)
@@ -465,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__`
@@ -505,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}`
@@ -548,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 === '*') {
@@ -711,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
@@ -755,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()
@@ -767,7 +793,7 @@ class VrpcClient extends EventEmitter {
 
   // Private functions
 
-  static _createHash (str, length = 20) {
+  static _createHash (str, length = 16) {
     // Extended DJB2 hash with two accumulators
     let hash1 = 5381
     let hash2 = 52711 // different seed
@@ -822,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,
@@ -984,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
     }
@@ -1007,27 +1042,19 @@ class VrpcClient extends EventEmitter {
 
           const obsoleteTopics = Object.keys(this._cachedSubscriptions).filter(
             topic => {
-              const tokens = topic.split('/')
-              if (tokens[3] === '__e__') {
-                const topicInstance = tokens[6]
-                const topicEvent = tokens[7]
-                return topicInstance === instance && topicEvent === eventName
-              }
-              // Legacy fallback
-              const expectedOld = `${this._domain}/${agent}/${className}/${instance}:${eventName}`
-              return topic.startsWith(expectedOld)
+              const sub = this._cachedSubscriptions[topic]
+              return sub.instance === instance && sub.event === eventName
             }
           )
 
           obsoleteTopics.forEach(topic => {
             const id = `__e__${topic}`
-            const subscriptions = this._cachedSubscriptions[topic]
-            subscriptions.forEach(({ handler }) => {
+            const sub = this._cachedSubscriptions[topic]
+
+            sub.listeners.forEach(({ handler }) => {
               this._eventEmitter.removeListener(id, handler)
             })
-            if (!topic.includes('__e__')) {
-              this._mqttUnsubscribe(topic).catch(() => {})
-            }
+
             delete this._cachedSubscriptions[topic]
           })
           try {
@@ -1038,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(
@@ -1072,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(
@@ -1107,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(
@@ -1284,10 +1311,14 @@ class VrpcClient extends EventEmitter {
   async _onRemoteEvent ({ agent, className, instance, event, callback }) {
     const callbackId = this._getCallbackId(callback)
 
-    // Route directly to the client's single event inbox wildcard.
-    const topic = `${this._vrpcClientId}/__e__/${agent}/${className}/${
+    // Generate a short, sanitized hash
+    const hashInput = `${agent}-${className}-${
       instance || '__static__'
-    }/${event}/${callbackId}`
+    }-${event}-${callbackId}`
+    const topicId = VrpcClient._createHash(hashInput, 12)
+
+    // Route directly to the client's single event inbox wildcard
+    const topic = `${this._vrpcConnectionId}/${topicId}`
     const id = `__e__${topic}`
 
     const handler = ({ a }) => callback.apply(null, a)
@@ -1298,10 +1329,16 @@ class VrpcClient extends EventEmitter {
     }
 
     if (!this._cachedSubscriptions[topic]) {
-      this._cachedSubscriptions[topic] = [{ callback, handler }]
+      // Store metadata explicitly
+      this._cachedSubscriptions[topic] = {
+        agent,
+        className,
+        instance,
+        event,
+        listeners: [{ callback, handler }]
+      }
     } else {
-      // We MUST push duplicates to act as a reference counter!
-      this._cachedSubscriptions[topic].push({ callback, handler })
+      this._cachedSubscriptions[topic].listeners.push({ callback, handler })
     }
 
     return id
@@ -1312,29 +1349,22 @@ class VrpcClient extends EventEmitter {
     if (!callbackId) return null
 
     let foundId = null
-    const topics = Object.keys(this._cachedSubscriptions).filter(
-      t => t.endsWith(`/${callbackId}`) || t.endsWith(`-${callbackId}`)
-    )
+    const topics = Object.keys(this._cachedSubscriptions)
 
     topics.forEach(topic => {
       const id = `__e__${topic}`
-      const index = this._cachedSubscriptions[topic].findIndex(
-        x => x.callback === callback
-      )
+      const sub = this._cachedSubscriptions[topic]
+
+      const index = sub.listeners.findIndex(x => x.callback === callback)
 
       if (index !== -1) {
         // Decrease the "reference count" by removing one instance
-        this._cachedSubscriptions[topic].splice(index, 1)
+        sub.listeners.splice(index, 1)
 
         // Only remove from the local event emitter if NO references remain
-        if (this._cachedSubscriptions[topic].length === 0) {
+        if (sub.listeners.length === 0) {
           delete this._cachedSubscriptions[topic]
 
-          // Legacy cleanup just in case
-          if (!topic.includes('__e__')) {
-            this._mqttUnsubscribe(topic).catch(() => {})
-          }
-
           // Cleanly wipe all listeners for this specific id
           this._eventEmitter.removeAllListeners(id)
         }
@@ -1347,27 +1377,20 @@ class VrpcClient extends EventEmitter {
   _clearCachedSubscriptions ({ lostAgent, lostInstance }) {
     const obsoleteTopics = Object.keys(this._cachedSubscriptions).filter(
       topic => {
-        const tokens = topic.split('/')
-        if (tokens[3] === '__e__') {
-          const topicAgent = tokens[4]
-          const topicInstance = tokens[6]
-          return topicAgent === lostAgent || topicInstance === lostInstance
-        }
-        // Legacy fallback
-        const [, agent, , instanceEvent] = topic.split('/')
-        const [instance] = (instanceEvent || '').split(':')
-        return agent === lostAgent || instance === lostInstance
+        const sub = this._cachedSubscriptions[topic]
+        return sub.agent === lostAgent || sub.instance === lostInstance
       }
     )
+
     obsoleteTopics.forEach(topic => {
       const id = `__e__${topic}`
       this._log.debug(`Clearing subscriptions for obsolete topic: ${topic}`)
-      const subscriptions = this._cachedSubscriptions[topic]
-      subscriptions.forEach(({ handler }) => {
+      const sub = this._cachedSubscriptions[topic]
+
+      sub.listeners.forEach(({ handler }) => {
         this._eventEmitter.removeListener(id, handler)
       })
-      // this async function will never reject
-      this._mqttUnsubscribe(topic)
+
       delete this._cachedSubscriptions[topic]
     })
   }

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)
   }
 }