vrpc 3.0.0-alpha.1 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vrpc",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.1",
   "description": "Variadic Remote Procedure Calls",
   "main": "index.js",
   "directories": {
@@ -12,10 +12,11 @@
     "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",
-    "test": "npm run test:agent && npm run test:client && npm run test:native",
+    "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",
     "test:agent": "tests/agent/test.sh",
     "test:client": "tests/client/test.sh",
-    "test:native": "./node_modules/.bin/mocha tests/native/vrpc-native*.js --exit",
     "test:performance": "tests/performance/test.sh",
     "test:production": "./node_modules/.bin/mocha tests/production/lifeCycleTest.js --timeout 30000 --exit && tests/production/test.sh"
   },
@@ -49,7 +50,7 @@
     "crypto-browserify": "^3.12.0",
     "dockerode": "^3.2.0",
     "jsdoc-to-markdown": "^7.0.1",
-    "mocha": "^6.1.4",
+    "mocha": "^9.1.3",
     "os-browserify": "^0.3.0",
     "sinon": "^7.3.2",
     "stream-browserify": "^3.0.0",
@@ -66,8 +67,10 @@
   "dependencies": {
     "ajv": "^6.10.0",
     "argparse": "^2.0.1",
+    "buffer": "^6.0.3",
     "caller": "^1.0.1",
     "mqtt": "^4.2.6",
-    "nanoid": "^3.1.23"
+    "nanoid": "^3.1.23",
+    "process": "^0.11.10"
   }
 }

package/vrpc/VrpcAdapter.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
@@ -44,6 +44,7 @@ const Ajv = require('ajv')
 const caller = require('caller')
 const commentParser = require('./comment-parser')
 const EventEmitter = require('events')
+const { nanoid } = require('nanoid')
 
 /**
  * Generates an adapter layer for existing code and enables further VRPC-based
@@ -104,13 +105,16 @@ class VrpcAdapter {
     if (typeof code === 'string') {
       const absPath = path.resolve(caller(), '../', code)
       const relPath = path.relative(__dirname, absPath)
-      const absJsdocPath = `${absPath}.js`
+      const absJsdocPath =
+        absPath && absPath.endsWith('.js') ? absPath : `${absPath}.js`
       const Klass = require(relPath)
       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(), '../', `${jsdocPath}.js`)
+        const absJsdocPath = path.resolve(caller(), '../', sJsdocPath)
         this._registerClass(code, absJsdocPath, { ...options, jsdoc: true })
       } else {
         this._registerClass(code, null, options)
@@ -146,14 +150,16 @@ class VrpcAdapter {
       const content = fs.readFileSync(absJsdocPath).toString('utf8')
       meta = this._parseComments(content)
     }
-    VrpcAdapter._functionRegistry.set(className, {
-      memberFunctions,
-      meta,
-      Klass: {},
-      withNew: false,
-      staticFunctions: [],
-      schema: null
-    })
+    if (!VrpcAdapter._functionRegistry.has(className)) {
+      VrpcAdapter._functionRegistry.set(className, {
+        memberFunctions,
+        meta,
+        Klass: {},
+        withNew: false,
+        staticFunctions: [],
+        schema: null
+      })
+    }
     VrpcAdapter._instances.set(instance, {
       className,
       instance: obj,
@@ -161,81 +167,56 @@ class VrpcAdapter {
     })
   }
 
-  static getClasses () {
-    return JSON.stringify(VrpcAdapter._getClassesArray())
-  }
-
-  static getMemberFunctions (className) {
-    return JSON.stringify(VrpcAdapter._getMemberFunctionsArray(className))
-  }
-
-  static getStaticFunctions (className) {
-    return JSON.stringify(VrpcAdapter._getStaticFunctionsArray(className))
-  }
-
-  static getMetaData (className) {
-    return JSON.stringify(VrpcAdapter._getMetaData(className))
-  }
-
-  static getInstances (className) {
-    return JSON.stringify(VrpcAdapter._getInstancesArray(className))
-  }
-
-  static call (jsonString) {
-    const json = JSON.parse(jsonString)
-    VrpcAdapter._call(json)
-    return JSON.stringify(json)
-  }
-
-  static onCallback (callback) {
-    VrpcAdapter._callback = callback
-  }
-
-  // convenience interface if used in parallel - as local factory and from remote
-
-  /**
-   * Creates an un-managed, anonymous instance
-   *
-   * @param {String} className Name of the class to create an instance of
-   * @param  {...any} args  Arguments to provide to the constructor
-   * @returns {Object} The real instance (not a proxy!)
-   */
-  static create (className, ...args) {
-    if (typeof className === 'string') {
-      return VrpcAdapter._create(className, ...args)
-    }
-    if (typeof className === 'object') {
-      if (className.instance) {
-        return VrpcAdapter._createNamed(
-          className.className,
-          className.instance,
-          ...className.args
-        )
-      }
-      return VrpcAdapter._create(className.className, ...className.args)
-    }
-  }
+  /*****************************************************
+   * convenience interface if used as plug-able factory *
+   ******************************************************/
 
   /**
-   * Creates a managed named instance
+   * Creates a new instance
    *
-   * @param {String} className Name of the class to create an instance of
-   * @param {String} instance Name of the instance
-   * @param  {...any} args Arguments to provide to the constructor
+   * @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!)
    */
