vrpc 3.1.0 → 3.2.0

package/browser/vrpc.js.LICENSE.txt

@@ -10,3 +10,5 @@
 /*! ieee754. BSD-3-Clause License. Feross Aboukhadijeh <https://feross.org/opensource> */
 
 /*! safe-buffer. MIT License. Feross Aboukhadijeh <https://feross.org/opensource> */
+
+/** @license URI.js v4.4.1 (c) 2011 Gary Court. License: http://github.com/garycourt/uri-js */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vrpc",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Variadic Remote Procedure Calls",
   "main": "index.js",
   "directories": {
@@ -10,8 +10,8 @@
   },
   "scripts": {
     "build:addon": "ln -sf binding.gyp.no-auto binding.gyp && node-gyp rebuild && rm binding.gyp",
-    "build:browser": "./node_modules/.bin/webpack",
-    "build:doc": "./node_modules/.bin/jsdoc2md -f vrpc/*.js --param-list-format=list --separators > docs/api.md",
+    "build:browser": "./node_modules/.bin/webpack --stats-error-details",
+    "build:doc": "./node_modules/.bin/jsdoc2md -f vrpc/VrpcAdapter.js vrpc/VrpcAgent.js vrpc/VrpcClient.js vrpc/VrpcNative.js --param-list-format=list --separators > docs/api.md",
     "test": "npm run test:adapter && npm run test:native && npm run test:agent && npm run test:client && npm run test:production",
     "test:adapter": "./node_modules/.bin/mocha tests/adapter/*.js --exit",
     "test:native": "./node_modules/.bin/mocha tests/native/*.js --exit",
@@ -69,6 +69,7 @@
     "argparse": "^2.0.1",
     "buffer": "^6.0.3",
     "caller": "^1.0.1",
+    "json-stringify-safe": "^5.0.1",
     "mqtt": "^4.2.6",
     "nanoid": "^3.1.23",
     "process": "^0.11.10"

package/vrpc/VrpcAdapter.js

@@ -111,10 +111,8 @@ class VrpcAdapter {
       this._registerClass(Klass, absJsdocPath, options)
     } else {
       const { jsdocPath } = options
-      const sJsdocPath =
-        jsdocPath && jsdocPath.endsWith('.js') ? jsdocPath : `${jsdocPath}.js`
       if (jsdocPath) {
-        const absJsdocPath = path.resolve(caller(), '../', sJsdocPath)
+        const absJsdocPath = path.resolve(caller(), '../', jsdocPath)
         this._registerClass(code, absJsdocPath, { ...options, jsdoc: true })
       } else {
         this._registerClass(code, null, options)
@@ -146,7 +144,7 @@ class VrpcAdapter {
     }
     let meta = null
     if (jsdocPath) {
-      const absJsdocPath = path.resolve(caller(), '../', `${jsdocPath}.js`)
+      const absJsdocPath = path.resolve(caller(), '../', jsdocPath)
       const content = fs.readFileSync(absJsdocPath).toString('utf8')
       meta = this._parseComments(content)
     }
@@ -194,7 +192,10 @@ class VrpcAdapter {
     const obj = isIsolated
       ? VrpcAdapter._handleCreateIsolated(json)
       : VrpcAdapter._handleCreateShared(json)
-    if (json.e) throw new Error(json.e)
+    if (json.e) {
+      const { message, cause } = json.e
+      throw new Error(message, { cause })
+    }
     return obj
   }
 
@@ -350,9 +351,17 @@ class VrpcAdapter {
             ({ tag }) => tag === 'param' || tag === 'arg' || tag === 'argument'
           )
           if (params.length > 0) {
-            params = params.map(({ name, optional, description, type }) => {
-              return { name, optional, description, type }
-            })
+            params = params.map(
+              ({
+                name,
+                optional,
+                description,
+                type,
+                default: defaultValue
+              }) => {
+                return { name, optional, description, type, defaultValue }
+              }
+            )
           } else {
             params = []
           }
@@ -361,10 +370,7 @@ class VrpcAdapter {
           )
           if (ret.length === 1) {
             const { source, type } = ret[0]
-            const description = source
-              .split(' ')
-              .splice(2)
-              .join(' ')
+            const description = source.split(' ').splice(2).join(' ')
             ret = { description, type }
           } else {
             ret = null
@@ -375,7 +381,8 @@ class VrpcAdapter {
                 name: 'instanceName',
                 optional: false,
                 description: 'Name of the instance to be created',
-                type: 'string'
+                type: 'string',
+                defaultValue: undefined
               },
               ...params
             ]
@@ -432,7 +439,8 @@ class VrpcAdapter {
       })
       json.r = instanceId
     } catch (err) {
-      json.e = err.message
+      const { message, cause } = err
+      json.e = { message, cause }
     }
     return instance
   }
