vrpc 3.12.1 → 3.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vrpc",
-  "version": "3.12.1",
+  "version": "3.14.0",
   "description": "Variadic Remote Procedure Calls",
   "main": "index.js",
   "directories": {
@@ -12,14 +12,16 @@
     "build:addon": "ln -sf binding.gyp.no-auto binding.gyp && node-gyp rebuild && rm binding.gyp",
     "build:browser": "./node_modules/.bin/webpack --stats-error-details",
     "build:doc": "./node_modules/.bin/jsdoc2md -f vrpc/VrpcAdapter.js vrpc/VrpcAgent.js vrpc/VrpcClient.js vrpc/VrpcNative.js --param-list-format=list --separators > docs/api.md",
-    "test": "npm run test:adapter && npm run test:agent && npm run test:client && npm run test:persistor && npm run test:lifecycle && npm run test:production",
+    "test": "npm run test:adapter && npm run test:reconnect && npm run test:agent && npm run test:client && npm run test:persistor && npm run test:lifecycle && npm run test:legacy-runtime && 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:reconnect": "./node_modules/.bin/mocha tests/reconnect/*.spec.js --exit",
     "test:agent": "tests/agent/test.sh",
     "test:client": "tests/client/test.sh",
     "test:performance": "tests/performance/test.sh",
     "test:persistor": "./node_modules/.bin/mocha tests/persistor/*.js --timeout 30000 --exit",
     "test:lifecycle": "./node_modules/.bin/mocha tests/lifecycle/*.js --timeout 30000 --exit",
+    "test:legacy-runtime": "tests/legacy-runtime/test.sh",
     "test:production": "./node_modules/.bin/mocha tests/production/lifeCycleTest.js --timeout 30000 --exit && tests/production/test.sh"
   },
   "bin": {
@@ -56,6 +58,7 @@
     "fs-extra": "^11.3.1",
     "jsdoc-to-markdown": "^7.0.1",
     "mocha": "^9.2.2",
+    "mqtt-packet": "^9.0.2",
     "os-browserify": "^0.3.0",
     "sinon": "^21.0.0",
     "stream-browserify": "^3.0.0",

package/vrpc/ReconnectBackoff.js

@@ -0,0 +1,79 @@
+/**
+ * Paces the reconnects of an mqtt.js client after refused CONNACKs.
+ *
+ * mqtt.js retries at a fixed `reconnectPeriod`. A connection the broker
+ * refuses - a stale credential, an authorization service that is away -
+ * would knock once per period for as long as it lives, and an
+ * authorization service may block a client id that knocks too often. So
+ * every refusal doubles the wait up to `max`, and a successful connect
+ * restores the base. The refusal itself stays visible as the client's
+ * 'error' event, so a host can renew its credentials and `hurry()`.
+ *
+ * mqtt.js reads `reconnectPeriod` only when it arms its reconnect
+ * interval, once per outage; re-arming it takes the internal
+ * `_clearReconnect` / `_setupReconnect`. Without them (a future mqtt.js)
+ * a new period applies from the next outage on.
+ */
+
+const REFUSED = /^Connection refused/
+
+class ReconnectBackoff {
+  /**
+   * @param {Object} client an mqtt.js client created with
+   *   `reconnectOnConnackError: true`
+   * @param {Object} [options]
+   * @param {Number} [options.max=30000] longest wait in ms between attempts
+   */
+  constructor (client, { max = 30000 } = {}) {
+    this._client = client
+    this._base = client.options.reconnectPeriod
+    this._max = Math.max(max, this._base)
+    this._next = this._base
+    client.on('error', err => {
+      if (ReconnectBackoff.isRefusal(err)) this._slowDown()
+    })
+    client.on('connect', () => this._restore())
+  }
+
+  /** Whether an mqtt.js error is a refused CONNACK. */
+  static isRefusal (err) {
+    return (
+      !!err && typeof err.code === 'number' && REFUSED.test(err.message || '')
+    )
+  }
+
+  /** The wait in ms before the next attempt. */
+  get period () {
+    return this._client.options.reconnectPeriod
+  }
+
+  /**
+   * New credentials: the next attempt follows within the base period
+   * instead of waiting out the back-off. A live connection stays as it is.
+   */
+  hurry () {
+    this._restore()
+    const client = this._client
+    if (client.connected || client.disconnecting || !client.reconnecting) return
+    if (typeof client._clearReconnect !== 'function') return
+    client._clearReconnect()
+    client._setupReconnect()
+  }
+
+  // Runs inside the CONNACK handler's 'error' emit: the handler re-arms
+  // the reconnect interval right after (reconnectOnConnackError), with the
+  // period set here
+  _slowDown () {
+    const client = this._client
+    client.options.reconnectPeriod = this._next
+    this._next = Math.min(this._next * 2, this._max)
+    if (typeof client._clearReconnect === 'function') client._clearReconnect()
+  }
+
+  _restore () {
+    this._next = this._base
+    this._client.options.reconnectPeriod = this._base
+  }
+}
+
+module.exports = ReconnectBackoff

package/vrpc/VrpcAdapter.js

@@ -43,6 +43,17 @@ const commentParser = require('./comment-parser')
 const EventEmitter = require('events')
 const { nanoid } = require('nanoid')
 
+// Node before 18.18 / 20.4 has no dispose symbols, and a class's
+// [Symbol.asyncDispose]() would become a method named 'undefined'. Node's
+// own stand-ins live in the symbol registry, so a class file and the adapter
+// meet on one symbol whichever of them installs it first.
+if (typeof Symbol.dispose !== 'symbol') {
+  Symbol.dispose = Symbol.for('nodejs.dispose')
+}
+if (typeof Symbol.asyncDispose !== 'symbol') {
+  Symbol.asyncDispose = Symbol.for('nodejs.asyncDispose')
+}
+
 /**
  * Generates an adapter layer for existing code and enables further VRPC-based
  * communication.
@@ -197,7 +208,10 @@ class VrpcAdapter {
   }
 
   /**
-   * Deletes an instance
+   * Deletes an instance: its name is free at once, the adapter takes back
+   * every listener it attached, and the object releases what it runs
+   * through its `[Symbol.asyncDispose]` or `[Symbol.dispose]` method, which
+   * runs in the background here (a remote delete answers once it settled).
    *
    * @param {String|Object} instance Instance (name or object itself) to be deleted
    * @returns {Boolean} True in case of success, false otherwise
@@ -208,10 +222,7 @@ class VrpcAdapter {
     }
     if (typeof instance === 'object') {
       for (const [k, v] of VrpcAdapter._instances) {
-        if (v.instance === instance) {
-          VrpcAdapter._instances.delete(k)
-          return true
-        }
+        if (v.instance === instance) return VrpcAdapter._delete(k)
       }
       return false
     }
@@ -577,11 +588,17 @@ class VrpcAdapter {
         instance,
         className: json.c
       })
-      json.r = VrpcAdapter._delete(instance)
+      const { ended, disposed } = VrpcAdapter._end(instance)
       VrpcAdapter._emitter.emit('delete', {
         instance,
         className: json.c
       })
+      // a delete answers once the object released what it runs, so that a
+      // constructor right after it never meets a port or a session the old
+      // object still holds; the agent's own housekeeping awaits no answer
+      if (disposed && json.s !== VrpcAdapter.LOCAL_SENDER) {
+        VrpcAdapter._handlePromise(json, disposed.then(() => ended))
+      } else json.r = ended
     } catch (err) {
       const { message, cause } = err
       json.e = { message, cause }
@@ -603,6 +620,15 @@ class VrpcAdapter {
       json.r = true
       return
     }
+    // an unknown context fails before its arguments are unwrapped: a
+    // listener registered for a name that does not exist would outlive the
+    // failed call and pass for attached once the name is created
+    if (
+      !VrpcAdapter._functionRegistry.has(json.c) &&
+      !VrpcAdapter._instances.has(json.c)
+    ) {
+      throw new Error(`Could not find context: ${json.c}`)
+    }
     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
@@ -671,33 +697,115 @@ class VrpcAdapter {
   }
 
   static _delete (instanceId) {
+    return VrpcAdapter._end(instanceId).ended
+  }
+
+  /**
+   * 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). Node has no destructor, so an object that runs a
+   * 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);
+   * 3. the object releases what it runs through the ECMAScript dispose
+   *    protocol, `[Symbol.asyncDispose]` or else `[Symbol.dispose]`.
+   *
+   * @returns {Object} `{ ended, disposed }`: whether the name was known, and
+   * a promise when an asynchronous dispose is under way (it never rejects)
+   */
+  static _end (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()
+    if (!entry) return { ended: false, disposed: null }
+    VrpcAdapter._instances.delete(instanceId)
+    VrpcAdapter._detachListeners(instanceId, entry.instance)
+    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
       }
-      delete VrpcAdapter._listeners[instanceId]
-      VrpcAdapter._instances.delete(instanceId)
-      return true
     }
