vrpc 3.12.1 → 3.14.0

package/vrpc/VrpcBrowserAdapter.js

@@ -39,6 +39,16 @@ const Ajv = require('ajv')
 const EventEmitter = require('events')
 const { nanoid } = require('nanoid')
 
+// 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
+// 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')
+}
+
 const VRPC_GLOBAL = '__global__'
 const VRPC_WINDOW_NS = 'vrpc'
 
@@ -188,7 +198,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
@@ -199,10 +212,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
     }
@@ -457,11 +467,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 resource 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) {
       json.e = err.message
     }
@@ -482,6 +498,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)
     if (!unwrapped) {
       // this call must be skipped (event emitter stuff)
@@ -557,33 +582,112 @@ 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): 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
+   * 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]
         }
       })
     })
@@ -622,6 +726,7 @@ class VrpcAdapter {
           // event registration
           if (func === 'on' || func === 'addListener') {
             VrpcAdapter._mustTrackClient = true
+            const held = VrpcAdapter._holdsListener(context, arg)
             const listener = VrpcAdapter._registerListener({
               clientId,
               isCallAll,
@@ -629,9 +734,8 @@ class VrpcAdapter {
               eventId: arg,
               event: args[0]
             })
-            if (!listener) {
-              return null // skip call as listener is already registered
-            }
+            // 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') {
@@ -666,8 +770,32 @@ 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, 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 _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 })
@@ -708,11 +836,13 @@ class VrpcAdapter {
       return VrpcAdapter._listeners[instanceId][eventId].listener
     }
     VrpcAdapter._listeners[instanceId][eventId].clients.push(clientId)
-    return null
+    return VrpcAdapter._listeners[instanceId][eventId].listener
   }
 
   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 })
     }
@@ -892,12 +1022,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/VrpcBrowserAgent.js