@@ -456,7 +464,8 @@ class VrpcAdapter {
         instance: instanceId
       })
     } catch (err) {
-      json.e = err.message
+      const { message, cause } = err
+      json.e = { message, cause }
     }
     return instance
   }
@@ -492,14 +501,21 @@ class VrpcAdapter {
           calls.push({ id, val: v, err: e })
         }
       }
-      this._handlePromise(json, Promise.all(calls))
+      this._handlePromise(
+        json,
+        Promise.allSettled(calls).then(result =>
+          result.filter(x => x.status === 'fulfilled').map(x => x.value)
+        )
+      )
     } catch (err) {
-      json.e = err.message
+      const { message, cause } = err
+      json.e = { message, cause }
     }
   }
 
   static sanitizeEventListenerReturnValues (ret) {
-    return ret && typeof ret === 'object' &&
+    return ret &&
+      typeof ret === 'object' &&
       ret._events !== undefined &&
       ret._eventsCount !== undefined
       ? true
@@ -509,13 +525,18 @@ class VrpcAdapter {
   static _handleDelete (json) {
     try {
       const instance = json.a[0] // first arg is instance to be deleted
+      VrpcAdapter._emitter.emit('beforeDelete', {
+        instance,
+        className: json.c
+      })
       json.r = VrpcAdapter._delete(instance)
       VrpcAdapter._emitter.emit('delete', {
         instance,
         className: json.c
       })
     } catch (err) {
-      json.e = err.message
+      const { message, cause } = err
+      json.e = { message, cause }
     }
   }
 
@@ -549,7 +570,8 @@ class VrpcAdapter {
             this._handlePromise(json, ret)
           } else json.r = ret
         } catch (err) {
-          json.e = err.message
+          const { message, cause } = err
+          json.e = { message, cause }
         }
       } else throw new Error(`Could not find function: ${json.f}`)
     } else {
@@ -568,7 +590,8 @@ class VrpcAdapter {
             this._handlePromise(json, ret)
           } else json.r = ret
         } catch (err) {
-          json.e = err.message
+          const { message, cause } = err
+          json.e = { message, cause }
         }
       } else throw new Error(`Could not find function: ${json.f}`)
     }