-    return false
+  }
+
+  // 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
+   * never thrown: the instance is gone either way.
+   *
+   * @returns {Promise|null} Settles when an asynchronous dispose is done
+   */
+  static _dispose (instanceId, { instance, className }) {
+    const fail = error =>
+      VrpcAdapter._emitter.emit('disposeFailed', {
+        instance: instanceId,
+        className,
+        error
+      })
+    let result
+    try {
+      if (VrpcAdapter._isFunction(instance[Symbol.asyncDispose])) {
+        result = instance[Symbol.asyncDispose]()
+      } else if (VrpcAdapter._isFunction(instance[Symbol.dispose])) {
+        result = instance[Symbol.dispose]()
+      }
+    } catch (err) {
+      fail(err)
+      return null
+    }
+    if (!VrpcAdapter._isPromise(result)) return null
+    let timer
+    const bound = new Promise(resolve => {
+      timer = setTimeout(() => {
+        fail(
+          new Error(
+            `dispose did not settle within ${VrpcAdapter.DISPOSE_TIMEOUT} ms`
+          )
+        )
+        resolve()
+      }, VrpcAdapter.DISPOSE_TIMEOUT)
+    })
+    const settled = result.then(
+      () => {},
+      err => fail(err)
+    )
+    return Promise.race([settled, bound]).then(() => clearTimeout(timer))
   }
 
   static _unregisterClient (clientId) {
     Object.entries(VrpcAdapter._listeners).forEach(([ik, iv]) => {
       Object.entries(iv).forEach(([ek, ev]) => {
-        const { clients, listener, event } = ev
-        const index = clients.indexOf(clientId)
-        if (index !== -1) {
-          clients.splice(index, 1)
-          if (clients.length === 0) {
-            const instance = VrpcAdapter.getInstance(ik)
-            if (instance && instance.removeListener) {
-              instance.removeListener(event, listener)
-            }
-            delete VrpcAdapter._listeners[ik][ek]
+        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]
         }
       })
     })
@@ -774,8 +882,27 @@ class VrpcAdapter {
     return unwrapped
   }
 
+  /**
+   * Whether the object under `instanceId` is still the one the adapter saw
+   * when it built a listener or a callback for it: a deleted instance never
+   * speaks on the bus again (#1705), even when its class kept the listener
+   * or its clock kept running. A static context (a class name) has no
+   * object and always speaks.
+   */
+  static _speaksFor (instanceId) {
+    const entry = VrpcAdapter._instances.get(instanceId)
+    if (!entry) return () => true
+    const { instance } = entry
+    return () => {
+      const live = VrpcAdapter._instances.get(instanceId)
+      return live !== undefined && live.instance === instance
+    }
+  }
+
   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 })