@@ -68,6 +68,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()
@@ -146,6 +153,7 @@ class VrpcAgent extends EventEmitter {
    * @returns {Promise} Resolves when disconnected and ended
    */
   async end ({ unregister = false } = {}) {
+    VrpcAdapter.off('disposeFailed', this._handleDisposeFailed)
     try {
       if (!this._client || !this._client.connected) {
         this.emit('end')
@@ -542,7 +550,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,
@@ -550,6 +560,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}`)
           }
         })

package/vrpc/VrpcClient.js

@@ -40,9 +40,14 @@ const { nanoid } = require('nanoid')
 const mqtt = require('mqtt')
 const EventEmitter = require('events')
 const SubscribeRetrier = require('./SubscribeRetrier')
+const ReconnectBackoff = require('./ReconnectBackoff')
 
 const VRPC_PROTOCOL_VERSION = 3
 
+// mqtt clients this client ended on purpose: the 'client disconnecting'
+// workaround must never revive one of them
+const ENDED = new WeakSet()
+
 /**
  * Client capable of creating proxy objects and remotely calling
  * functions as provided through one or more (distributed) agents.
@@ -220,7 +225,19 @@ class VrpcClient extends EventEmitter {
   /**
    * Actually connects to the MQTT broker.
    *
+   * A refused connection is retried with a growing wait (doubling up to
+   * 30 s, back to the start once connected), and every refusal is emitted
+   * as 'error', so a caller can renew its credentials (see
+   * updateCredentials).
+   *
    * @emits connected
+   * @param {Object} [options]
+   * @param {Boolean} [options.keepTrying=false] If true, a connection that
+   * is not made within [timeout] still rejects the returned promise, but
+   * keeps trying until end() and emits 'connect' once it stands, and a
+   * further connect({ keepTrying: true }) while it is trying waits for it
+   * instead of opening a second connection. If false (the default), nothing
+   * changes: the client gives up at the timeout and must be connected again.
    * @returns {Promise} Resolves once connected within [timeout], rejects otherwise
    * @example
    * try {
@@ -229,14 +246,14 @@ class VrpcClient extends EventEmitter {
    *   console.error(`Could not connect because: ${err.message}`)
    * }
    */
-  async connect () {
+  async connect ({ keepTrying = false } = {}) {
     if (this._client && this._client.connected) return
-    let username = this._username
-    let password = this._password
-    if (this._token) {
-      username = username || this._generateUserName()
-      password = this._token
+    // keepTrying: a connection that is still trying is waited for, never
+    // doubled (without it, connect() behaves as it always did)
+    if (keepTrying && this._client && !ENDED.has(this._client)) {
+      return this._awaitConnect(this._client, { keepTrying })
     }
+    const { username, password } = this._credentials()
     const options = {
       username,
       password,
@@ -264,6 +281,7 @@ class VrpcClient extends EventEmitter {
     })
 
     this._client = mqtt.connect(this._broker, options)
+    this._backoff = new ReconnectBackoff(this._client)
 
     // Persistent lifecycle handlers
     this._client.on('offline', () => {
@@ -393,25 +411,78 @@ class VrpcClient extends EventEmitter {
       }
     })
 
+    return this._awaitConnect(this._client, { keepTrying })
+  }
+
+  _awaitConnect (client, { keepTrying }) {
     return new Promise((resolve, reject) => {
       const timeout = setTimeout(() => {
         // This will run only if the 'connect' event isn't fired in time.
+        const error = new Error(
+          `Connection trial timed out (> ${this._timeout} ms)`
+        )
+        if (keepTrying) {
+          // the client keeps trying in the background, until end()
+          client.removeListener('connect', onConnect)
+          reject(error)
+          return
+        }
         // We explicitly end the client to stop it from retrying in the background.
-        this._client.end(true, () => {
-          reject(
-            new Error(`Connection trial timed out (> ${this._timeout} ms)`)
-          )
-        })
+        VrpcClient._endMqtt(client, true, {}, () => reject(error))
       }, this._timeout)
 
-      this._client.once('connect', () => {
+      const onConnect = () => {
         // If we connect successfully, clear the timeout and resolve the promise.
         clearTimeout(timeout)
         resolve()
-      })
+      }
+      client.once('connect', onConnect)
     })
   }
 
+  /**
+   * Replaces the credentials the connection logs in with
+   *
+   * The broker checks credentials when a connection is made: a live
+   * connection carries on undisturbed, and the next one - after a network
+   * loss, a broker restart - logs in with these. A connection that is
+   * being refused right now tries again with them within a second,
+   * instead of waiting out its back-off.
+   *
+   * @param {Object} credentials Only the given fields change
+   * @param {String} [credentials.username] MQTT username
+   * @param {String} [credentials.password] MQTT password (if no token is used)
+   * @param {String} [credentials.token] Access token
+   */
+  updateCredentials ({ username, password, token } = {}) {
+    if (username !== undefined) this._username = username
+    if (password !== undefined) this._password = password
+    if (token !== undefined) this._token = token
+    if (!this._client || ENDED.has(this._client)) return
+    const credentials = this._credentials()
+    for (const key of ['username', 'password']) {
+      if (credentials[key] === undefined) delete this._client.options[key]
+      else this._client.options[key] = credentials[key]
+    }
+    this._backoff.hurry()
+  }
+
+  // what the broker sees: a token rides as the password
+  _credentials () {
+    let username = this._username
+    let password = this._password
+    if (this._token) {
+      username = username || this._generateUserName()
+      password = this._token
+    }
+    return { username, password }
+  }
+
+  static _endMqtt (client, force, options, callback) {
+    ENDED.add(client)
+    client.end(force, options, callback)
+  }
+
   /**
    * Creates a new remote instance and provides a proxy to it.
    *
@@ -546,7 +617,27 @@ class VrpcClient extends EventEmitter {
     const topic = `${this._domain}/${agent}/${className}/__static__/__delete__`
     this._mqttPublish(topic, JSON.stringify(json))
     delete this._proxies[`${agent}/${className}/${instance}`]
-    return this._handleAgentAnswer(json, agent)
+    const deleted = await this._handleAgentAnswer(json, agent)
+    // the answer and the class info that no longer lists the instance
+    // travel on different topics, and a broker need not keep their order:
+    // what this client deleted is gone for it at once
+    if (deleted === true) this._forgetInstance({ agent, className, instance })
+    return deleted
+  }
+
+  /**
+   * Takes an instance off this client's view of its agent, the way a class
+   * info without it does: listing, instanceGone, cached subscriptions. A
+   * class info that arrives later finds nothing left to remove.
+   */
+  _forgetInstance ({ agent, className, instance }) {
+    const info = this._agents[agent] && this._agents[agent].classes[className]
+    if (!info || !Array.isArray(info.instances)) return
+    if (!info.instances.includes(instance)) return
+    info.instances = info.instances.filter(x => x !== instance)
+    const domain = this._domain
+    this.emit('instanceGone', [instance], { domain, agent, className })
+    this._clearCachedSubscriptions({ lostInstance: instance, agent, className })
   }
 
   /**
@@ -795,7 +886,10 @@ class VrpcClient extends EventEmitter {
     this._token = token
     this._agent = agent
     if (this._client) {
-      await new Promise(resolve => this._client.end(false, {}, resolve))
+      const client = this._client
+      await new Promise(resolve =>
+        VrpcClient._endMqtt(client, false, {}, resolve)
+      )
     }
     return this.connect()
   }
@@ -842,7 +936,9 @@ class VrpcClient extends EventEmitter {
     this.removeAllListeners()
     const client = this._client
     this._client = null // Prevent race conditions during shutdown
-    return new Promise(resolve => client.end(false, {}, resolve))
+    return new Promise(resolve =>
+      VrpcClient._endMqtt(client, false, {}, resolve)
+    )
   }
 
   // Private functions
@@ -909,8 +1005,16 @@ class VrpcClient extends EventEmitter {
     return `${this._domain}/${this._mqttClientId}/${this._connectionSecret}`
   }
 
+  // The 'client disconnecting' workaround below revives a client mqtt.js
+  // left half-closed, never one that was ended on purpose (a connect
+  // timeout, end(), reconnectWithToken) or has been replaced since
+  _isRevivable (client) {
+    return client === this._client && !ENDED.has(client)
+  }
+
   _mqttPublish (topic, message, options) {
-    this._client.publish(
+    const client = this._client
+    client.publish(
       topic,
       message,
       { qos: this._qos, ...options },
@@ -919,13 +1023,16 @@ class VrpcClient extends EventEmitter {
           this._log.warn(
             `Could not publish MQTT message because: ${err.message}`
           )
-          if (err.message === 'client disconnecting') {
+          if (
+            err.message === 'client disconnecting' &&
+            this._isRevivable(client)
+          ) {
             // This most certainly relates to a bug in MQTT.js (#1284)
             this._log.error(`Failed to publish, because: ${err.message}`)
             this.emit('error', err)
             this._log.info('Forcing reconnect now...')
-            this._client.disconnecting = false
-            this._client.reconnect()
+            client.disconnecting = false
+            client.reconnect()
           }
         }
       }
@@ -933,8 +1040,9 @@ class VrpcClient extends EventEmitter {
   }
 
   async _mqttSubscribe (topic, options) {
+    const client = this._client
     return new Promise((resolve, reject) => {
-      this._client.subscribe(
+      client.subscribe(
         topic,
         { qos: this._qos, ...options },
         (err, granted) => {
@@ -942,15 +1050,20 @@ class VrpcClient extends EventEmitter {
             this._log.warn(
               `Could not subscribe to topic(s): '${topic}', because: ${err.message}`
             )
-            if (err.message === 'client disconnecting') {
+            if (
+              err.message === 'client disconnecting' &&
+              this._isRevivable(client)
+            ) {
               // This most certainly relates to a bug in MQTT.js (#1284)
               const msg = `Failed to subscribe, because: ${err.message}`
               this._log.error(msg)
               this.emit('error', err)
               this._log.info('Forcing reconnect now...')
-              this._client.disconnecting = false
-              this._client.reconnect()
+              client.disconnecting = false
+              client.reconnect()
               reject(new Error(msg))
+            } else if (err.message === 'client disconnecting') {
+              reject(err)
             }
           } else {
             const topicArray = Array.isArray(topic) ? topic : [topic]

package/vrpc/VrpcPersistor.js

@@ -98,6 +98,8 @@ class VrpcPersistor {
         .replace(/[^a-zA-Z0-9]/g, '-')}`
 
     this._storage = null
+    // the 'update' listener on each persisted instance, dropped on delete
+    this._updateListeners = new Map()
     this._isInitialized = this._init(Storage)
 
     this._log.info(
@@ -282,7 +284,11 @@ class VrpcPersistor {
           const obj = VrpcAdapter.getInstance(instance)
           // Ensure the object is an event emitter
           if (obj && typeof obj.on === 'function') {
-            obj.on('update', data => {
+            const listener = data => {
+              // a deleted object never rewrites the record of its name
+              // (#1705): an in-process delete announces nothing
+              const live = VrpcAdapter._instances.get(instance)
+              if (!live || live.instance !== obj) return
               this._log.info(
                 `[VrpcPersistor] Persisting update for: ${instance} (${className})`
               )
@@ -293,7 +299,9 @@ class VrpcPersistor {
                   `[VrpcPersistor] Failed persisting update of ${instance} (${className}): ${err.message}`
                 )
               )
-            })
+            }
+            obj.on('update', listener)
+            this._updateListeners.set(instance, { obj, listener })
           }
         } catch (err) {
           this._log.warn(
@@ -304,6 +312,11 @@ class VrpcPersistor {
 
       // Persist instance deletion
       VrpcAdapter.on('delete', ({ instance, className }) => {
+        const update = this._updateListeners.get(instance)
+        if (update) {
+          this._updateListeners.delete(instance)
+          update.obj.removeListener('update', update.listener)
+        }
         this._log.info(
           `[VrpcPersistor] Deleting persisted instance: ${instance} (${className})`
         )

package/vrpc/comment-parser/parser.js

@@ -230,6 +230,17 @@ function mkextract (opts) {
       indent = startPos + MARKER_START.length
     }
 
+    // a member with a computed key ([Symbol.asyncDispose]) names no remote
+    // function: the block documents it and nothing else - without this it
+    // landed on the first call in the member's body
+    if (
+      findMethod &&
+      /^\s*(static\s+)?(async\s+)?\*?\s*((get|set)\s+)?\[[^\]]+\]\s*\(/.test(line)
+    ) {
+      result = parse_block(chunk, opts)
+      findMethod = false
+    }
+
     if (findMethod) {
       const ret = line.match(/\s*function\s+(\w+)\s*\(/) ||
         line.match(/\s*(\w+)\s*=?\s*\(/)