vrpc 2.6.0 → 3.0.0

package/vrpc/{VrpcRemote.js → VrpcClient.js}

@@ -10,13 +10,13 @@ __\/\\\_______\/\\\__/\\\///////\\\___\/\\\/////////\\\____/\\\////////__
        ________\///________\///________\///__\///___________________\/////////__
 
 
-Non-intrusively binds code and provides access in form of asynchronous remote
+Non-intrusively adapts code and provides access in form of asynchronous remote
 procedure calls (RPC).
-Author: Dr. Burkhard C. Heisen (https://github.com/bheisen/vrpc)
+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
@@ -39,16 +39,19 @@ SOFTWARE.
 
 const os = require('os')
 const crypto = require('crypto')
+const { nanoid } = require('nanoid')
 const mqtt = require('mqtt')
 const EventEmitter = require('events')
 
+const VRPC_PROTOCOL_VERSION = 3
+
 /**
  * Client capable of creating proxy objects and remotely calling
  * functions as provided through one or more (distributed) agents.
  *
  * @extends EventEmitter
  */
-class VrpcRemote extends EventEmitter {
+class VrpcClient extends EventEmitter {
   /**
    * Constructs a remote client, able to communicate with any distributed agents
    *
@@ -66,7 +69,7 @@ class VrpcRemote extends EventEmitter {
    * @param {Object} [options.log=console] Log object (must support debug, info, warn, and error level)
    * @param {Boolean} [options.bestEffort=false] If true, message will be sent with best effort, i.e. no caching if offline
    * @example
-   * const client = new VrpcRemote({
+   * const client = new VrpcClient({
    *   domain: 'public.vrpc',
    *   broker: 'mqtt://vrpc.io'
    * })
@@ -105,7 +108,7 @@ class VrpcRemote extends EventEmitter {
     this._timeout = timeout
     this._qos = this._qos = bestEffort ? 0 : 1
 
-    this._instance = crypto.randomBytes(2).toString('hex')
+    this._instance = nanoid(8)
     this._mqttClientId = this._createMqttClientId()
     this._vrpcClientId = this._createVrpcClientId()
     this._agents = {}
@@ -113,7 +116,7 @@ class VrpcRemote 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
@@ -123,6 +126,15 @@ class VrpcRemote extends EventEmitter {
     }
   }
 
+  /**
+   * Provides a unique id for this client instance
+   *
+   * @returns {String} clientId
+   */
+  getClientId () {
+    return this._vrpcClientId
+  }
+
   /**
    * Actually connects to the MQTT broker.
    *
@@ -150,6 +162,7 @@ class VrpcRemote extends EventEmitter {
       keepalive: 30,
       clientId: this._mqttClientId,
       rejectUnauthorized: false,
+      connectTimeout: this._timeout,
       will: {
         topic: `${this._vrpcClientId}/__clientInfo__`,
         payload: JSON.stringify({ status: 'offline' })
@@ -217,10 +230,12 @@ class VrpcRemote 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,
@@ -232,42 +247,33 @@ class VrpcRemote extends EventEmitter {
         })
         // RPC message
       } else {
-        const { id, data } = JSON.parse(message.toString())
-        this._eventEmitter.emit(id, data)
+        const { i, a, e, r } = JSON.parse(message.toString())
+        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)
     })
   }
 
-  async connected () {
-    this._indicateDeprecation(
-      'VrpcRemote.connected(): This API usage is deprecated, use `connect()` instead.'
-    )
-    return this.connect()
-  }
-
   /**
    * 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.
    *
@@ -275,50 +281,51 @@ class VrpcRemote 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' }]
    * })
    */
   async create ({
     className,
-    instance,
+    instance = nanoid(8),
     args = [],
     agent = this._agent,
-    cacheProxy = false
+    cacheProxy = false,
+    isIsolated = false
   } = {}) {
     if (agent === '*') throw new Error('Agent must be specified')
-    const data = instance ? { _1: instance } : {}
-    const offset = instance ? 2 : 1
-    args.forEach((value, index) => {
-      data[`_${index + offset}`] = value
-    })
     const json = {
-      context: className,
-      method: instance ? '__createNamed__' : '__create__',
-      id: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
-      sender: `${this._domain}/${os.hostname()}/${this._instance}`,
-      data
+      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}`,
+      v: VRPC_PROTOCOL_VERSION
     }
     const proxy = await this._getProxy(agent, className, json)
     if (instance && cacheProxy) this._proxies[instance] = proxy
@@ -334,37 +341,15 @@ class VrpcRemote 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(
-        'VrpcRemote.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)
   }
 
   /**
@@ -376,35 +361,23 @@ class VrpcRemote 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(
-        'VrpcRemote.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 = {
-      context: className,
-      method: '__delete__',
-      id: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
-      sender: `${this._domain}/${os.hostname()}/${this._instance}`,
-      data: { _1: instanceString }
+      c: className,
+      f: '__delete__',
+      a: [instance],
+      i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
+      s: `${this._domain}/${os.hostname()}/${this._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)
   }
 
   /**
@@ -423,19 +396,25 @@ class VrpcRemote 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 = {
-      context: className,
-      method: functionName,
-      id: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
-      sender: this._vrpcClientId,
-      data: VrpcRemote._argsArrayToObject(wrapped)
+      c: className,
+      f: functionName,
+      a: wrapped,
+      i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
+      s: this._vrpcClientId,
+      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)
   }
 
   /**
@@ -465,67 +444,45 @@ class VrpcRemote extends EventEmitter {
     agent = this._agent
   } = {}) {
     const json = {
-      context: className,
-      method: functionName,
-      id: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
-      sender: this._vrpcClientId
+      c: className,
+      f: functionName,
+      a: [],
+      i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
+      s: this._vrpcClientId,
+      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.data = VrpcRemote._argsArrayToObject([functionName, ...wrapped])
-        await this._waitUntilClassIsOnline(x, className)
+        json.a = [functionName, ...wrapped]
+        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.data = VrpcRemote._argsArrayToObject([functionName, ...wrapped])
+    json.a = [functionName, ...wrapped]
     await this._waitUntilClassIsOnline(agent, className)
     this._mqttPublish(topic, JSON.stringify(json))
-    return this._handleAgentAnswer(json)
-  }
-
-  /**
-   * Retrieves all agents, instances, classes, member and static
-   * functions potentially available for remote control.
-   * @deprecated
-   * @returns {Object} SystemInformation
-   * ```ts
-   * type SystemInformation = {
-   *   [domain].agents[agent].status: string, // 'offline' or 'online'
-   *   [domain].agents[agent].hostname: string,
-   *   [domain].agents[agent].version: string,
-   *   [domain].agents[agent].classes[className].instances: string[],
-   *   [domain].agents[agent].classes[className].memberFunctions: string[],
-   *   [domain].agents[agent].classes[className].staticFunctions: string[],
-   *   [domain].agents[agent].classes[className].meta?: MetaData
-   * }
-   * ```
-   */
-  getAvailabilities () {
-    this._indicateDeprecation(
-      'VrpcRemote.getAvailabilities(): ' +
-        'This function is deprecated and will be removed soon, ' +
-        'use `getSystemInformation()` instead.'
-    )
-    return { [this._domain]: { agents: this._agents } }
+    return this._handleAgentAnswer(json, agent)
   }
 
   /**
@@ -548,21 +505,6 @@ class VrpcRemote extends EventEmitter {
     return this._agents
   }
 
-  /**
-   * Retrieves all domains on which agents can be remote controlled
-   *
-   * @deprecated
-   * @returns {Array} Array of domain names
-   */
-  getAvailableDomains () {
-    this._indicateDeprecation(
-      'VrpcRemote.getAvailableDomains(): ' +
-        'this function will be removed in the next major release, as the client' +
-        'works with a single domain anyways'
-    )
-    return [this._domain]
-  }
-
   /**
    * Retrieves all available agents.
    *
@@ -570,19 +512,7 @@ class VrpcRemote 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(
-        'VrpcRemote.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
@@ -603,34 +533,7 @@ class VrpcRemote 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(
-        'VrpcRemote.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(
-        'VrpcRemote.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]
@@ -639,43 +542,19 @@ class VrpcRemote 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(
-        'VrpcRemote.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(
-        'VrpcRemote.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]
@@ -686,41 +565,17 @@ class VrpcRemote 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(
-        'VrpcRemote.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(
-        'VrpcRemote.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]
@@ -733,41 +588,17 @@ class VrpcRemote 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(
-        'VrpcRemote.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(
-        'VrpcRemote.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]
@@ -824,7 +655,7 @@ class VrpcRemote extends EventEmitter {
   async end () {
     this._mqttPublish(
       `${this._vrpcClientId}/__clientInfo__`,
-      JSON.stringify({ status: 'offline' })
+      JSON.stringify({ status: 'offline', v: VRPC_PROTOCOL_VERSION })
     )
     return new Promise(resolve => this._client.end(false, {}, resolve))
   }
@@ -845,9 +676,8 @@ class VrpcRemote extends EventEmitter {
       .createHash('md5')
       .update(clientInfo)
       .digest('hex')
-      .substr(0, 13)
-    // FIXME (3.x): use vrpcp -> vrpcc
-    return `vrpcp${this._instance}X${md5}` // 5 + 4 + 1 + 13 = 23 (max clientId)
+      .substring(0, 12)
+    return `vc3${this._instance}${md5}` // 3 + 8 + 12 = 23 (max clientId)
   }
 
   _createVrpcClientId () {
@@ -904,22 +734,22 @@ class VrpcRemote extends EventEmitter {
   }
 
   async _getProxy (agent, className, json) {
-    const { method } = json
-    const topic = `${this._domain}/${agent}/${className}/__static__/${method}`
+    const { f, i } = json
+    const topic = `${this._domain}/${agent}/${className}/__static__/${f}`
     await this._waitUntilClassIsOnline(agent, className)
     this._mqttPublish(topic, JSON.stringify(json))
     return new Promise((resolve, reject) => {
       const msg = `Proxy creation for class "${className}" on agent "${agent}" and domain "${this._domain}" timed out (> ${this._timeout} ms)`
       const timer = setTimeout(() => {
-        this._eventEmitter.removeAllListeners(json.id)
+        this._eventEmitter.removeAllListeners(i)
         reject(new Error(msg))
       }, this._timeout)
-      this._eventEmitter.once(json.id, data => {
+      this._eventEmitter.once(i, ({ e, r }) => {
         clearTimeout(timer)
-        if (data.e) {
-          reject(new Error(data.e))
+        if (e) {
+          reject(new Error(e))
         } else {
-          const proxy = this._createProxy(agent, className, data.r)
+          const proxy = this._createProxy(agent, className, r)
           resolve(proxy)
         }
       })
@@ -961,8 +791,9 @@ class VrpcRemote extends EventEmitter {
     const targetTopic = `${this._domain}/${agent}/${className}/${instance}`
     const proxyId = `${this._instance}-${this._proxyId++}`
     const proxy = {
-      _targetId: instance,
-      _proxyId: proxyId
+      vrpcClientId: this._vrpcClientId,
+      vrpcInstanceId: instance,
+      vrpcProxyId: proxyId
     }
     let functions = this._agents[agent].classes[className].memberFunctions
     // Strip off argument signature
@@ -974,48 +805,135 @@ class VrpcRemote 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 = {
-            context: instance,
-            method: name,
-            id: `${this._instance}-${this._invokeId++ %
+            c: instance,
+            f: functionName,
+            a: wrapped,
+            i: `${this._instance}-${this._invokeId++ %
               Number.MAX_SAFE_INTEGER}`,
-            sender: this._vrpcClientId,
-            data: VrpcRemote._argsArrayToObject(wrapped)
+            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 ({ id, context, method }) {
+  async _handleAgentAnswer ({ i, c, f }, agent) {
     return new Promise((resolve, reject) => {
-      const msg = `Function call "${context}::${method}()" 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(id)
+        this._eventEmitter.removeAllListeners(i)
         reject(new Error(msg))
       }, this._timeout)
-      this._eventEmitter.once(id, data => {
+      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 {
@@ -1046,91 +964,128 @@ class VrpcRemote 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, data => {
-            const args = Object.keys(data)
-              .sort()
-              .filter(x => x[0] === '_')
-              .map(x => data[x])
-            x.apply(null, args) // 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, data => {
-          const args = Object.keys(data)
-            .sort()
-            .filter(x => x[0] === '_')
-            .map(x => data[x])
-          emitter.emit(event, ...args)
+        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, data => {
-      const args = Object.keys(data)
-        .sort()
-        .filter(x => x[0] === '_')
-        .map(x => data[x])
-      emitter.emit(id, ...args)
-    })
-    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) {
@@ -1158,7 +1113,7 @@ class VrpcRemote extends EventEmitter {
     )
   }
 
-  async _getInstanceData (instance, options = {}) {
+  async _getInstanceData (instance, options) {
     const instanceData = this._getInstanceFromCache(instance, options)
     if (!instanceData) {
       if (options.noWait) {
@@ -1170,6 +1125,21 @@ class VrpcRemote 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
@@ -1194,14 +1164,6 @@ class VrpcRemote extends EventEmitter {
       this._log.warn('DEPRECATED ', msg)
     }
   }
-
-  static _argsArrayToObject (args) {
-    const obj = {}
-    args.forEach((x, i) => {
-      obj[`_${i + 1}`] = x
-    })
-    return obj
-  }
 }
 
 /**
@@ -1210,7 +1172,7 @@ class VrpcRemote extends EventEmitter {
  * This event is fired whenever an agent is added or removed, or whenever
  * an agent changes its status (switches between online or offline).
  *
- * @event VrpcRemote#agent
+ * @event VrpcClient#agent
  * @param {Object} info
  * @param {String} info.domain - Domain name
  * @param {String} info.agent - Agent name
@@ -1225,12 +1187,12 @@ class VrpcRemote extends EventEmitter {
  * Emitted whenever a class is added or removed, or when instances
  * or functions of this class have changed.
  *
- * @event VrpcRemote#class
+ * @event VrpcClient#class
  * @param {Object} info
  * @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
@@ -1241,7 +1203,7 @@ class VrpcRemote extends EventEmitter {
  *
  * Emitted whenever a new instance was created.
  *
- * @event VrpcRemote#instanceNew
+ * @event VrpcClient#instanceNew
  *
  * @param {Array.<String>} addedInstances - An array of newly added instances
  * @param {Object} info
@@ -1255,7 +1217,7 @@ class VrpcRemote extends EventEmitter {
  *
  * Emitted whenever a new instance was removed.
  *
- * @event VrpcRemote#instanceGone
+ * @event VrpcClient#instanceGone
  *
  * @param {Array.<String>} removedInstances - An array of removed instances
  * @param {Object} info
@@ -1269,7 +1231,7 @@ class VrpcRemote extends EventEmitter {
  *
  * Emitted on successful (re)connection (i.e. connack rc=0).
  *
- * @event VrpcRemote#connect
+ * @event VrpcClient#connect
  * @type {Object}
  * @property {Boolean} sessionPresent - A session from a previous connection is already present
  */
@@ -1279,7 +1241,7 @@ class VrpcRemote extends EventEmitter {
  *
  * Emitted when a reconnect starts.
  *
- * @event VrpcRemote#reconnect
+ * @event VrpcClient#reconnect
  */
 
 /**
@@ -1287,7 +1249,7 @@ class VrpcRemote extends EventEmitter {
  *
  * Emitted after a disconnection.
  *
- * @event VrpcRemote#close
+ * @event VrpcClient#close
  */
 
 /**
@@ -1295,7 +1257,7 @@ class VrpcRemote extends EventEmitter {
  *
  * Emitted when the client goes offline.
  *
- * @event VrpcRemote#offline
+ * @event VrpcClient#offline
  */
 
 /**
@@ -1310,7 +1272,7 @@ class VrpcRemote extends EventEmitter {
  * - EADDRINUSE
  * - ENOTFOUND
  *
- * @event VrpcRemote#error
+ * @event VrpcClient#error
  * @type {Object} Error
  */
 
@@ -1320,7 +1282,7 @@ class VrpcRemote extends EventEmitter {
  * Emitted when mqtt.Client#end() is called. If a callback was passed to
  * mqtt.Client#end(), this event is emitted once the callback returns.
  *
- * @event VrpcRemote#end
+ * @event VrpcClient#end
  */
 
-module.exports = VrpcRemote
+module.exports = VrpcClient