vrpc 3.13.0 → 3.15.0

package/vrpc/VrpcAdapter.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
@@ -42,6 +42,8 @@ const caller = require('caller')
 const commentParser = require('./comment-parser')
 const EventEmitter = require('events')
 const { nanoid } = require('nanoid')
+const Registrations = require('./Registrations')
+const NamePattern = require('./namePattern')
 
 // Node before 18.18 / 20.4 has no dispose symbols, and a class's
 // [Symbol.asyncDispose]() would become a method named 'undefined'. Node's
@@ -97,14 +99,16 @@ class VrpcAdapter {
    * @param {Any} code Existing code to be registered, can be a class
    * or function object or a relative path to a module
    * @param {Object} [options]
-   * @param {Boolean} [options.onlyPublic=true] If true, only registers
-   * functions that do not begin with an underscore
+   * @param {Boolean} [options.onlyPublic=true] If true, only registers public
+   * functions: none whose name begins with an underscore, and - when the
+   * JSDoc is read - none tagged `@private` or `@access private`
    * @param {Boolean} [options.withNew=true] If true, class will be constructed
    * using the `new` operator
    * @param {Object} [options.schema=null] If provided is used to validate ctor
    * parameters (only works if registered code reflects a single class)
-   * @param {String} options.jsdocPath if provided, parses documentation and
-   * provides it as meta information
+   * @param {String} [options.jsdocPath] if provided, parses documentation and
+   * provides it as meta information; a code given by path has its JSDoc read
+   * without
    *
    * NOTE: This function currently only supports registration of classes (either
    * when provided as object or when exported on the provided module path)
@@ -135,8 +139,9 @@ class VrpcAdapter {
    * @param {Object} options
    * @param {String} options.className Class name of the instance
    * @param {String} options.instance Name of the instance
-   * @param {Boolean} [options.onlyPublic=true] If true, only registers
-   * functions that do not begin with an underscore
+   * @param {Boolean} [options.onlyPublic=true] If true, only registers public
+   * functions: none whose name begins with an underscore, and - when the
+   * JSDoc is read - none tagged `@private` or `@access private`
    * @param {String} [options.jsdocPath] if provided, parses documentation and
    * provides it as meta information
    */
@@ -144,18 +149,17 @@ class VrpcAdapter {
     obj,
     { className, instance, jsdocPath, onlyPublic = true } = {}
   ) {
-    let memberFunctions = VrpcAdapter._extractMemberFunctions(obj)
-    if (onlyPublic) {
-      memberFunctions = memberFunctions.filter(f => {
-        return !f.startsWith('_')
-      })
-    }
-    let meta = null
+    let docs = null
     if (jsdocPath) {
       const absJsdocPath = path.resolve(caller(), '../', jsdocPath)
       const content = fs.readFileSync(absJsdocPath).toString('utf8')
-      meta = this._parseComments(content)
+      docs = VrpcAdapter._readDocs(content, obj.constructor && obj.constructor.name)
+    }
+    let memberFunctions = VrpcAdapter._extractMemberFunctions(obj)
+    if (onlyPublic) {
+      memberFunctions = VrpcAdapter._onlyPublic(memberFunctions, docs, 'member')
     }
+    const meta = docs ? VrpcAdapter._metaOf(docs.meta, memberFunctions) : null
     if (!VrpcAdapter._functionRegistry.has(className)) {
       VrpcAdapter._functionRegistry.set(className, {
         memberFunctions,
@@ -304,6 +308,13 @@ class VrpcAdapter {
    * @param {String} [type] Return value type
    */
 
+  /**
+   * Listens to an event of the adapter: `create`, `beforeDelete`,
+   * `delete`, `disposeFailed`, `releaseFailed` or `greetFailed`
+   *
+   * @param {String} eventName The event
+   * @param {Function} listener Called with the event's payload
+   */
   static on (eventName, listener) {
     VrpcAdapter._emitter.on(eventName, listener)
   }
@@ -328,26 +339,30 @@ class VrpcAdapter {
     { onlyPublic = true, withNew = true, schema = null, jsdoc = true } = {}
   ) {
     // Get all static static functions
+    const docs =
+      jsdoc && absJsdocPath
+        ? VrpcAdapter._readDocs(
+          fs.readFileSync(absJsdocPath).toString('utf8'),
+          Klass.name
+        )
+        : null
     let staticFunctions = VrpcAdapter._extractStaticFunctions(Klass)
     if (onlyPublic) {
-      staticFunctions = staticFunctions.filter(f => !f.startsWith('_'))
+      staticFunctions = VrpcAdapter._onlyPublic(staticFunctions, docs, 'static')
     }
     // Inject constructor and destructor
     staticFunctions.push('__createIsolated__')
     staticFunctions.push('__createShared__')
     staticFunctions.push('__callAll__')
+    staticFunctions.push('__callMatching__')
     staticFunctions.push('__delete__')
     let memberFunctions = VrpcAdapter._extractMemberFunctions(Klass)
     if (onlyPublic) {
-      memberFunctions = memberFunctions.filter(f => {
-        return !f.startsWith('_')
-      })
-    }
-    let meta = null
-    if (jsdoc && absJsdocPath) {
-      const content = fs.readFileSync(absJsdocPath).toString('utf8')
-      meta = this._parseComments(content)
+      memberFunctions = VrpcAdapter._onlyPublic(memberFunctions, docs, 'member')
     }
+    const meta = docs
+      ? VrpcAdapter._metaOf(docs.meta, [...staticFunctions, ...memberFunctions])
+      : null
     VrpcAdapter._functionRegistry.set(Klass.name, {
       Klass,
       withNew,
@@ -358,8 +373,72 @@ class VrpcAdapter {
     })
   }
 
-  static _parseComments (content) {
-    const comments = commentParser(content, { assocFunctions: true })
+  /**
+   * The public of some functions: none beginning with an underscore, and
+   * none the class's JSDoc tags `@private` (when it was read)
+   */
+  static _onlyPublic (functions, docs, kind) {
+    return functions.filter(
+      f => !f.startsWith('_') && !(docs && docs.privates[kind].has(f))
+    )
+  }
+
+  /**
+   * The meta data of the published functions only: a hidden function's
+   * documentation stays inside the agent as well
+   */
+  static _metaOf (meta, published) {
+    return Object.fromEntries(
+      Object.entries(meta).filter(
+        ([name]) => name === '__createShared__' || published.includes(name)
+      )
+    )
+  }
+
+  /**
+   * The meta data of the functions a source documents (see `_readDocs`)
+   */
+  static _parseComments (content, className) {
+    return VrpcAdapter._readDocs(content, className).meta
+  }
+
+  /**
+   * Reads the JSDoc of a class's source: the meta data of its functions, and
+   * the functions tagged `@private` (or `@access private`), which stay off
+   * its class info and so cannot be called. A comment counts for the class
+   * whose body it is in; in a source that declares no class, and when no
+   * class name is given, every comment counts.
+   *
+   * @param {String} content the source
+   * @param {String} [className] the class to read the documentation of
+   * @returns {{ meta: Object, privates: { member: Set, static: Set } }}
+   */
+  static _readDocs (content, className) {
+    const declaresClasses = content
+      .split('\n')
+      .some(line => commentParser.CLASS_DECLARATION.test(line))
+    const comments = commentParser(content, { assocFunctions: true }).filter(
+      ({ functionName, className: owner }) =>
+        !functionName ||
+        className === undefined ||
+        owner === className ||
+        (!owner && !declaresClasses)
+    )
+    const privates = { member: new Set(), static: new Set() }
+    comments.forEach(({ tags, functionName, isStatic, className: owner }) => {
+      if (!functionName || functionName === 'constructor' || !tags) return
+      const hidden = tags.some(
+        ({ tag, name }) =>
+          tag === 'private' || (tag === 'access' && name === 'private')
+      )
+      if (!hidden) return
+      if (owner) {
+        privates[isStatic ? 'static' : 'member'].add(functionName)
+      } else {
+        privates.member.add(functionName)
+        privates.static.add(functionName)
+      }
+    })
     const meta = {}
     const paramsOf = tags =>
       tags
@@ -418,11 +497,38 @@ class VrpcAdapter {
         }
       }
     })
-    return meta
+    return { meta, privates }
   }
 
+  /**
+   * 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) {
     this._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 this._mustTrackClient
+  }
+
+  static _dispatch (json) {
     switch (json.f) {
       case '__createIsolated__':
         VrpcAdapter._handleCreateIsolated(json)
@@ -433,16 +539,48 @@ 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 this._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, or a static
+   * function of the class. 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)
   }
 
   /**
@@ -461,11 +599,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
@@ -504,6 +659,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`)
@@ -528,35 +684,75 @@ class VrpcAdapter {
     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(
@@ -572,18 +768,117 @@ class VrpcAdapter {
   }
 
   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) {
+      const { message, cause } = err
+      json.e = { message, cause }
+    }
+  }
+
+  /**
+   * `__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) {
+      const { message, cause } = err
+      json.e = { message, cause }
+    }
   }
 
   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
@@ -614,9 +909,16 @@ class VrpcAdapter {
       json.e = { message, cause }
       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
     }
@@ -629,6 +931,49 @@ class VrpcAdapter {
     ) {
       throw new Error(`Could not find context: ${json.c}`)
     }
+    // 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 {
+      const entry = VrpcAdapter._instances.get(json.c)
+      if (entry === undefined) {
+        throw new Error(`Could not find context: ${json.c}`)
+      }
+      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)) {
+          this._handlePromise(json, value)
+        } else json.r = value
+      } catch (err) {
+        const { message, cause } = err
+        json.e = { message, cause }
+      }
+      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
@@ -641,47 +986,23 @@ class VrpcAdapter {
       json.r = true
       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)) {
-            this._handlePromise(json, ret)
-          } else json.r = ret
-        } catch (err) {
-          const { message, cause } = err
-          json.e = { message, cause }
-        }
-      } else throw new Error(`Could not find function: ${json.f}`)
-    } 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)) {
-            this._handlePromise(json, ret)
-          } else json.r = ret
-        } catch (err) {
-          const { message, cause } = err
-          json.e = { message, cause }
-        }
-      } else throw new Error(`Could not find function: ${json.f}`)
+    // 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)) {
+        this._handlePromise(json, ret)
+      } else json.r = ret
+    } catch (err) {
+      const { message, cause } = err
+      json.e = { message, cause }
     }
   }
 
@@ -707,10 +1028,13 @@ class VrpcAdapter {
    * clock or holds a connection lives on as long as anything reaches it;
    * ending it takes three steps:
    * 1. its name is free at once: no call reaches the object any more;
-   * 2. the adapter takes back every listener it attached (its listeners are
-   *    silent from now on anyway, see _generateListener);
+   * 2. the adapter forgets the instance's registrations (their listeners
+   *    are silent from now on, see Registrations); it releases them itself
+   *    only for an object without a dispose method (legacy), and always
+   *    takes back what it attached through Node's own `on`;
    * 3. the object releases what it runs through the ECMAScript dispose
    *    protocol, `[Symbol.asyncDispose]` or else `[Symbol.dispose]`.
+   * Its subscribers learn the loss from the class info (instance gone).
    *
    * @returns {Object} `{ ended, disposed }`: whether the name was known, and
    * a promise when an asynchronous dispose is under way (it never rejects)
@@ -719,33 +1043,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
@@ -790,25 +1097,12 @@ class VrpcAdapter {
     return Promise.race([settled, bound]).then(() => clearTimeout(timer))
   }
 
+  /**
+   * A client connection went: every subscription it held is withdrawn, and
+   * a registration whose last subscription that was is released.
+   */
   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) {
@@ -819,6 +1113,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
@@ -829,53 +1124,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(
-            this._generateCallback({
-              clientId,
-              isCallAll,
-              instanceId: context,
-              eventId: arg
-            })
-          )
-        } else if (arg.startsWith('__e__')) {
-          // event registration
-          if (func === 'on' || func === 'addListener') {
-            this._mustTrackClient = true
-            const listener = VrpcAdapter._registerListener({
-              clientId,
-              isCallAll,
-              instanceId: context,
-              eventId: arg,
-              event: args[0]
-            })
-            unwrapped.push(listener)
-            // event un-registration
-          } else if (func === 'off' || func === 'removeListener') {
-            const listener = VrpcAdapter._unregisterListener({
-              clientId,
-              instanceId: context,
-              eventId: arg
-            })
-            unwrapped.push(listener)
-          } else {
-            this._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(
+          this._generateCallback({
+            clientId,
+            isCallAll,
+            instanceId: context,
+            eventId: arg,
+            receiverVersion: json.v
+          })
+        )
       } else {
-        // regular argument
         unwrapped.push(arg)
       }
     }
@@ -899,112 +1158,38 @@ class VrpcAdapter {
     }
   }
 
-  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 })
-    }
-  }
-
-  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
+      // 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 _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)
-        VrpcAdapter.getInstance(instanceId).removeAllListeners(ev.event)
-        if (ev.clients.length === 0) {
-          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: { message: err.message, cause: err.cause },
-            i: id
-          })
-        )
-    } catch (err) {
-      const { message, cause } = err
-      json.data.e = { message, cause }
-    }
+    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) {
@@ -1040,6 +1225,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(
@@ -1047,12 +1244,12 @@ class VrpcAdapter {
             !VrpcAdapter._blackList.has(x) &&
             this._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) && this._isFunction(klass_[x])
         )
-        fs = [...fs, ...funcs]
+        fs = [...fs, ...published(funcs, klass_)]
       }
       klass_ = Object.getPrototypeOf(klass_)
     } while (klass_)
