vrpc 3.13.0 → 3.15.0

package/vrpc/VrpcBrowserAdapter.js

@@ -14,7 +14,7 @@ procedure calls (RPC).
 Author: Dr. Burkhard C. Heisen (https://github.com/heisenware/vrpc)
 
 Licensed under the MIT License <http://opensource.org/licenses/MIT>.
-Copyright (c) 2018 - 2022 Dr. Burkhard C. Heisen <burkhard.heisen@heisenware.com>.
+Copyright (c) 2018 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
@@ -38,6 +38,8 @@ SOFTWARE.
 const Ajv = require('ajv')
 const EventEmitter = require('events')
 const { nanoid } = require('nanoid')
+const Registrations = require('./Registrations')
+const NamePattern = require('./namePattern')
 
 // A runtime without dispose symbols (older browsers, Node before 18.18 /
 // 20.4) gets Node's own stand-ins from the symbol registry, so a class file
@@ -82,6 +84,7 @@ class VrpcAdapter {
     staticFunctions.push('__createIsolated__')
     staticFunctions.push('__createShared__')
     staticFunctions.push('__callAll__')
+    staticFunctions.push('__callMatching__')
     staticFunctions.push('__delete__')
     let memberFunctions = VrpcAdapter._extractMemberFunctions(Klass)
     if (onlyPublic) {
@@ -303,8 +306,35 @@ class VrpcAdapter {
 
   // private:
 
+  /**
+   * Handles one request in place: the answer lands on `json` as `r` or `e`.
+   * Every request is answered - a malformed one, an unknown context or
+   * function with an error - so no caller waits for its timeout.
+   *
+   * @returns {Boolean} Whether the call took subscriptions of its sender,
+   * whose presence the agent then watches
+   */
   static _call (json) {
     VrpcAdapter._mustTrackClient = false // reset client tracking flag
+    // the answer is what the call yields, never what the request brought
+    delete json.r
+    delete json.e
+    try {
+      // a request without arguments has none
+      if (json.a === undefined) json.a = []
+      if (!Array.isArray(json.a)) {
+        throw new Error('The arguments of a request must be an array')
+      }
+      VrpcAdapter._dispatch(json)
+    } catch (err) {
+      json.e = VrpcAdapter._error(err)
+    }
+    // if we took a listener on board we must tell our caller such that
+    // things can be cleaned up later.
+    return VrpcAdapter._mustTrackClient
+  }
+
+  static _dispatch (json) {
     switch (json.f) {
       case '__createIsolated__':
         VrpcAdapter._handleCreateIsolated(json)
@@ -315,16 +345,49 @@ class VrpcAdapter {
       case '__callAll__':
         VrpcAdapter._handleCallAll(json)
         break
+      case '__callMatching__':
+        VrpcAdapter._handleCallMatching(json)
+        break
       case '__delete__':
         VrpcAdapter._handleDelete(json)
         break
+      case '__unsubscribe__':
+        VrpcAdapter._handleUnsubscribe(json)
+        break
+      case '__registrations__':
+        VrpcAdapter._handleRegistrations(json)
+        break
+      case '__end__':
+        VrpcAdapter._handleEnd(json)
+        break
       default:
         // this call may have the side-effect of taking a listener on board
         VrpcAdapter._handleCall(json)
     }
-    // if we took a listener on board we must tell our caller such that
-    // things can be cleaned up later.
-    return VrpcAdapter._mustTrackClient
+  }
+
+  // an error as it travels: `{ message, cause? }`, whatever was thrown
+  static _error (err) {
+    if (err && typeof err === 'object' && 'message' in err) {
+      const e = { message: String(err.message) }
+      if (err.cause !== undefined) e.cause = err.cause
+      return e
+    }
+    return { message: String(err) }
+  }
+
+  /**
+   * Whether a request may call a function: only what the class info lists
+   * is reachable - a member function of the instance's class, a static
+   * function of the class, or a registered global function. Anything else
+   * an object happens to have (an EventEmitter's `emit`, a private helper)
+   * stays inside the agent.
+   */
+  static _isPublished (className, func, isStatic) {
+    const entry = VrpcAdapter._functionRegistry.get(className)
+    if (!entry) return false
+    const published = isStatic ? entry.staticFunctions : entry.memberFunctions
+    return published.includes(func)
   }
 
   /**
@@ -343,11 +406,28 @@ class VrpcAdapter {
     )
   }
 
+  /**
+   * An instance name is one topic level of its own: a non-empty string
+   * without `/`, `+`, `#` or `*` (which would read as a pattern), and never
+   * `__static__`, which stands for the class in a request topic.
+   */
+  static _assertInstanceName (name) {
+    if (
+      typeof name !== 'string' ||
+      name.length === 0 ||
+      /[/+#*]/.test(name) ||
+      name === '__static__'
+    ) {
+      throw new Error(`Invalid instance name: ${JSON.stringify(name)}`)
+    }
+  }
+
   static _handleCreateIsolated (json) {
     let instance
     try {
       const className = json.c
       const [instanceId, ...args] = json.a
+      VrpcAdapter._assertInstanceName(instanceId)
       const existing = VrpcAdapter._instances.get(instanceId)
       if (existing) {
         // an id is never re-homed: a shared instance stays shared, an
@@ -375,7 +455,7 @@ class VrpcAdapter {
       })
       json.r = instanceId
     } catch (err) {
-      json.e = err.message
+      json.e = VrpcAdapter._error(err)
     }
     return instance
   }
@@ -385,6 +465,7 @@ class VrpcAdapter {
     try {
       const className = json.c
       const [instanceId, ...args] = json.a
+      VrpcAdapter._assertInstanceName(instanceId)
       const existing = VrpcAdapter._instances.get(instanceId)
       if (existing && existing.isIsolated) {
         throw new Error(`Instance '${instanceId}' exists as an isolated instance`)
@@ -403,66 +484,203 @@ class VrpcAdapter {
         instance: instanceId
       })
     } catch (err) {
-      json.e = err.message
+      json.e = VrpcAdapter._error(err)
     }
     return instance
   }
 
+  // `a` = [function, ...arguments]: every shared instance of the class (ALL-1)
   static _handleCallAll (json) {
+    const [func, ...args] = json.a
+    VrpcAdapter._callAll(json, func, args, () => true)
+  }
+
+  // `a` = [selection, function, ...arguments]: the shared instances whose
+  // name the selection matches, a pattern or a list of them (ALL-4, ALL-5)
+  static _handleCallMatching (json) {
+    const [selection, func, ...args] = json.a
+    if (!NamePattern.isSelection(selection)) {
+      json.e = {
+        message: `Invalid selection: ${JSON.stringify(selection)} (a pattern or a list of them)`
+      }
+      return
+    }
+    VrpcAdapter._callAll(json, func, args, id =>
+      NamePattern.selects(selection, id)
+    )
+  }
+
+  // calls a function on the shared instances of a class `chosen` takes, and
+  // answers one entry per instance (ALL-2)
+  static _callAll (json, func, args, chosen) {
     try {
       const calls = []
+      const subscribes = Registrations.carriesEventIds(args)
+      // a remover carrying ids never reaches the class (see Registrations)
+      const withdraws = subscribes && Registrations.isRemover(func, json.v)
+      if (!withdraws && !VrpcAdapter._isPublished(json.c, func, false)) {
+        throw new Error(`Could not find function: ${func}`)
+      }
+      // what the instance's callbacks unwrap from: the function and its
+      // arguments, as a __callAll__ request carries them
+      const asCallAll = { ...json, a: [func, ...args] }
       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
+        // isolated instances never take part
+        if (className !== json.c || isIsolated || !chosen(id)) continue
+        // one answer per instance: `{ id, val }`, or `{ id, err }` with the
+        // error as it travels
         try {
-          const unwrapped = VrpcAdapter._unwrapArguments(json, id)
-          if (unwrapped) {
-            const funcName = unwrapped[0]
-            v = instance[funcName].apply(instance, unwrapped.slice(1))
-            v = VrpcAdapter.sanitizeEventListenerReturnValues(v)
+          let val
+          if (subscribes) {
+            val = VrpcAdapter._subscribe(json, {
+              contextKey: id,
+              contextName: id,
+              target: instance,
+              func,
+              args,
+              isCallAll: true
+            }).value
+          } else {
+            const unwrapped = VrpcAdapter._unwrapArguments(asCallAll, id)
+            val = instance[func].apply(instance, unwrapped.slice(1))
+            val = VrpcAdapter.sanitizeEventListenerReturnValues(val)
           }
-        } catch (err) {
-          e = err.message
-        }
-        if (VrpcAdapter._isPromise(v)) {
           calls.push(
-            v
-              .then(val => ({ id, val, err: null }))
-              .catch(err => ({ id, err, val: null }))
+            VrpcAdapter._isPromise(val)
+              ? val.then(
+                x => ({ id, val: x }),
+                err => ({ id, err: VrpcAdapter._error(err) })
+              )
+              : { id, val }
           )
-        } else {
-          calls.push({ id, val: v, err: e })
+        } catch (err) {
+          calls.push({ id, err: VrpcAdapter._error(err) })
         }
       }
-      this._handlePromise(
+      VrpcAdapter._handlePromise(
         json,
         Promise.allSettled(calls).then(result =>
           result.filter(x => x.status === 'fulfilled').map(x => x.value)
         )
       )
     } catch (err) {
-      json.e = err.message
+      json.e = VrpcAdapter._error(err)
     }
   }
 
   static sanitizeEventListenerReturnValues (ret) {
-    return ret &&
-      typeof ret === 'object' &&
-      ret._events !== undefined &&
-      ret._eventsCount !== undefined
-      ? true
-      : ret
+    return Registrations.sanitize(ret)
+  }
+
+  /**
+   * The book key of a request's context: an instance id, or the class for
+   * static functions (kept apart from an instance of the same name).
+   */
+  static _contextKey (context, isStatic) {
+    return isStatic ? `\u0000${context}` : context
+  }
+
+  // a class name addresses the class, as in _handleCall
+  static _isStaticContext (context) {
+    return VrpcAdapter._functionRegistry.has(context)
+  }
+
+  /**
+   * A call carrying subscription ids: one registration per context,
+   * function and arguments, shared by every subscription (see
+   * Registrations).
+   */
+  static _subscribe (
+    json,
+    { contextKey, contextName, target, func, args, isCallAll = false }
+  ) {
+    const result = VrpcAdapter._registrations.call({
+      json,
+      contextKey,
+      contextName,
+      target,
+      func,
+      args,
+      isCallAll,
+      speaks: VrpcAdapter._speaksFor(contextName),
+      makeCallback: eventId =>
+        VrpcAdapter._generateCallback({
+          clientId: json.s,
+          isCallAll,
+          instanceId: contextName,
+          eventId,
+          receiverVersion: json.v
+        })
+    })
+    // a subscriber is tracked: its going withdraws what it holds
+    if (result.ids.length > 0) VrpcAdapter._mustTrackClient = true
+    return result
+  }
+
+  /**
+   * `__unsubscribe__ [id, ...]`: withdraws the sender's subscriptions
+   * wherever they are held; an entry `{ id, context }` withdraws that id
+   * on that instance only (one instance of a callAll subscription).
+   * Answers true.
+   */
+  static _handleUnsubscribe (json) {
+    VrpcAdapter._registrations.unsubscribe(json.a || [], json.s)
+    json.r = true
+  }
+
+  /**
+   * `__registrations__`: lists the registrations of an instance or (on the
+   * static topic) a class.
+   */
+  static _handleRegistrations (json) {
+    try {
+      const isStatic = VrpcAdapter._isStaticContext(json.c)
+      if (!isStatic) {
+        VrpcAdapter._assertOwner(VrpcAdapter._instances.get(json.c), json, json.c)
+      }
+      json.r = VrpcAdapter._registrations.list(
+        VrpcAdapter._contextKey(json.c, isStatic)
+      )
+    } catch (err) {
+      json.e = VrpcAdapter._error(err)
+    }
+  }
+
+  /**
+   * `__end__ [function, args, by]`: ends one registration for all its
+   * subscriptions, which are told who ended it. Answers whether it existed.
+   */
+  static _handleEnd (json) {
+    try {
+      const isStatic = VrpcAdapter._isStaticContext(json.c)
+      if (!isStatic) {
+        VrpcAdapter._assertOwner(VrpcAdapter._instances.get(json.c), json, json.c)
+      }
+      const [func, args = [], by = null] = json.a || []
+      json.r = VrpcAdapter._registrations.end(
+        VrpcAdapter._contextKey(json.c, isStatic),
+        func,
+        args,
+        by
+      )
+    } catch (err) {
+      json.e = VrpcAdapter._error(err)
+    }
   }
 
   static _handleDelete (json) {
     try {
       const instance = json.a[0] // first arg is instance to be deleted
-      VrpcAdapter._assertOwner(VrpcAdapter._instances.get(instance), json, instance)
+      const entry = VrpcAdapter._instances.get(instance)
+      // a delete names the instance's own class: the class info of that
+      // class is what announces it gone
+      if (entry && entry.className !== json.c && json.s !== VrpcAdapter.LOCAL_SENDER) {
+        throw new Error(`Instance '${instance}' is not of class '${json.c}'`)
+      }
+      VrpcAdapter._assertOwner(entry, json, instance)
       VrpcAdapter._emitter.emit('beforeDelete', {
         instance,
         className: json.c
@@ -479,7 +697,7 @@ class VrpcAdapter {
         VrpcAdapter._handlePromise(json, disposed.then(() => ended))
       } else json.r = ended
     } catch (err) {
-      json.e = err.message
+      json.e = VrpcAdapter._error(err)
     }
   }
 
@@ -488,13 +706,19 @@ class VrpcAdapter {
     try {
       VrpcAdapter._assertOwner(VrpcAdapter._instances.get(json.c), json, json.c)
     } catch (err) {
-      const { message, cause } = err
-      json.e = { message, cause }
+      json.e = VrpcAdapter._error(err)
       return
     }
-    // special case: removeAllListeners
+    // special case: removeAllListeners withdraws the caller's subscriptions
+    // of that event - the emitter itself is never touched, it holds other
+    // clients' and its own listeners
     if (json.f === 'removeAllListeners') {
-      VrpcAdapter._removeAllListeners(json.a[0], json.s, json.c)
+      const isStatic = VrpcAdapter._isStaticContext(json.c)
+      VrpcAdapter._registrations.withdrawEvent(
+        VrpcAdapter._contextKey(json.c, isStatic),
+        json.a[0],
+        json.s
+      )
       json.r = true
       return
     }
@@ -507,66 +731,93 @@ class VrpcAdapter {
     ) {
       throw new Error(`Could not find context: ${json.c}`)
     }
-    const unwrapped = VrpcAdapter._unwrapArguments(json)
-    if (!unwrapped) {
-      // this call must be skipped (event emitter stuff)
-      json.r = true
-      return
-    }
-
     // Check whether context is global
     if (json.c === VRPC_GLOBAL) {
+      if (!VrpcAdapter._isPublished(VRPC_GLOBAL, json.f, true)) {
+        throw new Error(`Could not find function: ${json.f}`)
+      }
       try {
+        const unwrapped = VrpcAdapter._unwrapArguments(json)
         const ret = window[VRPC_WINDOW_NS][json.f].apply(null, unwrapped)
         // check if function returns promise
         if (VrpcAdapter._isPromise(ret)) {
           VrpcAdapter._handlePromise(json, ret)
         } else json.r = ret
       } catch (err) {
-        json.e = err.message
+        json.e = VrpcAdapter._error(err)
       }
       return
     }
-
-    // Check whether context is a registered class
-    const entry = VrpcAdapter._functionRegistry.get(json.c)
-    if (entry !== undefined) {
-      // entry is class -> function is static
-      const { Klass } = entry
-      // TODO Think about whether to do live checking (like here) or
-      // rather sticking to those functions registered before...
-      // TODO This is even more important now as the agent does a wildcard
-      // subscription against all functions
-      if (VrpcAdapter._isFunction(Klass[json.f])) {
-        try {
-          const ret = Klass[json.f].apply(null, unwrapped)
-          // check if function returns promise
-          if (VrpcAdapter._isPromise(ret)) {
-            VrpcAdapter._handlePromise(json, ret)
-          } else json.r = ret
-        } catch (err) {
-          json.e = err.message
-        }
-      } else throw new Error(`Could not find static function: ${json.f}`)
+    // Check whether context is a registered class (function is static)
+    const classEntry = VrpcAdapter._functionRegistry.get(json.c)
+    const isStatic = classEntry !== undefined
+    let target
+    let className = json.c
+    if (isStatic) {
+      target = classEntry.Klass
     } else {
-      // is not static
       const entry = VrpcAdapter._instances.get(json.c)
       if (entry === undefined) {
         throw new Error(`Could not find context: ${json.c}`)
       }
-      const { instance } = entry
-      if (VrpcAdapter._isFunction(instance[json.f])) {
-        try {
-          let ret = instance[json.f].apply(instance, unwrapped)
-          ret = VrpcAdapter.sanitizeEventListenerReturnValues(ret)
-          // check if function returns promise
-          if (VrpcAdapter._isPromise(ret)) {
-            VrpcAdapter._handlePromise(json, ret)
-          } else json.r = ret
-        } catch (err) {
-          json.e = err.message
-        }
-      } else throw new Error(`Could not find member function: ${json.f}`)
+      target = entry.instance
+      className = entry.className
+    }
+    const carriesIds = Registrations.carriesEventIds(json.a)
+    // only what the class info lists is called; a remover carrying ids never
+    // reaches the class (see Registrations)
+    if (
+      !(carriesIds && Registrations.isRemover(json.f, json.v)) &&
+      !VrpcAdapter._isPublished(className, json.f, isStatic)
+    ) {
+      throw new Error(`Could not find function: ${json.f}`)
+    }
+    // a call carrying subscription ids subscribes (or withdraws)
+    if (carriesIds) {
+      try {
+        const { value } = VrpcAdapter._subscribe(json, {
+          contextKey: VrpcAdapter._contextKey(json.c, isStatic),
+          contextName: json.c,
+          target,
+          func: json.f,
+          args: json.a
+        })
+        if (VrpcAdapter._isPromise(value)) {
+          VrpcAdapter._handlePromise(json, value)
+        } else json.r = value
+      } catch (err) {
+        json.e = VrpcAdapter._error(err)
+      }
+      return
+    }
+    const unwrapped = VrpcAdapter._unwrapArguments(json)
+    // special case: removing a listener the adapter does not hold (the
+    // client's subscription outlived a restart of this agent, or it sent
+    // no listener at all) - nothing to remove, and the instance's
+    // EventEmitter would throw on a listener that is not a function
+    if (
+      (json.f === 'off' || json.f === 'removeListener') &&
+      typeof unwrapped[1] !== 'function'
+    ) {
+      json.r = true
+      return
+    }
+    // TODO Think about whether to do live checking (like here) or
+    // rather sticking to those functions registered before...
+    if (!VrpcAdapter._isFunction(target[json.f])) {
+      throw new Error(`Could not find function: ${json.f}`)
+    }
+    try {
+      let ret = isStatic
+        ? target[json.f].apply(null, unwrapped)
+        : target[json.f].apply(target, unwrapped)
+      if (!isStatic) ret = VrpcAdapter.sanitizeEventListenerReturnValues(ret)
+      // check if function returns promise
+      if (VrpcAdapter._isPromise(ret)) {
+        VrpcAdapter._handlePromise(json, ret)
+      } else json.r = ret
+    } catch (err) {
+      json.e = VrpcAdapter._error(err)
     }
   }
 
@@ -588,9 +839,10 @@ class VrpcAdapter {
   /**
    * Ends an instance - the one teardown behind every door (a remote delete,
    * the auto-delete of an isolated instance whose client went, an
-   * in-process delete): its name is free at once, the adapter takes back
-   * every listener it attached (silent from now on anyway, see
-   * _generateListener), and the object releases what it runs through the
+   * in-process delete): its name is free at once, the adapter forgets its
+   * registrations (silent from now on, see Registrations; released by the
+   * adapter only for an object without a dispose method, and Node's own
+   * `on` always), and the object releases what it runs through the
    * ECMAScript dispose protocol, `[Symbol.asyncDispose]` or else
    * `[Symbol.dispose]`.
    *
@@ -601,33 +853,16 @@ class VrpcAdapter {
     const entry = VrpcAdapter._instances.get(instanceId)
     if (!entry) return { ended: false, disposed: null }
     VrpcAdapter._instances.delete(instanceId)
-    VrpcAdapter._detachListeners(instanceId, entry.instance)
+    const { instance } = entry
+    VrpcAdapter._registrations.forgetContext(instanceId, {
+      release: !(
+        VrpcAdapter._isFunction(instance[Symbol.asyncDispose]) ||
+        VrpcAdapter._isFunction(instance[Symbol.dispose])
+      )
+    })
     return { ended: true, disposed: VrpcAdapter._dispose(instanceId, entry) }
   }
 
-  static _detachListeners (instanceId, instance) {
-    const registrations = VrpcAdapter._listeners[instanceId]
-    delete VrpcAdapter._listeners[instanceId]
-    if (!registrations || !VrpcAdapter._isFunction(instance.removeListener)) {
-      return
-    }
-    for (const { event, listener, clients } of Object.values(registrations)) {
-      try {
-        VrpcAdapter._removeTimes(instance, event, listener, clients.length)
-      } catch (err) {
-        // a class whose removeListener fails keeps a silent listener
-      }
-    }
-  }
-
-  // a subscription repeated n times may hold n attachments of one listener
-  // (EventEmitter semantics): each removeListener takes one of them
-  static _removeTimes (instance, event, listener, times) {
-    for (let n = 0; n < Math.max(1, times); n++) {
-      instance.removeListener(event, listener)
-    }
-  }
-
   /**
    * Runs the object's dispose method. A dispose that fails or outlasts
    * VrpcAdapter.DISPOSE_TIMEOUT is reported (event 'disposeFailed') and
@@ -673,24 +908,7 @@ class VrpcAdapter {
   }
 
   static _unregisterClient (clientId) {
-    Object.entries(VrpcAdapter._listeners).forEach(([ik, iv]) => {
-      Object.entries(iv).forEach(([ek, ev]) => {
-        const { listener, event } = ev
-        // a client is listed once per subscription: its going ends them all
-        const remaining = ev.clients.filter(x => x !== clientId)
-        const gone = ev.clients.length - remaining.length
-        if (gone === 0) return
-        ev.clients = remaining
-        if (remaining.length === 0) {
-          const entry = VrpcAdapter._instances.get(ik)
-          const instance = entry && entry.instance
-          if (instance && instance.removeListener) {
-            VrpcAdapter._removeTimes(instance, event, listener, gone)
-          }
-          delete VrpcAdapter._listeners[ik][ek]
-        }
-      })
-    })
+    VrpcAdapter._registrations.withdrawClient(clientId)
   }
 
   static _validate (schema, params) {
@@ -701,6 +919,7 @@ class VrpcAdapter {
     if (!valid) throw new Error(VrpcAdapter._ajv.errorsText())
   }
 
+  // the arguments of a plain call: `__f__` ids become one-shot callbacks
   static _unwrapArguments (json, instanceId) {
     const clientId = json.s
     // if we came from a "callAll" we will have an instanceId defined
@@ -711,59 +930,17 @@ class VrpcAdapter {
     const func = isCallAll ? json.a[0] : json.f
     const unwrapped = isCallAll ? [func] : []
     for (const arg of args) {
-      if (typeof arg === 'string') {
-        if (arg.startsWith('__f__')) {
-          // function callback
-          unwrapped.push(
-            VrpcAdapter._generateCallback({
-              clientId,
-              isCallAll,
-              instanceId: context,
-              eventId: arg
-            })
-          )
-        } else if (arg.startsWith('__e__')) {
-          // event registration
-          if (func === 'on' || func === 'addListener') {
-            VrpcAdapter._mustTrackClient = true
-            const held = VrpcAdapter._holdsListener(context, arg)
-            const listener = VrpcAdapter._registerListener({
-              clientId,
-              isCallAll,
-              instanceId: context,
-              eventId: arg,
-              event: args[0]
-            })
-            // attached already: skip the call, one listener hears once
-            if (held) return null
-            unwrapped.push(listener)
-            // event un-registration
-          } else if (func === 'off' || func === 'removeListener') {
-            const listener = VrpcAdapter._unregisterListener({
-              clientId,
-              instanceId: context,
-              eventId: arg
-            })
-            if (!listener) {
-              return null // skip call as others are still interested
-            }
-            unwrapped.push(listener)
-          } else {
-            VrpcAdapter._mustTrackClient = true
-            const listener = VrpcAdapter._registerListener({
-              clientId,
-              isCallAll,
-              instanceId: context,
-              eventId: arg,
-              event: null
-            })
-            unwrapped.push(listener)
-          }
-        } else {
-          unwrapped.push(arg)
-        }
+      if (typeof arg === 'string' && arg.startsWith('__f__')) {
+        unwrapped.push(
+          VrpcAdapter._generateCallback({
+            clientId,
+            isCallAll,
+            instanceId: context,
+            eventId: arg,
+            receiverVersion: json.v
+          })
+        )
       } else {
-        // regular argument
         unwrapped.push(arg)
       }
     }
@@ -787,113 +964,38 @@ class VrpcAdapter {
     }
   }
 
-  static _holdsListener (instanceId, eventId) {
-    const registrations = VrpcAdapter._listeners[instanceId]
-    return Boolean(registrations && registrations[eventId])
-  }
-
-  static _generateCallback ({ eventId, clientId, instanceId, isCallAll }) {
-    const speaks = VrpcAdapter._speaksFor(instanceId)
-    return (...innerArgs) => {
-      if (!speaks()) return
-      // "callAll" event notifications expect the instanceId as first argument
-      const a = isCallAll ? [instanceId, ...innerArgs] : [...innerArgs]
-      VrpcAdapter._callback({ a, s: clientId, i: eventId })
-    }
-  }
-
-  static _registerListener ({
+  static _generateCallback ({
     eventId,
     clientId,
     instanceId,
-    event,
-    isCallAll
+    isCallAll,
+    receiverVersion
   }) {
-    if (!VrpcAdapter._listeners[instanceId]) {
-      VrpcAdapter._listeners[instanceId] = {
-        [eventId]: {
-          event,
-          clients: [clientId],
-          listener: VrpcAdapter._generateListener({
-            eventId,
-            instanceId,
-            isCallAll
-          })
-        }
-      }
-      return VrpcAdapter._listeners[instanceId][eventId].listener
-    }
-    if (!VrpcAdapter._listeners[instanceId][eventId]) {
-      VrpcAdapter._listeners[instanceId][eventId] = {
-        event,
-        clients: [clientId],
-        listener: VrpcAdapter._generateListener({
-          eventId,
-          instanceId,
-          isCallAll
-        })
-      }
-      return VrpcAdapter._listeners[instanceId][eventId].listener
-    }
-    VrpcAdapter._listeners[instanceId][eventId].clients.push(clientId)
-    return VrpcAdapter._listeners[instanceId][eventId].listener
-  }
-
-  static _generateListener ({ eventId, instanceId, isCallAll }) {
     const speaks = VrpcAdapter._speaksFor(instanceId)
     return (...innerArgs) => {
       if (!speaks()) return
+      // "callAll" event notifications expect the instanceId as first argument
       const a = isCallAll ? [instanceId, ...innerArgs] : [...innerArgs]
-      VrpcAdapter._callback({ a, i: eventId })
+      // the receiver's protocol version: whether it can be told of a
+      // callback that cannot travel (CALL-10)
+      VrpcAdapter._callback({ a, s: clientId, i: eventId, receiverVersion })
     }
   }
 
-  static _unregisterListener ({ eventId, clientId, instanceId }) {
-    if (
-      VrpcAdapter._listeners[instanceId] &&
-      VrpcAdapter._listeners[instanceId][eventId]
-    ) {
-      const { listener, clients } = VrpcAdapter._listeners[instanceId][eventId]
-      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]
-        }
-        return listener
-      }
-    }
-  }
-
-  static _removeAllListeners (event, clientId, instanceId) {
-    const eventIds = VrpcAdapter._listeners[instanceId]
-    if (!eventIds) return
-    Object.entries(eventIds).forEach(([ek, ev]) => {
-      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
-          )
-          delete VrpcAdapter._listeners[instanceId][ek]
-        }
-      }
-    })
-  }
-
+  /**
+   * Answers a promise twice: at once with `r: '__p__<f>-<n>'`, and once it
+   * settled with a second answer under that id, `{ s, i, r }` or
+   * `{ s, i, e }`.
+   */
   static _handlePromise (json, promise) {
-    try {
-      const cid = VrpcAdapter._correlationId++ % Number.MAX_SAFE_INTEGER
-      const id = `__p__${json.f}-${cid}`
-      json.r = id
-      promise
-        .then(r => VrpcAdapter._callback({ ...json, r, i: id }))
-        .catch(err => VrpcAdapter._callback({ ...json, e: err.message, i: id }))
-    } catch (err) {
-      json.data.e = err.message
-    }
+    const cid = VrpcAdapter._correlationId++ % Number.MAX_SAFE_INTEGER
+    const id = `__p__${json.f}-${cid}`
+    const { s } = json
+    json.r = id
+    promise.then(
+      r => VrpcAdapter._callback({ s, i: id, r }),
+      err => VrpcAdapter._callback({ s, i: id, e: VrpcAdapter._error(err) })
+    )
   }
 
   static _getClassEntry (className) {
@@ -929,6 +1031,18 @@ class VrpcAdapter {
   static _extractMemberFunctions (klass) {
     let klass_ = klass
     let fs = []
+    // Node's EventEmitter offers subscribing, withdrawing and once to
+    // clients; emit (anyone could fake an event to every subscriber, or emit
+    // 'error' and end the agent) and its internals stay inside the class
+    const isEmitter =
+      klass instanceof EventEmitter ||
+      (!!klass.prototype && klass.prototype instanceof EventEmitter)
+    const published = (names, level) => {
+      if (level === EventEmitter.prototype) {
+        return names.filter(x => VrpcAdapter._emitterPublic.has(x))
+      }
+      return isEmitter ? names.filter(x => x !== 'emit') : names
+    }
     do {
       if (klass_.prototype) {
         const funcs = Object.getOwnPropertyNames(klass_.prototype).filter(
@@ -936,13 +1050,12 @@ class VrpcAdapter {
             !VrpcAdapter._blackList.has(x) &&
             VrpcAdapter._isFunction(klass_.prototype[x])
         )
-        fs = [...fs, ...funcs]
+        fs = [...fs, ...published(funcs, klass_.prototype)]
       } else {
         const funcs = Object.getOwnPropertyNames(klass_).filter(
-          x =>
-            !VrpcAdapter._blackList.has(x) && VrpcAdapter._isFunction(klass_[x])
+          x => !VrpcAdapter._blackList.has(x) && VrpcAdapter._isFunction(klass_[x])
         )
-        fs = [...fs, ...funcs]
+        fs = [...fs, ...published(funcs, klass_)]
       }
       klass_ = Object.getPrototypeOf(klass_)
     } while (klass_)
@@ -954,13 +1067,16 @@ class VrpcAdapter {
     let klass_ = klass
     let fs = []
     do {
-      fs = [
-        ...fs,
-        ...Object.getOwnPropertyNames(klass_).filter(prop => {
-          const desc = Object.getOwnPropertyDescriptor(klass_, prop)
-          return !!desc && typeof desc.value === 'function'
-        })
-      ]
+      // EventEmitter's own statics are Node helpers, not the class's API
+      if (klass_ !== EventEmitter) {
+        fs = [
+          ...fs,
+          ...Object.getOwnPropertyNames(klass_).filter(prop => {
+            const desc = Object.getOwnPropertyDescriptor(klass_, prop)
+            return !!desc && typeof desc.value === 'function'
+          })
+        ]
+      }
       klass_ = Object.getPrototypeOf(klass_)
     } while (klass_ && klass_.name)
     // Filter out all duplicates
@@ -1041,10 +1157,26 @@ VrpcAdapter._functionRegistry = new Map()
 VrpcAdapter._instances = new Map()
 VrpcAdapter._emitter = new EventEmitter()
 VrpcAdapter._correlationId = 0
-VrpcAdapter._listeners = {}
+// the event registrations of every context and their subscriptions
+VrpcAdapter._registrations = new Registrations({
+  publish: message => VrpcAdapter._callback(message),
+  emit: (event, payload) => VrpcAdapter._emitter.emit(event, payload)
+})
 // the longest a delete waits for the dispose method of its instance
 VrpcAdapter.DISPOSE_TIMEOUT = 10000
+// the EventEmitter functions published to clients
+VrpcAdapter._emitterPublic = new Set([
+  'on',
+  'addListener',
+  'off',
+  'removeListener',
+  'once',
+  'removeAllListeners'
+])
 VrpcAdapter._blackList = new Set([
+  // a class's constructor is reached through __createShared__ and
+  // __createIsolated__, never as a member function
+  'constructor',
   'caller',
   'callee',
   'arguments',