vrpc 3.0.0-alpha.3 → 3.0.0

package/vrpc/VrpcClient.js

@@ -16,7 +16,7 @@ Author: Dr. Burkhard C. Heisen (https://github.com/heisenware/vrpc)
 
 
 Licensed under the MIT License <http://opensource.org/licenses/MIT>.
-Copyright (c) 2018 - 2021 Dr. Burkhard C. Heisen <burkhard.heisen@heisenware.com>.
+Copyright (c) 2018 - 2022 Dr. Burkhard C. Heisen <burkhard.heisen@heisenware.com>.
 
 Permission is hereby  granted, free of charge, to any  person obtaining a copy
 of this software and associated  documentation files (the "Software"), to deal
@@ -116,7 +116,7 @@ class VrpcClient extends EventEmitter {
     this._invokeId = 0
     this._proxyId = 0
     this._client = null
-    this._cachedSubscriptions = new Map()
+    this._cachedSubscriptions = {}
     this._proxies = {}
     if (log === 'console') {
       this._log = console
@@ -162,6 +162,7 @@ class VrpcClient extends EventEmitter {
       keepalive: 30,
       clientId: this._mqttClientId,
       rejectUnauthorized: false,
+      connectTimeout: this._timeout,
       will: {
         topic: `${this._vrpcClientId}/__clientInfo__`,
         payload: JSON.stringify({ status: 'offline' })
@@ -229,10 +230,12 @@ class VrpcClient extends EventEmitter {
           staticFunctions,
           meta
         } = json
-        if (removed.length !== 0)
+        if (removed.length !== 0) {
           this.emit('instanceGone', removed, { domain, agent, className })
-        if (added.length !== 0)
+        }
+        if (added.length !== 0) {
           this.emit('instanceNew', added, { domain, agent, className })
+        }
         this.emit('class', {
           domain,
           agent,
@@ -248,31 +251,29 @@ class VrpcClient extends EventEmitter {
         this._eventEmitter.emit(i, { a, e, r })
       }
     })
-    await new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
+    return new Promise((resolve, reject) => {
+      this._client.once('offline', () => {
+        this._client.end()
         reject(new Error(`Connection trial timed out (> ${this._timeout} ms)`))
-      }, this._timeout)
-      this.once('connect', () => {
-        clearTimeout(timer)
-        resolve()
       })
+      this._client.once('connect', resolve)
     })
   }
 
   /**
    * Creates a new remote instance and provides a proxy to it.
    *
-   * Remote instances can be "named" or "anonymous". Named instances are
-   * shareable and re-attachable across clients as long as they are not
-   * explicitly deleted. Life-cycle changes of named instances are available
-   * under the `class`, `instanceNew`, and `instanceGone` events. A named
-   * instance is created when specifying the `instance` option.
+   * Remote instances can be "shared" or "isolated". Shared instances are
+   * visible and re-attachable across clients as long as they are not
+   * explicitly deleted. Life-cycle changes of shared instances are available
+   * under the `class`, `instanceNew`, and `instanceGone` events. A shared
+   * instance is created by default (`isIsolated: false`).
    *
-   * When the `instance` option is not provided, the created proxy is the only
-   * object capable of issuing remote function calls. The remote instance stays
-   * invisible to other clients.
+   * When the `isIsolated` option is true, the remote instance stays invisible
+   * to other clients and the corresponding proxy object is the only way to
+   * issue commands.
    *
-   * **NOTE** When creating a named instance that already exists, the new proxy will
+   * **NOTE** When creating an instance that already exists, the new proxy will
    * simply attach to (and not re-create) it - just like `getInstance()` was
    * called.
    *
@@ -280,28 +281,32 @@ class VrpcClient extends EventEmitter {
    * @param {String} options.className Name of the class which should be
    * instantiated
    * @param {String} [options.instance] Name of the created instance. If not
-   * provided an (invisible) id will be generated
+   * provided an id will be generated
    * @param {Array} [options.args] Positional arguments for the constructor call
    * @param {String} [options.agent] Agent name. If not provided class default
    * is used
-   * @param {bool} [options.cacheProxy=false] If true the proxy object for a given
-   * instance is cached and used in subsequent calls
-   * @returns {Promise<Proxy>} Object reflecting a proxy to the original one
-   * handled by the agent
+   * @param {bool} [options.cacheProxy=false] If true the proxy object for a
+   * given instance is cached and (re-)used in subsequent calls
+   * @param {bool} [options.isIsolated=false] If true the created proxy will be
+   * visible only to the client who created it
+   * @returns {Promise<Proxy>} Object reflecting a proxy to the original object
+   * which is handled by the agent
    * @example
-   * // create anonymous instance
+   * // create isolated instance
    * const proxy1 = await client.create({
-   *   className: 'Foo'
+   *   className: 'Foo',
+   *   instance: 'myPersonalInstance',
+   *   isIsolated: true
    * })
-   * // create named instance
+   * // create shared instance
    * const proxy2 = await client.create({
    *   className: 'Foo',
-   *   instance: 'myFooInstance'
+   *   instance: 'aSharedFooInstance'
    * })
-   * // create named instance providing three constructor arguments
+   * // create shared instance providing three constructor arguments
    * const proxy3 = await client.create({
    *   className: 'Bar',
-   *   instance: 'myBarInstance',
+   *   instance: 'mySharedBarInstance',
    *   args: [42, "second argument", { some: 'option' }]
    * })
    */
@@ -317,9 +322,9 @@ class VrpcClient extends EventEmitter {
     const json = {
       c: className,
       f: isIsolated ? '__createIsolated__' : '__createShared__',
+      a: [instance, ...args],
       i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
       s: `${this._domain}/${os.hostname()}/${this._instance}`,
-      a: [instance, ...args],
       v: VRPC_PROTOCOL_VERSION
     }
     const proxy = await this._getProxy(agent, className, json)
@@ -364,15 +369,15 @@ class VrpcClient extends EventEmitter {
     const json = {
       c: className,
       f: '__delete__',
+      a: [instance],
       i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
       s: `${this._domain}/${os.hostname()}/${this._instance}`,
-      a: [instance],
       v: VRPC_PROTOCOL_VERSION
     }
     const topic = `${this._domain}/${agent}/${className}/__static__/__delete__`
     this._mqttPublish(topic, JSON.stringify(json))
     if (this._proxies[instance]) delete this._proxies[instance]
-    return this._handleAgentAnswer(json)
+    return this._handleAgentAnswer(json, agent)
   }
 
   /**
@@ -391,20 +396,25 @@ class VrpcClient extends EventEmitter {
     args = [],
     agent = this._agent
   } = {}) {
-    const wrapped = this._wrapArguments(className, functionName, ...args)
+    const wrapped = this._wrapArguments({
+      agent,
+      className,
+      functionName,
+      args
+    })
     if (!wrapped) return // Skipping remote call -> handled locally
     const json = {
       c: className,
       f: functionName,
+      a: wrapped,
       i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
       s: this._vrpcClientId,
-      a: wrapped,
       v: VRPC_PROTOCOL_VERSION
     }
     const topic = `${this._domain}/${agent}/${className}/__static__/${functionName}`
     await this._waitUntilClassIsOnline(agent, className)
     this._mqttPublish(topic, JSON.stringify(json))
-    return this._handleAgentAnswer(json)
+    return this._handleAgentAnswer(json, agent)
   }
 
   /**
@@ -436,41 +446,43 @@ class VrpcClient extends EventEmitter {
     const json = {
       c: className,
       f: functionName,
+      a: [],
       i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
       s: this._vrpcClientId,
-      a: [],
       v: VRPC_PROTOCOL_VERSION
     }
     if (agent === '*') {
       const result = []
       const agents = this.getAvailableAgents()
-      for (const x of agents) {
-        const topic = `${this._domain}/${x}/${className}/__static__/__callAll__`
-        const wrapped = this._wrapArguments(
-          `${x}-${className}`,
+      for (const agent of agents) {
+        const topic = `${this._domain}/${agent}/${className}/__static__/__callAll__`
+        const wrapped = this._wrapArguments({
+          agent,
+          className,
           functionName,
-          ...args
-        )
+          args
+        })
         if (!wrapped) continue // using cache
         json.a = [functionName, ...wrapped]
-        await this._waitUntilClassIsOnline(x, className)
+        await this._waitUntilClassIsOnline(agent, className)
         this._mqttPublish(topic, JSON.stringify(json))
-        const tmp = await this._handleAgentAnswer(json)
+        const tmp = await this._handleAgentAnswer(json, agent)
         result.push(...tmp)
       }
       return result
     }
     const topic = `${this._domain}/${agent}/${className}/__static__/__callAll__`
-    const wrapped = this._wrapArguments(
-      `${agent}-${className}`,
+    const wrapped = this._wrapArguments({
+      agent,
+      className,
       functionName,
-      ...args
-    )
+      args
+    })
     if (!wrapped) return // using cache
     json.a = [functionName, ...wrapped]
     await this._waitUntilClassIsOnline(agent, className)
     this._mqttPublish(topic, JSON.stringify(json))
-    return this._handleAgentAnswer(json)
+    return this._handleAgentAnswer(json, agent)
   }
 
   /**
@@ -530,7 +542,7 @@ class VrpcClient extends EventEmitter {
   }
 
   /**
-   * Retrieves all (named) instances on specific class and agent.
+   * Retrieves all (shared) instances on specific class and agent.
    *
    * @param {Object} [options]
    * @param {String} options.className Class name
@@ -664,7 +676,7 @@ class VrpcClient extends EventEmitter {
       .createHash('md5')
       .update(clientInfo)
       .digest('hex')
-      .substr(0, 12)
+      .substring(0, 12)
     return `vc3${this._instance}${md5}` // 3 + 8 + 12 = 23 (max clientId)
   }
 
@@ -793,35 +805,120 @@ class VrpcClient extends EventEmitter {
     // Remove overloads
     const uniqueFuncs = new Set(functions)
     // Build proxy
-    uniqueFuncs.forEach(name => {
-      proxy[name] = async (...args) => {
-        const wrapped = this._wrapArguments(proxyId, name, ...args)
-        if (!wrapped) return // Skipping remote call -> handled locally
+    uniqueFuncs.forEach(functionName => {
+      // as we are messing with Node.js' event system we have to intercept here
+      if (functionName === 'removeAllListeners') {
+        proxy[functionName] = async eventName => {
+          if (!eventName) {
+            throw new Error('VRPC does not support removing all listeners')
+          }
+          const topic = `${this._domain}/${agent}/${className}/${instance}:${eventName}`
+          const id = `__e__${topic}`
+          if (this._cachedSubscriptions[topic]) {
+            this._eventEmitter.removeAllListeners(id)
+            this._mqttUnsubscribe(topic)
+            delete this._cachedSubscriptions[topic]
+          }
+          try {
+            const json = {
+              c: instance,
+              f: functionName,
+              a: [eventName],
+              i: `${this._instance}-${this._invokeId++ %
+                Number.MAX_SAFE_INTEGER}`,
+              s: this._vrpcClientId,
+              v: VRPC_PROTOCOL_VERSION
+            }
+            this._mqttPublish(
+              `${targetTopic}/${functionName}`,
+              JSON.stringify(json)
+            )
+            return this._handleAgentAnswer(json, agent)
+          } catch (err) {
+            throw new Error(
+              `Could not remotely call "${functionName}" because: ${err.message}`
+            )
+          }
+        }
+        return
+      }
+      proxy[functionName] = async (...args) => {
+        const wrapped = this._wrapArguments({
+          agent,
+          className,
+          instance,
+          proxyId,
+          functionName,
+          args
+        })
+        if (!wrapped) return true // Skipping remote call -> handled locally
         try {
           const json = {
             c: instance,
-            f: name,
+            f: functionName,
+            a: wrapped,
             i: `${this._instance}-${this._invokeId++ %
               Number.MAX_SAFE_INTEGER}`,
             s: this._vrpcClientId,
-            a: wrapped,
             v: VRPC_PROTOCOL_VERSION
           }
-          this._mqttPublish(`${targetTopic}/${name}`, JSON.stringify(json))
-          return this._handleAgentAnswer(json)
+          this._mqttPublish(
+            `${targetTopic}/${functionName}`,
+            JSON.stringify(json)
+          )
+          return this._handleAgentAnswer(json, agent)
         } catch (err) {
           throw new Error(
-            `Could not remotely call "${name}" because: ${err.message}`
+            `Could not remotely call "${functionName}" because: ${err.message}`
           )
         }
       }
     })
+    if (!uniqueFuncs.has('vrpcOn') && !uniqueFuncs.has('vrpcOff')) {
+      proxy.vrpcOn = async (functionName, ...args) => {
+        if (!uniqueFuncs.has(functionName)) throw new Error('Bad magic')
+        const wrapped = this._wrapArguments({
+          agent,
+          className,
+          instance,
+          proxyId,
+          functionName: 'vrpcOn',
+          args: [functionName, ...args]
+        })
+        if (!wrapped) return // Skipping remote call -> handled locally
+        try {
+          const json = {
+            c: instance,
+            f: functionName,
+            a: wrapped.slice(1), // first argument was remote function name
+            i: `${this._instance}-${this._invokeId++ %
+              Number.MAX_SAFE_INTEGER}`,
+            s: this._vrpcClientId,
+            v: VRPC_PROTOCOL_VERSION
+          }
+          this._mqttPublish(
+            `${targetTopic}/${functionName}`,
+            JSON.stringify(json)
+          )
+          return this._handleAgentAnswer(json, agent)
+        } catch (err) {
+          throw new Error(
+            `Could not remotely call "${functionName}" because: ${err.message}`
+          )
+        }
+      }
+      proxy.vrpcOff = functionName => {
+        const topic = `${this._domain}/${agent}/${className}/${instance}-${functionName}`
+        const id = `__e__${topic}`
+        this._eventEmitter.removeAllListeners(id)
+      }
+    }
     return proxy
   }
 
-  async _handleAgentAnswer ({ i, c, f }) {
+  async _handleAgentAnswer ({ i, c, f }, agent) {
     return new Promise((resolve, reject) => {
-      const msg = `Function call "${c}::${f}()" timed out (> ${this._timeout} ms)`
+      const msg = `Function call "${c}::${f}()" on agent "${agent}" timed out (> ${this._timeout} ms)`
       const timer = setTimeout(() => {
         this._eventEmitter.removeAllListeners(i)
         reject(new Error(msg))
@@ -829,13 +926,14 @@ class VrpcClient extends EventEmitter {
       this._eventEmitter.once(i, data => {
         clearTimeout(timer)
         if (data.e) {
-          reject(new Error(data.e))
+          reject(new Error(`[vrpc ${agent}-${c}-${f}]: ${data.e}`))
         } else {
           const ret = data.r
           // Handle functions returning a promise
-          if (typeof ret === 'string' && ret.substr(0, 5) === '__p__') {
+          if (typeof ret === 'string' && ret.substring(0, 5) === '__p__') {
             this._eventEmitter.once(ret, promiseData => {
-              if (promiseData.e) reject(new Error(promiseData.e))
+              // TODO improve error message here, like above
+              if (promiseData.e) reject(new Error(`[vrpc ${agent}-${c}-${f}]: ${promiseData.e}`))
               else resolve(promiseData.r)
             })
           } else {
@@ -866,79 +964,128 @@ class VrpcClient extends EventEmitter {
     })
   }
 
-  _wrapArguments (remoteId, functionName, ...args) {
+  _wrapArguments ({ agent, className, instance, proxyId, functionName, args }) {
     const wrapped = []
-    let isHandledLocally = false
-    args.forEach((x, i) => {
+    for (const [i, x] of args.entries()) {
       // Check whether provided argument is a function
       if (this._isFunction(x)) {
-        // Check special case of an event emitter registration
-        // We test three conditions:
-        // 1) functionName must be "on"
-        // 2) callback is second argument
-        // 3) first argument was string
-        if (functionName === 'on' && i === 1 && typeof args[0] === 'string') {
-          const id = this._addEventSubscription(remoteId, args[0], x)
-          if (!id) isHandledLocally = true
+        const callback = x
+        if (
+          functionName === 'vrpcOn' ||
+          (functionName === 'on' && i === 1 && typeof args[0] === 'string')
+        ) {
+          // special case of an (remote-)event emitter registration
+          // we test three conditions:
+          // 1) functionName must be "on"
+          // 2) callback is second argument
+          // 3) first argument was string
+          const event = args[0]
+          const id = this._onRemoteEvent({
+            agent,
+            className,
+            instance,
+            event,
+            callback
+          })
+          // indicate that no network call is required
+          if (id === null) return null
           wrapped.push(id)
+          continue
         } else if (
           (functionName === 'off' || functionName === 'removeListener') &&
           i === 1 &&
           typeof args[0] === 'string'
         ) {
-          const id = this._removeEventSubscription(remoteId, args[0], x)
-          if (!id) isHandledLocally = true
+          const event = args[0]
+          const id = this._offRemoteEvent({
+            agent,
+            className,
+            instance,
+            event,
+            callback
+          })
+          // indicate that no network call is required
+          if (id === null) return null
           wrapped.push(id)
-          // Regular function callback
+          continue
         } else {
+          // Regular function callback (can be static or member function)
+          const remoteId = proxyId || `${agent}-${className}`
           const id = `__f__${remoteId}-${functionName}-${i}-${this._invokeId++ %
             Number.MAX_SAFE_INTEGER}`
           wrapped.push(id)
-          this._eventEmitter.once(id, ({ a }) => {
-            x.apply(null, a) // This is the actual function call
-          })
+          this._eventEmitter.once(id, ({ a }) => x.apply(null, a))
+          continue
         }
-      } else if (this._isEmitter(x)) {
+      }
+      // special case of an EventEmitter provided as argument
+      if (this._isEmitter(x)) {
         const { emitter, event } = x
-        const id = `__f__${remoteId}-${functionName}-${i}-${event}`
-        wrapped.push(id)
-        this._eventEmitter.on(id, ({ a }) => {
-          emitter.emit(event, ...a)
+        const id = this._onRemoteEvent({
+          agent,
+          className,
+          instance,
+          event,
+          callback: (...args) => emitter.emit(event, ...args)
         })
-      } else {
-        wrapped.push(x)
+        // indicate that no network call is required
+        if (id === null) return null
+        wrapped.push(id)
+        continue
       }
-    })
-    if (isHandledLocally) return null
+      // default behavior is to not touch
+      wrapped.push(x)
+    }
     return wrapped
   }
 
-  _addEventSubscription (remoteId, event, callback) {
-    const id = `__f__${remoteId}-${event}`
-    if (this._cachedSubscriptions.has(id)) {
-      this._cachedSubscriptions.get(id).on(id, callback)
-      return
+  _onRemoteEvent ({ agent, className, instance, event, callback }) {
+    // the topic on which any remote event will be published to
+    const topic = instance
+      ? `${this._domain}/${agent}/${className}/${instance}:${event}`
+      : `${this._domain}/${agent}/${className}/${event}`
+    // prepare a special id for the agent to know that events should be
+    // published to the provided topic after the prefix
+    const id = `__e__${topic}`
+    // call our proxy callback when remote events were received
+    const handler = ({ a }) => callback.apply(null, a)
+    this._eventEmitter.on(id, handler)
+    if (!this._cachedSubscriptions[topic]) {
+      // when not yet subscribed to this topic do it now
+      this._mqttSubscribe(topic)
+      this._cachedSubscriptions[topic] = [{ callback, handler }]
+      return id
     }
-    const emitter = new EventEmitter()
-    emitter.on(id, callback)
-    this._cachedSubscriptions.set(id, emitter)
-    this._eventEmitter.on(id, ({ a }) => {
-      emitter.emit(id, ...a)
-    })
-    return id
+    // otherwise just add the new callback-handler pair
+    this._cachedSubscriptions[topic].push({ callback, handler })
+    // indicate that no network call is required
+    return null
   }
 
-  _removeEventSubscription (remoteId, event, callback) {
-    const id = `__f__${remoteId}-${event}`
-    if (this._cachedSubscriptions.has(id)) {
-      const emitter = this._cachedSubscriptions.get(id)
-      emitter.removeListener(id, callback)
-      if (emitter.listenerCount(id) === 0) {
-        this._cachedSubscriptions.delete(id)
-        this._eventEmitter.removeAllListeners(id)
+  _offRemoteEvent ({ agent, className, instance, event, callback }) {
+    const topic = instance
+      ? `${this._domain}/${agent}/${className}/${instance}:${event}`
+      : `${this._domain}/${agent}/${className}/${event}`
+    const id = `__e__${topic}`
+    if (this._cachedSubscriptions[topic]) {
+      const index = this._cachedSubscriptions[topic].findIndex(x => x.callback === callback)
+      if (index === -1) {
+        this._log.warn(`Failed removing event listener ${id}`)
+        return null
+      }
+      const [{ handler }] = this._cachedSubscriptions[topic].splice(index, 1)
+      this._eventEmitter.removeListener(id, handler)
+      if (this._cachedSubscriptions[topic].length === 0) {
+        this._mqttUnsubscribe(topic)
+        delete this._cachedSubscriptions[topic]
         return id
       }
+      // indicate that no network call is required
+      return null
+    } else {
+      this._log.warn(`Can not unsubscribe from non-existing event: ${event}`)
     }
+    return id
   }
 
   _stripSignature (method) {
@@ -1045,7 +1192,7 @@ class VrpcClient extends EventEmitter {
  * @param {String} info.domain - Domain name
  * @param {String} info.agent - Agent name
  * @param {String} info.className - Class name
- * @param {Array.<String>} info.instances - Array of named instances
+ * @param {Array.<String>} info.instances - Array of instances
  * @param {Array.<String>} info.memberFunctions - Array of member functions
  * @param {Array.<String>} info.staticFunctions - Array of static functions
  * @param {MetaData} info.meta - Object associating further information to functions

package/vrpc/VrpcNative.js

@@ -16,7 +16,7 @@ Author: Dr. Burkhard C. Heisen (https://github.com/heisenware/vrpc)
 
 
 Licensed under the MIT License <http://opensource.org/licenses/MIT>.
-Copyright (c) 2018 - 2021 Dr. Burkhard C. Heisen <burkhard.heisen@heisenware.com>.
+Copyright (c) 2018 - 2022 Dr. Burkhard C. Heisen <burkhard.heisen@heisenware.com>.
 
 Permission is hereby  granted, free of charge, to any  person obtaining a copy
 of this software and associated  documentation files (the "Software"), to deal
@@ -41,7 +41,7 @@ const EventEmitter = require('events')
 const { nanoid } = require('nanoid')
 
 /**
- * Client capable of creating proxy objects and locally calling
+ * Client capable of creating proxy classes and objects to locally call
  * functions as provided through native addons.
  */
 class VrpcNative {
@@ -64,6 +64,15 @@ class VrpcNative {
     })
   }
 
+  /**
+   * Provides a proxy class to an existing one in the native addon
+   *
+   * You can use the returned class in the usual way. Static function calls
+   * are forwarded to the native addon, as are any instantiations and member
+   * function calls.
+   * @param {String} className The name of the class
+   * @returns Proxy Class
+   */
   getClass (className) {
     if (!this.getAvailableClasses().includes(className)) {
       throw new Error(`Native addon does not provide class: ${className}`)
@@ -226,6 +235,11 @@ class VrpcNative {
     return Klass
   }
 
+  /**
+   * Deletes a proxy object and its underlying instance
+   * @param {Object} proxy A proxy object
+   * @returns True in case of success, false otherwise
+   */
   delete (proxy) {
     if (!typeof proxy === 'object' || !proxy.vrpcProxyId) {
       throw new Error('Provided argument seems not to be a VRPC proxy')
@@ -238,6 +252,15 @@ class VrpcNative {
     return JSON.parse(this._adapter.call(JSON.stringify(json))).r
   }
 
+  /**
+   * Secondary option to call a static function (when creation of a proxy class
+   * seems to be too much overhead)
+   *
+   * @param {String} className The class on which the static function should be called
+   * @param {String} functionName Name of the static function
+   * @param  {...any} args The function arguments
+   * @returns The output of the underlying static function
+   */
   callStatic (className, functionName, ...args) {
     if (functionName === 'vrpcOff') {
       const id = `__f__${className}-vrpcOn:${args[0]}`