vrpc 2.6.0 → 3.0.0-alpha.1

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

@@ -10,9 +10,9 @@ __\/\\\_______\/\\\__/\\\///////\\\___\/\\\/////////\\\____/\\\////////__
        ________\///________\///________\///__\///___________________\/////////__
 
 
-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>.
@@ -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 = {}
@@ -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.
    *
@@ -232,8 +244,8 @@ 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) => {
@@ -247,13 +259,6 @@ class VrpcRemote extends EventEmitter {
     })
   }
 
-  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.
    *
@@ -302,23 +307,20 @@ class VrpcRemote extends EventEmitter {
    */
   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__',
+      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)
     if (instance && cacheProxy) this._proxies[instance] = proxy
@@ -351,7 +353,7 @@ class VrpcRemote extends EventEmitter {
     } else {
       // deprecate this
       this._indicateDeprecation(
-        'VrpcRemote.getInstance(): ' +
+        'VrpcClient.getInstance(): ' +
           'Using an object as single argument is deprecated, ' +
           'use "getInstance(instance, options)" instead.'
       )
@@ -387,7 +389,7 @@ class VrpcRemote extends EventEmitter {
     } else {
       // deprecate this
       this._indicateDeprecation(
-        'VrpcRemote.delete(): ' +
+        'VrpcClient.delete(): ' +
           'Using an object as single argument is deprecated, ' +
           'use "delete(instance, options)" instead.'
       )
@@ -395,11 +397,12 @@ class VrpcRemote extends EventEmitter {
     }
     const { agent, className, instance: instanceString } = instanceData
     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__',
+      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))
@@ -426,11 +429,12 @@ class VrpcRemote extends EventEmitter {
     const wrapped = this._wrapArguments(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,
+      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)
@@ -465,10 +469,12 @@ 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,
+      i: `${this._instance}-${this._invokeId++ % Number.MAX_SAFE_INTEGER}`,
+      s: this._vrpcClientId,
+      a: [],
+      v: VRPC_PROTOCOL_VERSION
     }
     if (agent === '*') {
       const result = []
@@ -481,7 +487,7 @@ class VrpcRemote extends EventEmitter {
           ...args
         )
         if (!wrapped) continue // using cache
-        json.data = VrpcRemote._argsArrayToObject([functionName, ...wrapped])
+        json.a = [functionName, ...wrapped]
         await this._waitUntilClassIsOnline(x, className)
         this._mqttPublish(topic, JSON.stringify(json))
         const tmp = await this._handleAgentAnswer(json)
@@ -496,38 +502,12 @@ class VrpcRemote extends EventEmitter {
       ...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 } }