@@ -820,7 +947,9 @@ class VrpcAdapter {
   }
 
   static _generateListener ({ eventId, instanceId, isCallAll }) {
+    const speaks = VrpcAdapter._speaksFor(instanceId)
     return (...innerArgs) => {
+      if (!speaks()) return
       const a = isCallAll ? [instanceId, ...innerArgs] : [...innerArgs]
       VrpcAdapter._callback({ a, i: eventId })
     }
@@ -1003,12 +1132,28 @@ class VrpcAdapter {
  * @property {String} instance The instance name
  */
 
+/**
+ * Event 'disposeFailed'
+ *
+ * Emitted when the dispose method of a deleted instance throws, rejects or
+ * does not settle within VrpcAdapter.DISPOSE_TIMEOUT. The instance is gone
+ * regardless.
+ *
+ * @event VrpcAdapter#disposeFailed
+ * @type {Object}
+ * @property {String} className The class name of the deleted instance
+ * @property {String} instance The instance name
+ * @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 longest a delete waits for the dispose method of its instance
+VrpcAdapter.DISPOSE_TIMEOUT = 10000
 VrpcAdapter._blackList = new Set([
   'caller',
   'callee',

package/vrpc/VrpcAgent.js

@@ -7,6 +7,7 @@ const EventEmitter = require('events')
 const jsonStringifySafe = require('json-stringify-safe')
 const VrpcAdapter = require('./VrpcAdapter')
 const SubscribeRetrier = require('./SubscribeRetrier')
+const ReconnectBackoff = require('./ReconnectBackoff')
 
 const VRPC_PROTOCOL_VERSION = 3
 
@@ -145,6 +146,13 @@ class VrpcAgent extends EventEmitter {
     }
     this._baseTopic = `${this._domain}/${this._agent}`
     VrpcAdapter.onCallback(this._handleVrpcCallback.bind(this))
+    // a deleted instance whose dispose failed is gone anyway: say why
+    this._handleDisposeFailed = ({ instance, className, error }) =>
+      this._log.warn(
+        error,
+        `Dispose of deleted instance ${className}::${instance} failed: ${error.message}`
+      )
+    VrpcAdapter.on('disposeFailed', this._handleDisposeFailed)
     // maps clientId to instanceId
     this._isolatedInstances = new Map()
     this._sharedInstances = new Map()
@@ -214,6 +222,8 @@ class VrpcAgent extends EventEmitter {
     this._log.info(`Broker : ${this._broker}`)
     this._log.info('Connecting to MQTT server...')
     this._client = mqtt.connect(this._broker, this._options)
+    // a refused agent knocks less and less often, not once a second
+    this._backoff = new ReconnectBackoff(this._client)
     this._client.on('connect', this._handleConnect.bind(this))
     this._client.on('reconnect', this._handleReconnect.bind(this))
     this._client.on('error', this._handleError.bind(this))
@@ -232,10 +242,19 @@ class VrpcAgent extends EventEmitter {
    * @returns {Promise} Resolves when disconnected and ended
    */
   async end ({ unregister = false } = {}) {
+    VrpcAdapter.off('disposeFailed', this._handleDisposeFailed)
     this._subscribeRetrier.cancel()
     try {
       if (!this._client || !this._client.connected) {
-        this.emit('end')
+        // a client that is still trying (refused, broker away) stops
+        // trying: end() is how a refusal becomes final
+        // (its 'end' is forwarded as the agent's)
+        if (this._client) {
+          const client = this._client
+          await new Promise(resolve => client.end(true, {}, resolve))
+        } else {
+          this.emit('end')
+        }
         return
       }
       const agentTopic = `${this._baseTopic}/__agentInfo__`
@@ -744,7 +763,9 @@ class VrpcAgent extends EventEmitter {
       const entry = this._isolatedInstances.get(connectionId)
       if (entry) {
         entry.forEach(instanceId => {
+          const known = VrpcAdapter._instances.get(instanceId)
           const json = {
+            c: known && known.className,
             f: '__delete__',
             a: [instanceId],
             r: null,
@@ -752,6 +773,8 @@ class VrpcAgent extends EventEmitter {
           }
           VrpcAdapter._call(json)
           if (json.r) {
+            // gone like a remote delete: no request topic outlives it
+            this._unsubscribeMethodsOfDeletedInstance(known.className, instanceId)
             this._log.debug(`Auto-deleted isolated instance: ${instanceId}`)
           }
         })