-  static createNamed (className, instance, ...args) {
-    return VrpcAdapter._createNamed(className, instance, ...args)
+  static create ({
+    className,
+    instance = nanoid(8),
+    args = [],
+    isIsolated = false
+  } = {}) {
+    const json = { c: className, a: [instance, ...args] }
+    const obj = isIsolated
+      ? VrpcAdapter._handleCreateIsolated(json)
+      : VrpcAdapter._handleCreateShared(json)
+    if (json.e) throw new Error(json.e)
+    return obj
   }
 
   /**
-   * Deletes a managed instance
+   * Deletes an instance
    *
-   * @param {String} instance Name of the instance to be deleted
+   * @param {String|Object} instance Instance (name or object itself) to be deleted
    * @returns {Boolean} True in case of success, false otherwise
    */
   static delete (instance) {
-    return VrpcAdapter._delete(instance)
+    if (typeof instance === 'string') {
+      return VrpcAdapter._delete(instance)
+    }
+    if (typeof instance === 'object') {
+      for (const [k, v] of VrpcAdapter._instances) {
+        if (v.instance === instance) {
+          VrpcAdapter._instances.delete(k)
+          return true
+        }
+      }
+      return false
+    }
   }
 
   /**
@@ -269,34 +250,14 @@ class VrpcAdapter {
     return VrpcAdapter._getInstancesArray(className)
   }
 
-  /**
-   * Provides all available member functions of the specified class.
-   *
-   * @param {String} className Name of class to provide member functions for
-   * @return {Array.<String>} Array of member function names
-   */
-  static getAvailableMemberFunctions (className) {
-    return VrpcAdapter._getMemberFunctionsArray(className)
-  }
-
-  /**
-   * Provides all available static functions of a registered class.
-   *
-   * @param {String} className Name of class to provide static functions for
-   * @returns {Array.<String>} Array of static function names
-   */
-  static getAvailableStaticFunctions (className) {
-    return VrpcAdapter._getStaticFunctionsArray(className)
+  static call (jsonString) {
+    const json = JSON.parse(jsonString)
+    VrpcAdapter._call(json)
+    return JSON.stringify(json)
   }
 
-  /**
-   * Provides all available meta data of the registered class.
-   *
-   * @param {String} className Name of class to provide meta data for
-   * @returns {MetaData} Meta Data
-   */
-  static getAvailableMetaData (className) {
-    return VrpcAdapter._getMetaData(className)
+  static onCallback (callback) {
+    VrpcAdapter._callback = callback
   }
 
   /**
@@ -429,6 +390,7 @@ class VrpcAdapter {
   }
 
   static _call (json) {
+    const before = Object.keys(VrpcAdapter._listeners).length
     switch (json.f) {
       case '__createIsolated__':
         VrpcAdapter._handleCreateIsolated(json)
@@ -443,53 +405,81 @@ class VrpcAdapter {
         VrpcAdapter._handleDelete(json)
         break
       default:
+        // this call may have the side-effect of taking a listener on board
         VrpcAdapter._handleCall(json)
     }
+    const after = Object.keys(VrpcAdapter._listeners).length
+    // if we took a listener on board we must tell our caller such that
+    // things can be cleaned up later.
+    return after > before
   }
 
   static _handleCreateIsolated (json) {
+    let instance
     try {
       const className = json.c
       const [instanceId, ...args] = json.a
-      const instance = VrpcAdapter._create(className, instanceId, ...args)
+      instance = VrpcAdapter._create(className, instanceId, ...args)
       VrpcAdapter._instances.set(instanceId, {
         instance,
         className,
         isIsolated: true
       })
+      VrpcAdapter._emitter.emit('create', {
+        args,
+        className,
+        isIsolated: true,
+        instance: instanceId
+      })
       json.r = instanceId
     } catch (err) {
       json.e = err.message
     }
+    return instance
   }
 
   static _handleCreateShared (json) {
+    let instance
     try {
       const className = json.c
       const [instanceId, ...args] = json.a
-      const instance = VrpcAdapter._create(className, instanceId, ...args)
+      instance = VrpcAdapter._create(className, instanceId, ...args)
       VrpcAdapter._instances.set(instanceId, {
         instance,
         className,
         isIsolated: false
       })
       json.r = instanceId
+      VrpcAdapter._emitter.emit('create', {
+        args,
+        className,
+        isIsolated: false,
+        instance: instanceId
+      })
     } catch (err) {
       json.e = err.message
     }
+    return instance
   }
 
   static _handleCallAll (json) {
     try {
       const calls = []
-      for (const [id, { className, instance }] of VrpcAdapter._instances) {
-        if (className !== json.c) continue
-        let v
+      for (const [
+        id,
+        { className, instance, isIsolated }
+      ] of VrpcAdapter._instances) {
+        // TODO Think about a configurable behavior w.r.t. isolated instances...
+        if (className !== json.c || isIsolated) continue
+        let v = true
         let e = null
         try {
-          const wrappedArgs = VrpcAdapter._wrapArguments(json, id)
-          const funcName = wrappedArgs[0]
-          v = instance[funcName].apply(instance, wrappedArgs.slice(1))
+          const unwrapped = VrpcAdapter._unwrapArguments(json, id)
+          if (unwrapped) {
+            const funcName = unwrapped[0]
+            v = instance[funcName].apply(instance, unwrapped.slice(1))
+            v = VrpcAdapter.sanitizeEventListenerReturnValues(v)
+          }
         } catch (err) {
           e = err.message
         }
@@ -509,14 +499,21 @@ class VrpcAdapter {
     }
   }
 
+  static sanitizeEventListenerReturnValues (ret) {
+    return typeof ret === 'object' &&
+      ret._events !== undefined &&
+      ret._eventsCount !== undefined
+      ? true
+      : ret
+  }
+
   static _handleDelete (json) {
     try {
-      const wrappedArgs = VrpcAdapter._wrapArguments(json)
-      const instanceId = wrappedArgs[0]
-      json.r = VrpcAdapter._delete(instanceId)
+      const instance = json.a[0] // first arg is instance to be deleted
+      json.r = VrpcAdapter._delete(instance)
       VrpcAdapter._emitter.emit('delete', {
-        className: json.c,
-        instance: wrappedArgs[0]
+        instance,
+        className: json.c
       })
     } catch (err) {
       json.e = err.message
@@ -524,7 +521,18 @@ class VrpcAdapter {
   }
 
   static _handleCall (json) {
-    const wrappedArgs = VrpcAdapter._wrapArguments(json)
+    // special case: removeAllListeners
+    if (json.f === 'removeAllListeners') {
+      VrpcAdapter._removeAllListeners(json.a[0], json.s, json.c)
+      json.r = true
+      return
+    }
+    const unwrapped = VrpcAdapter._unwrapArguments(json)
+    if (!unwrapped) {
+      // this call must be skipped (event emitter stuff)
+      json.r = true
+      return
+    }
     // Check whether context is a registered class
     const entry = VrpcAdapter._functionRegistry.get(json.c)
     if (entry !== undefined) {
@@ -536,7 +544,7 @@ class VrpcAdapter {
       // subscription against all functions
       if (VrpcAdapter._isFunction(Klass[json.f])) {
         try {
-          const ret = Klass[json.f].apply(null, wrappedArgs)
+          const ret = Klass[json.f].apply(null, unwrapped)
           // check if function returns promise
           if (VrpcAdapter._isPromise(ret)) {
             this._handlePromise(json, ret)
@@ -554,7 +562,8 @@ class VrpcAdapter {
       const { instance } = entry
       if (VrpcAdapter._isFunction(instance[json.f])) {
         try {
-          const ret = instance[json.f].apply(instance, wrappedArgs)
+          let ret = instance[json.f].apply(instance, unwrapped)
+          ret = VrpcAdapter.sanitizeEventListenerReturnValues(ret)
           // check if function returns promise
           if (VrpcAdapter._isPromise(ret)) {
             this._handlePromise(json, ret)
@@ -580,20 +589,34 @@ class VrpcAdapter {
   static _delete (instanceId) {
     const entry = VrpcAdapter._instances.get(instanceId)
     if (entry) {
+      // in case the instance was an EventEmitter, free all registered listeners
+      if (VrpcAdapter._isFunction(entry.removeAllListeners)) {
+        entry.removeAllListeners()
+      }
+      for (const [key, { clients, instance }] of Object.entries(
+        VrpcAdapter._listeners
+      )) {
+        if (instance === instanceId) {
+          VrpcAdapter._listeners[key] = { clients }
+        }
+      }
       VrpcAdapter._instances.delete(instanceId)
       return true
     }
     return false
   }
 
-  static _unregisterEventListeners (clientId) {
-    const listeners = VrpcAdapter._listeners[clientId]
-    if (listeners) {
-      listeners.forEach(({ i, e, f }) => {
-        VrpcAdapter.getInstance(i).removeListener(e, f)
-      })
+  static _unregisterClient (clientId) {
+    for (const [key, value] of Object.entries(VrpcAdapter._listeners)) {
+      const { instance, event, listener, clients } = value
+      clients.delete(clientId)
+      if (clients.size === 0) {
+        if (event) {
+          VrpcAdapter.getInstance(instance).removeListener(event, listener)
+        }
+        delete VrpcAdapter._listeners[key]
+      }
     }
-    delete VrpcAdapter._listeners[clientId]
   }
 
   static _validate (schema, params) {
@@ -604,51 +627,101 @@ class VrpcAdapter {
     if (!valid) throw new Error(VrpcAdapter._ajv.errorsText())
   }
 
-  static _wrapArguments (json, instanceId) {
-    const { f: func, s: sender, a: args, c: context } = json
-    const wrapped = []
-    args.forEach(arg => {
-      // Find those args that actually need to be function callbacks
-      if (typeof arg === 'string' && arg.substr(0, 5) === '__f__') {
-        const f = this._generateWrapper(arg, json, instanceId)
-        wrapped.push(f)
-        if (!sender) return
-        // Register this client to later know when he is dead and skip callbacks
-        if (!VrpcAdapter._listeners[sender]) VrpcAdapter._listeners[sender] = []
-        // Check whether injected callback is an EventEmitter registration
-        if (func === 'on' && typeof args[0] === 'string') {
-          const e = args[0]
-          const i = context
-          const r = arg
-          VrpcAdapter._listeners[sender].push({ i, e, f, r })
+  static _unwrapArguments (json, instanceId) {
+    const sender = json.s
+    let context = json.c
+    let func = json.f
+    let args = json.a
+    // things are different if we came from callAll (instanceId !== undefined)
+    if (instanceId) {
+      context = instanceId
+      func = args[0]
+      args = args.slice(1)
+    }
+    const unwrapped = instanceId ? [func] : []
+    for (const arg of args) {
+      // find those args that actually need to be functions
+      if (typeof arg === 'string' && arg.slice(0, 5) === '__f__') {
+        const callback = this._generateCallback(arg, sender, instanceId)
+        unwrapped.push(callback)
+      } else if (typeof arg === 'string' && arg.slice(0, 5) === '__e__') {
+        const listener = this._generateListener(arg, sender, instanceId)
+        unwrapped.push(listener)
+        // start tracking clients that are registering event listeners
+        if (!VrpcAdapter._listeners[arg]) {
+          VrpcAdapter._listeners[arg] = {
+            listener,
+            clients: new Set([sender]),
+            instances: new Set(),
+            event: null
+          }
+        } else {
+          VrpcAdapter._listeners[arg].clients.add(sender)
+        }
+        // see whether the requested listener is an EventEmitter registration
+        if (func === 'on' || func === 'addListener') {
+          // if this event is already registered on the given instance
+          // avoid a second registration
+          if (
+            VrpcAdapter._listeners[arg].event &&
+            VrpcAdapter._listeners[arg].instances.has(context)
+          ) {
+            return null // means that this call won't be forwarded
+          }
+          VrpcAdapter._listeners[arg].event = args[0]
+          VrpcAdapter._listeners[arg].instances.add(context)
         }
-        if (
-          (func === 'off' || func === 'removeListener') &&
-          typeof args[0] === 'string'
-        ) {
-          const listener = VrpcAdapter._listeners[sender]
-          const entry = listener && listener.find(x => x.r === arg)
-          if (entry) {
-            const { i, e, f } = entry
-            VrpcAdapter.getInstance(i).removeListener(e, f)
+        if (func === 'off' || func === 'removeListener') {
+          const {
+            clients,
+            instances,
+            listener,
+            event
+          } = VrpcAdapter._listeners[arg]
+          clients.delete(sender)
+          instances.delete(context)
+          if (clients.size === 0) {
+            delete VrpcAdapter._listeners[arg]
+            VrpcAdapter.getInstance(context).off(event, listener)
           }
+          return null // means that this call won't be forwarded
         }
       } else {
-        // Leave the others untouched
-        wrapped.push(arg)
+        // default behavior is to not touch
+        unwrapped.push(arg)
       }
-    })
-    return wrapped
+    }
+    return unwrapped
+  }
+
+  static _removeAllListeners (event, sender, context) {
+    for (const [key, value] of Object.entries(VrpcAdapter._listeners)) {
+      if (value.event === event) {
+        value.clients.delete(sender)
+        if (value.clients.size === 0) {
+          delete VrpcAdapter._listeners[key]
+          VrpcAdapter.getInstance(context).off(event, value.listener)
+        }
+      }
+    }
+  }
+
+  static _generateCallback (id, sender, instanceId) {
+    return (...innerArgs) => {
+      // callAll expects the instanceId as first argument
+      const a = instanceId ? [instanceId, ...innerArgs] : [...innerArgs]
+      VrpcAdapter._callback({ a, s: sender, i: id })
+    }
   }
 
-  static _generateWrapper (id, json, instanceId) {
-    const wrapper = (...innerArgs) => {
-      // do not even trigger a callback for already offline clients
-      if (json.s && !VrpcAdapter._listeners[json.s]) return
+  static _generateListener (id, sender, instanceId) {
+    return (...innerArgs) => {
+      // do not even emit for already offline clients
+      if (!VrpcAdapter._listeners[id]) return
+      // callAll expects the instanceId as first argument
       const a = instanceId ? [instanceId, ...innerArgs] : [...innerArgs]
-      VrpcAdapter._callback({ ...json, a, i: id })
+      VrpcAdapter._callback({ a, s: sender, i: id })
     }
-    return wrapper
   }
 
   static _handlePromise (json, promise) {
@@ -775,7 +848,7 @@ class VrpcAdapter {
 /**
  * Event 'create'
  *
- * Emitted on creation of named instance
+ * Emitted on creation of shared instance
  *
  * @event VrpcAdapter#create
  * @type {Object}
@@ -787,7 +860,7 @@ class VrpcAdapter {
 /**
  * Event 'delete'
  *
- * Emitted on deletion of named instance
+ * Emitted on deletion of shared instance
  *
  * @event VrpcAdapter#delete
  * @type {Object}