-  }
-
   /**
    * Retrieves all information about the currently available components.
    *
@@ -548,21 +528,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.
    *
@@ -575,7 +540,7 @@ class VrpcRemote extends EventEmitter {
     // `options = {}` was `domain = this._domain` before
     if (typeof options === 'string') {
       this._indicateDeprecation(
-        'VrpcRemote.getAvailableAgents(): ' +
+        'VrpcClient.getAvailableAgents(): ' +
           'Providing a domain here has no effect and will be an error in future.'
       )
       options = { mustBeOnline: true }
@@ -613,7 +578,7 @@ class VrpcRemote extends EventEmitter {
     // `options = {}` was `agent = this._agent` before
     if (typeof options === 'string') {
       this._indicateDeprecation(
-        'VrpcRemote.getAvailableClasses(): ' +
+        'VrpcClient.getAvailableClasses(): ' +
           'setting the agent as string argument is deprecated.`' +
           'Use `{ agent: <myAgent> }` instead.'
       )
@@ -625,7 +590,7 @@ class VrpcRemote extends EventEmitter {
     // was `domain = this._domain` before
     if (domain) {
       this._indicateDeprecation(
-        'VrpcRemote.getAvailableClasses(): ' +
+        'VrpcClient.getAvailableClasses(): ' +
           'Providing a domain here has no effect and will be an error in future.'
       )
     }
@@ -658,7 +623,7 @@ class VrpcRemote extends EventEmitter {
     // `options = {}` was `agent = this._agent` before
     if (typeof options === 'string') {
       this._indicateDeprecation(
-        'VrpcRemote.getAvailableInstances(): ' +
+        'VrpcClient.getAvailableInstances(): ' +
           'Setting the agent as string argument is deprecated.`' +
           'Use `{ agent: <myAgent> }` instead.'
       )
@@ -670,7 +635,7 @@ class VrpcRemote extends EventEmitter {
     // was `domain = this._domain` before
     if (domain) {
       this._indicateDeprecation(
-        'VrpcRemote.getAvailableInstances(): ' +
+        'VrpcClient.getAvailableInstances(): ' +
           'Providing a domain here has no effect and will be an error in future.'
       )
     }
@@ -703,7 +668,7 @@ class VrpcRemote extends EventEmitter {
     // `options = {}` was `agent = this._agent` before
     if (typeof options === 'string') {
       this._indicateDeprecation(
-        'VrpcRemote.getAvailableMemberFunctions(): ' +
+        'VrpcClient.getAvailableMemberFunctions(): ' +
           'Setting the agent as string argument is deprecated.`' +
           'Use `{ agent: <myAgent> }` instead.'
       )
@@ -715,7 +680,7 @@ class VrpcRemote extends EventEmitter {
     // was `domain = this._domain` before
     if (domain) {
       this._indicateDeprecation(
-        'VrpcRemote.getAvailableMemberFunctions(): ' +
+        'VrpcClient.getAvailableMemberFunctions(): ' +
           'Providing a domain here has no effect and will be an error in future.'
       )
     }
@@ -750,7 +715,7 @@ class VrpcRemote extends EventEmitter {
     // `options = {}` was `agent = this._agent` before
     if (typeof options === 'string') {
       this._indicateDeprecation(
-        'VrpcRemote.getAvailableStaticFunctions(): ' +
+        'VrpcClient.getAvailableStaticFunctions(): ' +
           'Setting the agent as string argument is deprecated.`' +
           'Use `{ agent: <myAgent> }` instead.'
       )
@@ -762,7 +727,7 @@ class VrpcRemote extends EventEmitter {
     // was `domain = this._domain` before
     if (domain) {
       this._indicateDeprecation(
-        'VrpcRemote.getAvailableStaticFunctions(): ' +
+        'VrpcClient.getAvailableStaticFunctions(): ' +
           'Providing a domain here has no effect and will be an error in future.'
       )
     }
@@ -824,7 +789,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))
   }
@@ -847,7 +812,7 @@ class VrpcRemote extends EventEmitter {
       .digest('hex')
       .substr(0, 13)
     // FIXME (3.x): use vrpcp -> vrpcc
-    return `vrpcp${this._instance}X${md5}` // 5 + 4 + 1 + 13 = 23 (max clientId)
+    return `vc${this._instance}${md5}` // 2 + 8 + 13 = 23 (max clientId)
   }
 
   _createVrpcClientId () {
@@ -904,22 +869,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 +926,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
@@ -980,12 +946,12 @@ class VrpcRemote extends EventEmitter {
         if (!wrapped) return // Skipping remote call -> handled locally
         try {
           const json = {
-            context: instance,
-            method: name,
-            id: `${this._instance}-${this._invokeId++ %
-              Number.MAX_SAFE_INTEGER}`,
-            sender: this._vrpcClientId,
-            data: VrpcRemote._argsArrayToObject(wrapped)
+            c: instance,
+            f: name,
+            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)
@@ -999,14 +965,14 @@ class VrpcRemote extends EventEmitter {
     return proxy
   }
 
-  async _handleAgentAnswer ({ id, context, method }) {
+  async _handleAgentAnswer ({ i, c, f }) {
     return new Promise((resolve, reject) => {
-      const msg = `Function call "${context}::${method}()" timed out (> ${this._timeout} ms)`
+      const msg = `Function call "${c}::${f}()" 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))
@@ -1074,24 +1040,16 @@ class VrpcRemote extends EventEmitter {
           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) // This is the actual function call
           })
         }
       } else 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)
+        this._eventEmitter.on(id, ({ a }) => {
+          emitter.emit(event, ...a)
         })
       } else {
         wrapped.push(x)
@@ -1110,12 +1068,8 @@ class VrpcRemote extends EventEmitter {
     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)
+    this._eventEmitter.on(id, ({ a }) => {
+      emitter.emit(id, ...a)
     })
     return id
   }
@@ -1194,14 +1148,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 +1156,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,7 +1171,7 @@ 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
@@ -1241,7 +1187,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 +1201,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 +1215,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 +1225,7 @@ class VrpcRemote extends EventEmitter {
  *
  * Emitted when a reconnect starts.
  *
- * @event VrpcRemote#reconnect
+ * @event VrpcClient#reconnect
  */
 
 /**
@@ -1287,7 +1233,7 @@ class VrpcRemote extends EventEmitter {
  *
  * Emitted after a disconnection.
  *
- * @event VrpcRemote#close
+ * @event VrpcClient#close
  */
 
 /**
@@ -1295,7 +1241,7 @@ class VrpcRemote extends EventEmitter {
  *
  * Emitted when the client goes offline.
  *
- * @event VrpcRemote#offline
+ * @event VrpcClient#offline
  */
 
 /**
@@ -1310,7 +1256,7 @@ class VrpcRemote extends EventEmitter {
  * - EADDRINUSE
  * - ENOTFOUND
  *
- * @event VrpcRemote#error
+ * @event VrpcClient#error
  * @type {Object} Error
  */
 
@@ -1320,7 +1266,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