vrpc 3.8.3 → 3.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vrpc",
-  "version": "3.8.3",
+  "version": "3.9.1",
   "description": "Variadic Remote Procedure Calls",
   "main": "index.js",
   "directories": {
@@ -12,13 +12,14 @@
     "build:addon": "ln -sf binding.gyp.no-auto binding.gyp && node-gyp rebuild && rm binding.gyp",
     "build:browser": "./node_modules/.bin/webpack --stats-error-details",
     "build:doc": "./node_modules/.bin/jsdoc2md -f vrpc/VrpcAdapter.js vrpc/VrpcAgent.js vrpc/VrpcClient.js vrpc/VrpcNative.js --param-list-format=list --separators > docs/api.md",
-    "test": "npm run test:adapter && npm run test:agent && npm run test:client && npm run test:persistor && npm run test:production",
+    "test": "npm run test:adapter && npm run test:agent && npm run test:client && npm run test:persistor && npm run test:lifecycle && 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:client": "tests/client/test.sh",
     "test:performance": "tests/performance/test.sh",
     "test:persistor": "./node_modules/.bin/mocha tests/persistor/*.js --timeout 30000 --exit",
+    "test:lifecycle": "./node_modules/.bin/mocha tests/lifecycle/*.js --timeout 30000 --exit",
     "test:production": "./node_modules/.bin/mocha tests/production/lifeCycleTest.js --timeout 30000 --exit && tests/production/test.sh"
   },
   "bin": {

package/vrpc/VrpcAdapter.js

@@ -9,12 +9,10 @@ __\/\\\_______\/\\\__/\\\///////\\\___\/\\\/////////\\\____/\\\////////__
       _______\//\\\_______\/\\\______\//\\\_\/\\\_______________\////\\\\\\\\\_
        ________\///________\///________\///__\///___________________\/////////__
 
-
 Non-intrusively adapts code and provides access in form of asynchronous remote
 procedure calls (RPC).
 Author: Dr. Burkhard C. Heisen (https://github.com/heisenware/vrpc)
 
-
 Licensed under the MIT License <http://opensource.org/licenses/MIT>.
 Copyright (c) 2018 - 2022 Dr. Burkhard C. Heisen <burkhard.heisen@heisenware.com>.
 
@@ -419,16 +417,45 @@ class VrpcAdapter {
     return this._mustTrackClient
   }
 
+  /**
+   * Refuses a request on an isolated instance that belongs to another
+   * connection. An isolated instance created over the wire remembers the
+   * connection that created it (the request's sender) and answers that
+   * connection alone; one the agent created itself has no owner and is
+   * open. The agent's own housekeeping passes as VrpcAdapter.LOCAL_SENDER,
+   * which no wire message can carry.
+   */
+  static _assertOwner (entry, json, instanceId) {
+    if (!entry || !entry.isIsolated || entry.owner === undefined) return
+    if (json.s === VrpcAdapter.LOCAL_SENDER || json.s === entry.owner) return
+    throw new Error(
+      `Instance '${instanceId}' is isolated to another connection`
+    )
+  }
+
   static _handleCreateIsolated (json) {
     let instance
     try {
       const className = json.c
       const [instanceId, ...args] = json.a
+      const existing = VrpcAdapter._instances.get(instanceId)
+      if (existing) {
+        // an id is never re-homed: a shared instance stays shared, an
+        // isolated one keeps its owner
+        if (!existing.isIsolated) {
+          throw new Error(`Instance '${instanceId}' exists as a shared instance`)
+        }
+        VrpcAdapter._assertOwner(existing, json, instanceId)
+        json.r = instanceId
+        return existing.instance
+      }
       instance = VrpcAdapter._create(className, instanceId, ...args)
       VrpcAdapter._instances.set(instanceId, {
         instance,
         className,
-        isIsolated: true
+        isIsolated: true,
+        // undefined for instances the agent creates itself (open)
+        owner: typeof json.s === 'string' ? json.s : undefined
       })
       VrpcAdapter._emitter.emit('create', {
         args,
@@ -449,6 +476,10 @@ class VrpcAdapter {
     try {
       const className = json.c
       const [instanceId, ...args] = json.a
+      const existing = VrpcAdapter._instances.get(instanceId)
+      if (existing && existing.isIsolated) {
+        throw new Error(`Instance '${instanceId}' exists as an isolated instance`)
+      }
       instance = VrpcAdapter._create(className, instanceId, ...args)
       VrpcAdapter._instances.set(instanceId, {
         instance,
@@ -524,6 +555,7 @@ class VrpcAdapter {
   static _handleDelete (json) {
     try {
       const instance = json.a[0] // first arg is instance to be deleted
+      VrpcAdapter._assertOwner(VrpcAdapter._instances.get(instance), json, instance)
       VrpcAdapter._emitter.emit('beforeDelete', {
         instance,
         className: json.c
@@ -540,6 +572,14 @@ class VrpcAdapter {
   }
 
   static _handleCall (json) {
+    // an isolated instance answers its creating connection only
+    try {
+      VrpcAdapter._assertOwner(VrpcAdapter._instances.get(json.c), json, json.c)
+    } catch (err) {
+      const { message, cause } = err
+      json.e = { message, cause }
+      return
+    }
     // special case: removeAllListeners
     if (json.f === 'removeAllListeners') {
       VrpcAdapter._removeAllListeners(json.a[0], json.s, json.c)
@@ -971,4 +1011,11 @@ VrpcAdapter._blackList = new Set([
   '__lookupSetter__'
 ])
 
+/**
+ * The sender the agent uses for its own housekeeping calls (deleting the
+ * isolated instances of a departed connection). A Symbol: no message from
+ * the wire can carry it, so it can never be claimed remotely.
+ */
+VrpcAdapter.LOCAL_SENDER = Symbol('vrpc.local-sender')
+
 module.exports = VrpcAdapter

package/vrpc/VrpcAgent.js

@@ -614,7 +614,14 @@ class VrpcAgent extends EventEmitter {
       // Intersecting life-cycle functions
       switch (method) {
         case '__createIsolated__': {
-          // TODO handle instantiation errors
+          if (json.e) {
+            // a constructor that threw leaves nothing behind: no instance,
+            // no subscription, no lifetime bookkeeping
+            this._log.warn(
+              `Instantiation of ${className} failed: ${json.e.message}`
+            )
+            break
+          }
           const instanceId = json.r
           // TODO await this
           this._subscribeToMethodsOfNewInstance(className, instanceId)
@@ -622,7 +629,12 @@ class VrpcAgent extends EventEmitter {
           break
         }
         case '__createShared__': {
-          // TODO handle instantiation errors
+          if (json.e) {
+            this._log.warn(
+              `Instantiation of ${className} failed: ${json.e.message}`
+            )
+            break
+          }
           const instanceId = json.r
           if (!this._hasSharedInstance(instanceId)) {
             this._subscribeToMethodsOfNewInstance(className, instanceId)
@@ -663,7 +675,12 @@ class VrpcAgent extends EventEmitter {
       const entry = this._isolatedInstances.get(connectionId)
       if (entry) {
         entry.forEach(instanceId => {
-          const json = { f: '__delete__', a: [instanceId], r: null }
+          const json = {
+            f: '__delete__',
+            a: [instanceId],
+            r: null,
+            s: VrpcAdapter.LOCAL_SENDER
+          }
           VrpcAdapter._call(json)
           if (json.r) {
             this._log.debug(`Auto-deleted isolated instance: ${instanceId}`)
@@ -718,7 +735,7 @@ class VrpcAgent extends EventEmitter {
     const entryIsolated = this._isolatedInstances.get(clientId)
     if (entryIsolated && entryIsolated.has(instanceId)) {
       entryIsolated.delete(instanceId)
-      if (entryIsolated.length === 0) {
+      if (entryIsolated.size === 0) {
         this._isolatedInstances.delete(clientId)
         this._mqttUnsubscribe(`${clientId}/__clientInfo__`)
         this._log.debug(`Stopped tracking lifetime of client: ${clientId}`)
@@ -730,7 +747,7 @@ class VrpcAgent extends EventEmitter {
       if (v.has(instanceId)) {
         found = true
         v.delete(instanceId)
-        if (v.length === 0) {
+        if (v.size === 0) {
           this._sharedInstances.delete(clientId)
           this._mqttUnsubscribe(`${clientId}/__clientInfo__`)
           this._log.debug(`Stopped tracking lifetime of client: ${clientId}`)

package/vrpc/VrpcBrowserAdapter.js

@@ -9,12 +9,10 @@ __\/\\\_______\/\\\__/\\\///////\\\___\/\\\/////////\\\____/\\\////////__
       _______\//\\\_______\/\\\______\//\\\_\/\\\_______________\////\\\\\\\\\_
        ________\///________\///________\///__\///___________________\/////////__
 
-
 Non-intrusively adapts code and provides access in form of asynchronous remote
 procedure calls (RPC).
 Author: Dr. Burkhard C. Heisen (https://github.com/heisenware/vrpc)
 
-
 Licensed under the MIT License <http://opensource.org/licenses/MIT>.
 Copyright (c) 2018 - 2022 Dr. Burkhard C. Heisen <burkhard.heisen@heisenware.com>.
 
@@ -319,16 +317,45 @@ class VrpcAdapter {
     return VrpcAdapter._mustTrackClient
   }
 
+  /**
+   * Refuses a request on an isolated instance that belongs to another
+   * connection. An isolated instance created over the wire remembers the
+   * connection that created it (the request's sender) and answers that
+   * connection alone; one the agent created itself has no owner and is
+   * open. The agent's own housekeeping passes as VrpcAdapter.LOCAL_SENDER,
+   * which no wire message can carry.
+   */
+  static _assertOwner (entry, json, instanceId) {
+    if (!entry || !entry.isIsolated || entry.owner === undefined) return
+    if (json.s === VrpcAdapter.LOCAL_SENDER || json.s === entry.owner) return
+    throw new Error(
+      `Instance '${instanceId}' is isolated to another connection`
+    )
+  }
+
   static _handleCreateIsolated (json) {
     let instance
     try {
       const className = json.c
       const [instanceId, ...args] = json.a
+      const existing = VrpcAdapter._instances.get(instanceId)
+      if (existing) {
+        // an id is never re-homed: a shared instance stays shared, an
+        // isolated one keeps its owner
+        if (!existing.isIsolated) {
+          throw new Error(`Instance '${instanceId}' exists as a shared instance`)
+        }
+        VrpcAdapter._assertOwner(existing, json, instanceId)
+        json.r = instanceId
+        return existing.instance
+      }
       instance = VrpcAdapter._create(className, instanceId, ...args)
       VrpcAdapter._instances.set(instanceId, {
         instance,
         className,
-        isIsolated: true
+        isIsolated: true,
+        // undefined for instances the agent creates itself (open)
+        owner: typeof json.s === 'string' ? json.s : undefined
       })
       VrpcAdapter._emitter.emit('create', {
         args,
@@ -348,6 +375,10 @@ class VrpcAdapter {
     try {
       const className = json.c
       const [instanceId, ...args] = json.a
+      const existing = VrpcAdapter._instances.get(instanceId)
+      if (existing && existing.isIsolated) {
+        throw new Error(`Instance '${instanceId}' exists as an isolated instance`)
+      }
       instance = VrpcAdapter._create(className, instanceId, ...args)
       VrpcAdapter._instances.set(instanceId, {
         instance,
@@ -421,6 +452,7 @@ class VrpcAdapter {
   static _handleDelete (json) {
     try {
       const instance = json.a[0] // first arg is instance to be deleted
+      VrpcAdapter._assertOwner(VrpcAdapter._instances.get(instance), json, instance)
       VrpcAdapter._emitter.emit('beforeDelete', {
         instance,
         className: json.c
@@ -436,6 +468,14 @@ class VrpcAdapter {
   }
 
   static _handleCall (json) {
+    // an isolated instance answers its creating connection only
+    try {
+      VrpcAdapter._assertOwner(VrpcAdapter._instances.get(json.c), json, json.c)
+    } catch (err) {
+      const { message, cause } = err
+      json.e = { message, cause }
+      return
+    }
     // special case: removeAllListeners
     if (json.f === 'removeAllListeners') {
       VrpcAdapter._removeAllListeners(json.a[0], json.s, json.c)
@@ -877,4 +917,11 @@ VrpcAdapter._blackList = new Set([
   '__lookupSetter__'
 ])
 
+/**
+ * The sender the agent uses for its own housekeeping calls (deleting the
+ * isolated instances of a departed connection). A Symbol: no message from
+ * the wire can carry it, so it can never be claimed remotely.
+ */
+VrpcAdapter.LOCAL_SENDER = Symbol('vrpc.local-sender')
+
 module.exports = VrpcAdapter

package/vrpc/VrpcBrowserAgent.js

@@ -504,7 +504,12 @@ class VrpcAgent extends EventEmitter {
       const entry = this._isolatedInstances.get(connectionId)
       if (entry) {
         entry.forEach(instanceId => {
-          const json = { f: '__delete__', a: [instanceId], r: null }
+          const json = {
+            f: '__delete__',
+            a: [instanceId],
+            r: null,
+            s: VrpcAdapter.LOCAL_SENDER
+          }
           VrpcAdapter._call(json)
           if (json.r) {
             this._log.debug(`Auto-deleted isolated instance: ${instanceId}`)
@@ -559,7 +564,7 @@ class VrpcAgent extends EventEmitter {
     const entryIsolated = this._isolatedInstances.get(clientId)
     if (entryIsolated && entryIsolated.has(instanceId)) {
       entryIsolated.delete(instanceId)
-      if (entryIsolated.length === 0) {
+      if (entryIsolated.size === 0) {
         this._isolatedInstances.delete(clientId)
         this._mqttUnsubscribe(`${clientId}/__clientInfo__`)
         this._log.debug(`Stopped tracking lifetime of client: ${clientId}`)
@@ -571,7 +576,7 @@ class VrpcAgent extends EventEmitter {
       if (v.has(instanceId)) {
         found = true
         v.delete(instanceId)
-        if (v.length === 0) {
+        if (v.size === 0) {
           this._sharedInstances.delete(clientId)
           this._mqttUnsubscribe(`${clientId}/__clientInfo__`)
           this._log.debug(`Stopped tracking lifetime of client: ${clientId}`)

package/vrpc/VrpcClient.js

@@ -9,12 +9,10 @@ __\/\\\_______\/\\\__/\\\///////\\\___\/\\\/////////\\\____/\\\////////__
       _______\//\\\_______\/\\\______\//\\\_\/\\\_______________\////\\\\\\\\\_
        ________\///________\///________\///__\///___________________\/////////__
 
-
 Non-intrusively adapts code and provides access in form of asynchronous remote
 procedure calls (RPC).
 Author: Dr. Burkhard C. Heisen (https://github.com/heisenware/vrpc)
 
-
 Licensed under the MIT License <http://opensource.org/licenses/MIT>.
 Copyright (c) 2018 - 2022 Dr. Burkhard C. Heisen <burkhard.heisen@heisenware.com>.
 
@@ -113,6 +111,18 @@ class VrpcClient extends EventEmitter {
         'The identity must NOT contain any of those characters: "+", "/", "#", "$"'
       )
     }
+    // mqtt client id sanity check: it becomes the second segment of every
+    // topic this client receives on, so it must be one plain segment
+    if (mqttClientId !== null && mqttClientId !== undefined) {
+      if (typeof mqttClientId !== 'string' || mqttClientId.length === 0) {
+        throw new Error('The mqttClientId must be a non-empty string')
+      }
+      if (mqttClientId.match(/[+/#]/)) {
+        throw new Error(
+          'The mqttClientId must NOT contain any of those characters: "+", "/", "#"'
+        )
+      }
+    }
     this._token = token
     this._username = username
     this._password = password
@@ -128,6 +138,11 @@ class VrpcClient extends EventEmitter {
     this._instance = nanoid(8)
     this._mqttClientId = mqttClientId || this._createMqttClientId()
     this._vrpcClientId = this._createVrpcClientId()
+    // the part of the connection id nobody else can learn: a broker that
+    // confines a client to topics under its own mqtt client id keeps
+    // every response, event and presence message of this connection
+    // private, and a sender field nobody can read cannot be forged
+    this._connectionSecret = nanoid(16)
     this._vrpcConnectionId = this._createVrpcConnectionId()
     this._agents = {}
     this._eventEmitter = new EventEmitter()
@@ -175,7 +190,12 @@ class VrpcClient extends EventEmitter {
    * 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.
+   *
+   * It reads `<domain>/<mqttClientId>/<secret>`: the mqtt client id is
+   * what the broker knows this connection by, so a broker can confine the
+   * client to its own topics, and the secret is random per connection, so
+   * nobody who cannot read those topics can impersonate the connection
+   * towards an agent. Treat it as a credential: do not log or share it.
    *
    * @returns {String} connectionId
    */
@@ -866,11 +886,10 @@ class VrpcClient extends EventEmitter {
   }
 
   _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}`
+    // Three segments, always: agents (this one, the C++ and the Python
+    // ports) recognise a presence message by `__clientInfo__` arriving as
+    // the fourth topic token, so the layout is part of the wire format.
+    return `${this._domain}/${this._mqttClientId}/${this._connectionSecret}`
   }
 
   _mqttPublish (topic, message, options) {
@@ -994,7 +1013,11 @@ class VrpcClient extends EventEmitter {
       this._eventEmitter.once(i, ({ e, r }) => {
         clearTimeout(timer)
         if (e) {
-          reject(new Error(e))
+          // the agent answers a throwing constructor with { message, cause }
+          const { message, cause } = VrpcClient._prepareError(e)
+          reject(
+            new Error(`[vrpc ${agent}-${className}-${f}]: ${message}`, { cause })
+          )
         } else {
           const proxy = this._createProxy(agent, className, r)
           resolve(proxy)
@@ -1225,15 +1248,15 @@ class VrpcClient extends EventEmitter {
     return new Promise((resolve, reject) => {
       const handler =
         timer =>
-        (instances, { agent, className }) => {
-          if (instances.includes(instance)) {
-            if (options.agent && agent !== options.agent) return
-            if (options.className && className !== options.className) return
-            clearTimeout(timer)
-            this.removeListener('instanceNew', handler)
-            resolve({ agent, className, instance })
+          (instances, { agent, className }) => {
+            if (instances.includes(instance)) {
+              if (options.agent && agent !== options.agent) return
+              if (options.className && className !== options.className) return
+              clearTimeout(timer)
+              this.removeListener('instanceNew', handler)
+              resolve({ agent, className, instance })
+            }
           }
-        }
       const timer = setTimeout(() => {
         this.removeListener('instanceNew', handler(timer))
         const msg = `Could not find instance: ${instance} (> ${this._timeout} ms)`
@@ -1454,8 +1477,8 @@ class VrpcClient extends EventEmitter {
     return (
       variable &&
       typeof variable === 'object' &&
-      variable.hasOwnProperty('emitter') &&
-      variable.hasOwnProperty('event') &&
+      Object.prototype.hasOwnProperty.call(variable, 'emitter') &&
+      Object.prototype.hasOwnProperty.call(variable, 'event') &&
       typeof variable.emitter === 'object' &&
       typeof variable.emitter.emit === 'function'
     )