@@ -603,9 +626,10 @@ class VrpcAdapter {
     Object.entries(VrpcAdapter._listeners).forEach(([ik, iv]) => {
       Object.entries(iv).forEach(([ek, ev]) => {
         const { clients, listener, event } = ev
-        if (clients.has(clientId)) {
-          clients.delete(clientId)
-          if (clients.size === 0) {
+        const index = clients.indexOf(clientId)
+        if (index !== -1) {
+          clients.splice(index, 1)
+          if (clients.length === 0) {
             const instance = VrpcAdapter.getInstance(ik)
             if (instance && instance.removeListener) {
               instance.removeListener(event, listener)
@@ -657,11 +681,7 @@ class VrpcAdapter {
               eventId: arg,
               event: args[0]
             })
-            if (
-              VrpcAdapter.getInstance(context)
-                .listeners(arg)
-                .includes(listener)
-            ) {
+            if (!listener) {
               return null // skip call as listener is already registered
             }
             unwrapped.push(listener)
@@ -717,7 +737,7 @@ class VrpcAdapter {
       VrpcAdapter._listeners[instanceId] = {
         [eventId]: {
           event,
-          clients: new Set([clientId]),
+          clients: [clientId],
           listener: VrpcAdapter._generateListener({
             eventId,
             instanceId,
@@ -725,20 +745,22 @@ class VrpcAdapter {
           })
         }
       }
-    } else if (!VrpcAdapter._listeners[instanceId][eventId]) {
+      return VrpcAdapter._listeners[instanceId][eventId].listener
+    }
+    if (!VrpcAdapter._listeners[instanceId][eventId]) {
       VrpcAdapter._listeners[instanceId][eventId] = {
         event,
-        clients: new Set([clientId]),
+        clients: [clientId],
         listener: VrpcAdapter._generateListener({
           eventId,
           instanceId,
           isCallAll
         })
       }
-    } else {
-      VrpcAdapter._listeners[instanceId][eventId].clients.add(clientId)
+      return VrpcAdapter._listeners[instanceId][eventId].listener
     }
-    return VrpcAdapter._listeners[instanceId][eventId].listener
+    VrpcAdapter._listeners[instanceId][eventId].clients.push(clientId)
+    return null
   }
 
   static _generateListener ({ eventId, instanceId, isCallAll }) {
@@ -754,8 +776,9 @@ class VrpcAdapter {
       VrpcAdapter._listeners[instanceId][eventId]
     ) {
       const { listener, clients } = VrpcAdapter._listeners[instanceId][eventId]
-      clients.delete(clientId)
-      if (clients.size === 0) {
+      const index = clients.indexOf(clientId)
+      if (index !== -1) clients.splice(index, 1)
+      if (clients.length === 0) {
         delete VrpcAdapter._listeners[instanceId][eventId]
         if (Object.keys(VrpcAdapter._listeners[instanceId]).length === 0) {
           delete VrpcAdapter._listeners[instanceId]
@@ -769,9 +792,9 @@ class VrpcAdapter {
     const eventIds = VrpcAdapter._listeners[instanceId]
     if (!eventIds) return
     Object.entries(eventIds).forEach(([ek, ev]) => {
-      if (ev.event === event && ev.clients.has(clientId)) {
-        ev.clients.delete(clientId)
-        if (ev.clients.size === 0) {
+      if (ev.event === event && ev.clients.includes(clientId)) {
+        ev.clients = ev.clients.filter(x => x !== clientId)
+        if (ev.clients.length === 0) {
           VrpcAdapter.getInstance(instanceId).removeListener(
             ev.event,
             ev.listener
@@ -789,17 +812,21 @@ class VrpcAdapter {
       json.r = id
       promise
         .then(r => VrpcAdapter._callback({ ...json, r, i: id }))
-        .catch(err => VrpcAdapter._callback({ ...json, e: err.message, i: id }))
+        .catch(err =>
+          VrpcAdapter._callback({
+            ...json,
+            e: { message: err.message, cause: err.cause },
+            i: id
+          })
+        )
     } catch (err) {
-      json.data.e = err.message
+      const { message, cause } = err
+      json.data.e = { message, cause }
     }
   }
 
   static _generateId (object) {
-    return crypto
-      .createHash('md5')
-      .update(JSON.stringify(object))
-      .digest('hex')
+    return crypto.createHash('md5').update(JSON.stringify(object)).digest('hex')
   }
 
   static _getClassEntry (className) {
@@ -920,6 +947,7 @@ class VrpcAdapter {
  *
  * Emitted on deletion of shared instance
  *
+ * @event VrpcAdapter#beforeDelete
  * @event VrpcAdapter#delete
  * @type {Object}
  * @property {String} className The class name of the deleted instance

package/vrpc/VrpcAgent.js

@@ -3,8 +3,9 @@ const path = require('path')
 const mqtt = require('mqtt')
 const crypto = require('crypto')
 const { ArgumentParser } = require('argparse')
-const VrpcAdapter = require('./VrpcAdapter')
 const EventEmitter = require('events')
+const jsonStringifySafe = require('json-stringify-safe')
+const VrpcAdapter = require('./VrpcAdapter')
 
 const VRPC_PROTOCOL_VERSION = 3
 
@@ -67,13 +68,11 @@ class VrpcAgent extends EventEmitter {
       default: password
     })
     parser.add_argument('--bestEffort', {
-      help:
-        'Calls function on best-effort. Improves performance but may fail under unstable network connections.',
+      help: 'Calls function on best-effort. Improves performance but may fail under unstable network connections.',
       action: 'store_true'
     })
     parser.add_argument('-V', '-v', '--userVersion', {
-      help:
-        'User defined agent version. May be checked on the remote side for compatibility checks.',
+      help: 'User defined agent version. May be checked on the remote side for compatibility checks.',
       required: false,
       default: version,
       dest: 'version'
@@ -99,7 +98,7 @@ class VrpcAgent extends EventEmitter {
    * @param {String} [obj.agent='<user>-<pathId>@<hostname>-<platform>-js'] This agent's name
    * @param {String} [obj.broker='mqtts://vrpc.io:8883'] Broker url in form: `<scheme>://<host>:<port>`
    * @param {Object} [obj.log=console] Log object (must support debug, info, warn, and error level)
-   * @param {String} [obj.bestEffort=false] If true, message will be sent with best effort, i.e. no caching if offline
+   * @param {String} [obj.bestEffort=true] If true, message will be sent with best effort, i.e. no caching if offline
    * @param {String} [obj.version=''] The (user-defined) version of this agent
    * @param {String} [obj.mqttClientId='<generated()>'] Explicitly set the mqtt client id.
    *
@@ -117,7 +116,7 @@ class VrpcAgent extends EventEmitter {
     agent = VrpcAgent._generateAgentName(),
     broker = 'mqtts://vrpc.io:8883',
     log = 'console',
-    bestEffort = false,
+    bestEffort = true,
     version = '',
     mqttClientId = null
   } = {}) {
@@ -244,6 +243,32 @@ class VrpcAgent extends EventEmitter {
     }
   }
 
+  /**
+   * Creates a new instance locally
+   *
+   * NOTE: The instance must previously be registered by the local VrpcAdapter
+   *
+   * @param {Object} options
+   * @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 id will be generated
+   * @param {Array} [options.args] Positional arguments for the constructor call
+   * @param {bool} [options.isIsolated=false] If true the created instance will
+   * be visible only to the client who created it
+   * @returns {Object} The real instance (not a proxy!)
+   */
+  create ({ className, instance = nanoid(8), args = [], isIsolated = false }) {
+    const obj = VrpcAdapter.create({ className, instance, args, isIsolated })
+    if (!this._hasSharedInstance(instance)) {
+      this._subscribeToMethodsOfNewInstance(className, instance)
+      this._publishClassInfoMessage(className)
+      this._publishClassInfoConciseMessage(className)
+      this._registerSharedInstance(instance, null)
+    }
+    return obj
+  }
+
   static _generateAgentName () {
     const { username } = os.userInfo()
     const pathId = crypto
@@ -269,10 +294,7 @@ class VrpcAgent extends EventEmitter {
       os.type() +
       JSON.stringify(os.networkInterfaces()) +
       JSON.stringify(os.cpus().map(({ model }) => model))
-    return crypto
-      .createHash('md5')
-      .update(uid)
-      .digest('hex')
+    return crypto.createHash('md5').update(uid).digest('hex')
   }
 
   _validateDomain (domain) {
@@ -427,9 +449,9 @@ class VrpcAgent extends EventEmitter {
     let str
     const { c, f } = json
     try {
-      str = JSON.stringify(json)
+      str = jsonStringifySafe(json)
     } catch (err) {
-      this._log.debug(
+      console.error(
         `Failed serialization of return value for: ${c}::${f}, because: ${err.message}`
       )
       json.r = '__vrpc::not-serializable__'
@@ -456,6 +478,7 @@ class VrpcAgent extends EventEmitter {
     const classes = this._getClasses()
     classes.forEach(className => {
       this._publishClassInfoMessage(className)
+      this._publishClassInfoConciseMessage(className)
     })
     // Register all pre-existing instances
     for (const [
@@ -477,7 +500,7 @@ class VrpcAgent extends EventEmitter {
 
   _publishClassInfoMessage (className) {
     const json = {
-      className: className,
+      className,
       instances: this._getInstances(className),
       memberFunctions: this._getMemberFunctions(className),
       staticFunctions: this._getStaticFunctions(className),
@@ -490,6 +513,25 @@ class VrpcAgent extends EventEmitter {
         JSON.stringify(json),
         { retain: true }
       )
+    } catch (err) {
+      this._log.error(err, `Problem during publishing schema: ${err.message}`)
+    }
+  }
+
+  _publishClassInfoConciseMessage (className) {
+    const json = {
+      className,
+      instances: this._getInstances(className),
+      memberFunctions: this._getMemberFunctions(className),
+      staticFunctions: this._getStaticFunctions(className),
+      v: VRPC_PROTOCOL_VERSION
+    }
+    try {
+      this._mqttPublish(
+        `${this._baseTopic}/${className}/__classInfoConcise__`,
+        JSON.stringify(json),
+        { retain: true }
+      )
     } catch (err) {
       this._log.error(
         err,
@@ -563,6 +605,7 @@ class VrpcAgent extends EventEmitter {
           if (!this._hasSharedInstance(instanceId)) {
             this._subscribeToMethodsOfNewInstance(className, instanceId)
             this._publishClassInfoMessage(className)
+            this._publishClassInfoConciseMessage(className)
           }
           this._registerSharedInstance(instanceId, json.s)
           break
@@ -570,7 +613,10 @@ class VrpcAgent extends EventEmitter {
         case '__delete__': {
           this._unsubscribeMethodsOfDeletedInstance(className, instance)
           const wasShared = this._unregisterInstance(json.a[0], json.s)
-          if (wasShared) this._publishClassInfoMessage(className)
+          if (wasShared) {
+            this._publishClassInfoMessage(className)
+            this._publishClassInfoConciseMessage(className)
+          }
           break
         }
       }
@@ -666,10 +712,10 @@ class VrpcAgent extends EventEmitter {
       }
     })
     if (!found) {
-      this._log.warn(
-        `Failed un-registering not registered instance: ${instanceId}`
+      this._log.info(
+        `Unregistering non-tracked (possibly by agent created) instance: ${instanceId}`
       )
-      return false
+      return true
     }
     return true
   }