vrpc 3.0.0-alpha.2 → 3.0.2

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
@@ -70,7 +70,7 @@ class VrpcClient extends EventEmitter {
    * @param {Boolean} [options.bestEffort=false] If true, message will be sent with best effort, i.e. no caching if offline
    * @example
    * const client = new VrpcClient({
-   *   domain: 'public.vrpc',
+   *   domain: 'vrpc',
    *   broker: 'mqtt://vrpc.io'
    * })
    */
@@ -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
@@ -152,7 +152,6 @@ class VrpcClient extends EventEmitter {
     let username = this._username
     let password = this._password
     if (this._token) {
-      username = '__token__'
       password = this._token
     }
     const options = {
@@ -162,6 +161,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 +229,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 +250,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 +280,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 +321,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)
@@ -336,37 +340,15 @@ class VrpcClient extends EventEmitter {
    *
    * @param {String} instance The instance to be retrieved
    * @param {Object} [options] Explicitly define agent and class
-   * @param {String} options.className Name of the instance's class
-   * @param {String} options.agent Agent name. If not provided class default is used
-   * @param {bool} options.noWait If true immediately fail if instance could not be found in local cache
+   * @param {String} [options.className] Name of the instance's class
+   * @param {String} [options.agent] Agent name. If not provided class default is used as priority hit
+   * @param {bool} [options.noWait=false] If true immediately fail if instance could not be found in local cache
    * @returns {Promise<Proxy>} Proxy object reflecting the remotely existing instance
    */
-  async getInstance (instance, options) {
+  async getInstance (instance, options = {}) {
     if (this._proxies[instance]) return this._proxies[instance]
-    if (typeof instance === 'string') {
-      const {
-        agent,
-        className,
-        instance: instanceString
-      } = await this._getInstanceData(instance, options)
-      return this._createProxy(agent, className, instanceString)
-    } else {
-      // deprecate this
-      this._indicateDeprecation(
-        'VrpcClient.getInstance(): ' +
-          'Using an object as single argument is deprecated, ' +
-          'use "getInstance(instance, options)" instead.'
-      )
-      const fakedOptions = { ...instance }
-      const fakedInstance = fakedOptions.instance
-      delete fakedOptions.instance
-      const {
-        agent,
-        className,
-        instance: instanceString
-      } = await this._getInstanceData(fakedInstance, fakedOptions)
-      return this._createProxy(agent, className, instanceString)
-    }
+    const { agent, className } = await this._getInstanceData(instance, options)
+    return this._createProxy(agent, className, instance)
   }
 
   /**
@@ -378,36 +360,23 @@ class VrpcClient extends EventEmitter {
    * @param {String} instance The instance to be deleted
    * @param {Object} [options] Explicitly define agent and class
    * @param {String} options.className Name of the instance's class
-   * @param {String} options.agent Agent name. If not provided class default is used
+   * @param {String} options.agent Agent name. If not provided class default is used as priority hit
    * @returns {Promise<Boolean>} true if successful, false otherwise
    */
-  async delete (instance, options) {
-    let instanceData = { agent: this._agent }
-    if (typeof instance === 'string') {
-      instanceData = await this._getInstanceData(instance)
-      if (options) instanceData = { ...options, ...instanceData }
-    } else {
-      // deprecate this
-      this._indicateDeprecation(
-        'VrpcClient.delete(): ' +
-          'Using an object as single argument is deprecated, ' +
-          'use "delete(instance, options)" instead.'
-      )
-      instanceData = { ...instanceData, ...instance }
-    }
-    const { agent, className, instance: instanceString } = instanceData
+  async delete (instance, options = {}) {
+    const { agent, className } = await this._getInstanceData(instance, options)
     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: [instanceString],
       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)
   }
 
   /**
@@ -426,20 +395,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)
   }
 
   /**
@@ -471,41 +445,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)
   }
 
   /**
@@ -535,19 +511,7 @@ class VrpcClient extends EventEmitter {
    * @param {Boolean} [options.mustBeOnline=true] Only retrieve currently online agents
    * @returns {Array} Array of agent names.
    */
-  getAvailableAgents (options = {}) {
-    /// DEPRECATION INFORMATION AND WORKAROUND - TO BE REMOVED IN 3.x
-    // `options = {}` was `domain = this._domain` before
-    if (typeof options === 'string') {
-      this._indicateDeprecation(
-        'VrpcClient.getAvailableAgents(): ' +
-          'Providing a domain here has no effect and will be an error in future.'
-      )
-      options = { mustBeOnline: true }
-    }
-    ///
-
-    const { mustBeOnline = true } = options
+  getAvailableAgents ({ mustBeOnline = true } = {}) {
     const agents = []
     if (mustBeOnline) {
       // loop agents
@@ -568,34 +532,7 @@ class VrpcClient extends EventEmitter {
    * @param {Boolean} [options.mustBeOnline=true] Only retrieve currently online classes
    * @returns {Array} Array of class names.
    */
-  getAvailableClasses (
-    options = { agent: this._agent, mustBeOnline: true },
-    domain
-  ) {
-    /// DEPRECATION INFORMATION AND WORKAROUND - TO BE REMOVED IN 3.x
-    let agent = this._agent
-    let mustBeOnline = true
-    // `options = {}` was `agent = this._agent` before
-    if (typeof options === 'string') {
-      this._indicateDeprecation(
-        'VrpcClient.getAvailableClasses(): ' +
-          'setting the agent as string argument is deprecated.`' +
-          'Use `{ agent: <myAgent> }` instead.'
-      )
-      agent = options
-    } else {
-      agent = options.agent
-      mustBeOnline = options.mustBeOnline
-    }
-    // was `domain = this._domain` before
-    if (domain) {
-      this._indicateDeprecation(
-        'VrpcClient.getAvailableClasses(): ' +
-          'Providing a domain here has no effect and will be an error in future.'
-      )
-    }
-    ///
-
+  getAvailableClasses ({ agent = this._agent, mustBeOnline = true } = {}) {
     if (agent === '*') throw new Error('Agent must be specified')
     if (!this._agents[agent]) return []
     const { classes, status } = this._agents[agent]
@@ -604,43 +541,19 @@ class VrpcClient extends EventEmitter {
   }
 
   /**
-   * Retrieves all (named) instances on specific class and agent.
+   * Retrieves all (shared) instances on specific class and agent.
    *
-   * @param {String} className Class name
    * @param {Object} [options]
+   * @param {String} options.className Class name
    * @param {String} [options.agent] Agent name. If not provided class default is used
    * @param {Boolean} [options.mustBeOnline=true] Only retrieve currently online classes
    * @returns {Array} Array of instance names
    */
-  getAvailableInstances (
+  getAvailableInstances ({
     className,
-    options = { agent: this._agent, mustBeOnline: true },
-    domain
-  ) {
-    /// DEPRECATION INFORMATION AND WORKAROUND - TO BE REMOVED IN 3.x
-    let agent = this._agent
-    let mustBeOnline = true
-    // `options = {}` was `agent = this._agent` before
-    if (typeof options === 'string') {
-      this._indicateDeprecation(
-        'VrpcClient.getAvailableInstances(): ' +
-          'Setting the agent as string argument is deprecated.`' +
-          'Use `{ agent: <myAgent> }` instead.'
-      )
-      agent = options
-    } else {
-      agent = options.agent
-      mustBeOnline = options.mustBeOnline
-    }
-    // was `domain = this._domain` before
-    if (domain) {
-      this._indicateDeprecation(
-        'VrpcClient.getAvailableInstances(): ' +
-          'Providing a domain here has no effect and will be an error in future.'
-      )
-    }
-    ///
-
+    agent = this._agent,
+    mustBeOnline = true
+  } = {}) {
     if (agent === '*') throw new Error('Agent must be specified')
     if (!this._agents[agent]) return []
     const { classes, status } = this._agents[agent]
@@ -651,41 +564,17 @@ class VrpcClient extends EventEmitter {
   /**
    * Retrieves all member functions of specific class and agent.
    *
-   * @param {String} className Class name
    * @param {Object} [options]
+   * @param {String} options.className Class name
    * @param {String} [options.agent] Agent name. If not provided class default is used
    * @param {Boolean} [options.mustBeOnline=true] Only retrieve currently online classes
    * @returns {Array} Array of member function names
    */
-  getAvailableMemberFunctions (
+  getAvailableMemberFunctions ({
     className,
-    options = { agent: this._agent, mustBeOnline: true },
-    domain
-  ) {
-    /// DEPRECATION INFORMATION AND WORKAROUND - TO BE REMOVED IN 3.x
-    let agent = this._agent
-    let mustBeOnline = true
-    // `options = {}` was `agent = this._agent` before
-    if (typeof options === 'string') {
-      this._indicateDeprecation(
-        'VrpcClient.getAvailableMemberFunctions(): ' +
-          'Setting the agent as string argument is deprecated.`' +
-          'Use `{ agent: <myAgent> }` instead.'
-      )
-      agent = options
-    } else {
-      agent = options.agent
-      mustBeOnline = options.mustBeOnline
-    }
-    // was `domain = this._domain` before
-    if (domain) {
-      this._indicateDeprecation(
-        'VrpcClient.getAvailableMemberFunctions(): ' +
-          'Providing a domain here has no effect and will be an error in future.'
-      )
-    }
-    ///
-
+    agent = this._agent,
+    mustBeOnline = true
+  } = {}) {
     if (agent === '*') throw new Error('Agent must be specified')
     if (!this._agents[agent]) return []
     const { classes, status } = this._agents[agent]
@@ -698,41 +587,17 @@ class VrpcClient extends EventEmitter {
   /**
    * Retrieves all static functions of specific class and agent.
    *
-   * @param {String} className Class name
    * @param {Object} [options]
+   * @param {String} options.className Class name
    * @param {String} [options.agent] Agent name. If not provided class default is used
    * @param {Boolean} [options.mustBeOnline=true] Only retrieve currently online classes
    * @returns {Array} Array of static function names
    */
-  getAvailableStaticFunctions (
+  getAvailableStaticFunctions ({
     className,
-    options = { agent: this._agent, mustBeOnline: true },
-    domain
-  ) {
-    /// DEPRECATION INFORMATION AND WORKAROUND - TO BE REMOVED IN 3.x
-    let agent = this._agent
-    let mustBeOnline = true
-    // `options = {}` was `agent = this._agent` before
-    if (typeof options === 'string') {
-      this._indicateDeprecation(
-        'VrpcClient.getAvailableStaticFunctions(): ' +
-          'Setting the agent as string argument is deprecated.`' +
-          'Use `{ agent: <myAgent> }` instead.'
-      )
-      agent = options
-    } else {
-      agent = options.agent
-      mustBeOnline = options.mustBeOnline
-    }
-    // was `domain = this._domain` before
-    if (domain) {
-      this._indicateDeprecation(
-        'VrpcClient.getAvailableStaticFunctions(): ' +
-          'Providing a domain here has no effect and will be an error in future.'
-      )
-    }
-    ///
-
+    agent = this._agent,
+    mustBeOnline = true
+  } = {}) {
     if (agent === '*') throw new Error('Agent must be specified')
     if (!this._agents[agent]) return []
     const { classes, status } = this._agents[agent]
@@ -810,7 +675,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)
   }
 
@@ -939,34 +804,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,
-            i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
-            s: this._vrpcClientId,
+            f: functionName,
             a: wrapped,
+            i: `${this._instance}-${this._invokeId++ %
+              Number.MAX_SAFE_INTEGER}`,
+            s: this._vrpcClientId,
             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))
@@ -974,13 +925,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 {
@@ -1011,79 +963,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) {
@@ -1111,7 +1112,7 @@ class VrpcClient extends EventEmitter {
     )
   }
 
-  async _getInstanceData (instance, options = {}) {
+  async _getInstanceData (instance, options) {
     const instanceData = this._getInstanceFromCache(instance, options)
     if (!instanceData) {
       if (options.noWait) {
@@ -1123,6 +1124,21 @@ class VrpcClient extends EventEmitter {
   }
 
   _getInstanceFromCache (instance, options = {}) {
+    // when no agent is specified, but an explicit class default exists give
+    // such instances priority in being found
+    if (!options.agent && this._agent !== '*') {
+      const { classes, status } = this._agents[this._agent]
+      if (!classes || status === 'offline') {
+        for (const className in classes) {
+          if (options.className && className !== options.className) continue
+          const { instances } = classes[className]
+          if (!instances) continue
+          if (instances.includes(instance)) {
+            return { agent, className, instance }
+          }
+        }
+      }
+    }
     // loop agents
     for (const agent in this._agents) {
       if (options.agent && agent !== options.agent) continue
@@ -1175,7 +1191,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