@@ -1064,13 +1261,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
@@ -1121,11 +1321,23 @@ class VrpcAdapter {
  */
 
 /**
- * Event 'delete'
+ * Event 'beforeDelete'
  *
- * Emitted on deletion of shared instance
+ * Emitted when a deletion through the agent begins, while the instance can
+ * still be reached
  *
  * @event VrpcAdapter#beforeDelete
+ * @type {Object}
+ * @property {String} className The class name of the instance
+ * @property {String} instance The instance name
+ */
+
+/**
+ * Event 'delete'
+ *
+ * Emitted once an instance was deleted through the agent (a client's delete,
+ * or an isolated instance whose owner went)
+ *
  * @event VrpcAdapter#delete
  * @type {Object}
  * @property {String} className The class name of the deleted instance
@@ -1146,15 +1358,59 @@ class VrpcAdapter {
  * @property {Error} error What went wrong
  */
 
+/**
+ * Event 'releaseFailed'
+ *
+ * Emitted when the release of an event registration threw or rejected; the
+ * registration is gone anyway
+ *
+ * @event VrpcAdapter#releaseFailed
+ * @type {Object}
+ * @property {String} context The instance (or class) of the registration
+ * @property {String} function The event function
+ * @property {Array.<Any>} args Its arguments, without handlers
+ * @property {Error} error What went wrong
+ */
+
+/**
+ * Event 'greetFailed'
+ *
+ * Emitted when a registration's greeting threw or rejected; the subscriber
+ * stays subscribed
+ *
+ * @event VrpcAdapter#greetFailed
+ * @type {Object}
+ * @property {String} context The instance (or class) of the registration
+ * @property {String} function The event function
+ * @property {Array.<Any>} args Its arguments, without handlers
+ * @property {Error} error What went wrong
+ */
+
 // Initialize static members
 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',
@@ -1177,6 +1433,8 @@ VrpcAdapter._blackList = new Set([
  * The sender the agent uses for its own housekeeping calls (deleting the
  * isolated instances of a departed connection). A Symbol: no message from
  * the wire can carry it, so it can never be claimed remotely.
+ *
+ * @private
  */
 VrpcAdapter.LOCAL_SENDER = Symbol('vrpc.local-sender')