vrpc 3.15.0 → 3.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vrpc",
-  "version": "3.15.0",
+  "version": "3.16.1",
   "description": "Remote objects over MQTT: call classes in other programs as if they were local - Node.js, browser, C++, Python, Arduino",
   "main": "index.js",
   "directories": {

package/vrpc/VrpcAdapter.js

@@ -661,8 +661,15 @@ class VrpcAdapter {
       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`)
+      if (existing) {
+        // an id is never re-homed: an isolated instance stays isolated
+        if (existing.isIsolated) {
+          throw new Error(`Instance '${instanceId}' exists as an isolated instance`)
+        }
+        // a create of a name that exists returns it unchanged: its class
+        // and arguments stay, and nothing announces it (no 'create' event)
+        json.r = instanceId
+        return existing.instance
       }
       instance = VrpcAdapter._create(className, instanceId, ...args)
       VrpcAdapter._instances.set(instanceId, {
@@ -1177,13 +1184,15 @@ class VrpcAdapter {
   }
 
   /**
-   * 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 }`.
+   * Answers a promise twice: at once with `r: '__p__<f>-<nonce>-<n>'`, and
+   * once it settled with a second answer under that id, `{ s, i, r }` or
+   * `{ s, i, e }`. A client waits for the second answer under the bare id,
+   * whichever agent sends it: the nonce keeps the ids of two agents apart,
+   * whose counters may well stand at the same value.
    */
   static _handlePromise (json, promise) {
     const cid = VrpcAdapter._correlationId++ % Number.MAX_SAFE_INTEGER
-    const id = `__p__${json.f}-${cid}`
+    const id = `__p__${json.f}-${VrpcAdapter._promiseNonce}-${cid}`
     const { s } = json
     json.r = id
     promise.then(
@@ -1311,7 +1320,8 @@ class VrpcAdapter {
 /**
  * Event 'create'
  *
- * Emitted on creation of shared instance
+ * Emitted once an instance was created. A create of a name that exists
+ * returns that instance and emits nothing.
  *
  * @event VrpcAdapter#create
  * @type {Object}
@@ -1391,6 +1401,8 @@ VrpcAdapter._functionRegistry = new Map()
 VrpcAdapter._instances = new Map()
 VrpcAdapter._emitter = new EventEmitter()
 VrpcAdapter._correlationId = 0
+// tells this process's promise ids from those of every other agent
+VrpcAdapter._promiseNonce = nanoid(8)
 // the event registrations of every context and their subscriptions
 VrpcAdapter._registrations = new Registrations({
   publish: message => VrpcAdapter._callback(message),

package/vrpc/VrpcAgent.js

@@ -646,6 +646,9 @@ class VrpcAgent extends EventEmitter {
     ] of VrpcAdapter._instances.entries()) {
       batches.push(this._methodsTopic(className, instanceId))
     }
+    // what the broker retains of this agent's classes: an earlier run's
+    // class that is no longer offered is cleared (_sweepClassInfo)
+    batches.push(`${this._baseTopic}/+/__classInfoConcise__`)
     let pending = batches.length
     const announce = () => {
       // a connection that ended meanwhile announces nothing: the next
@@ -659,10 +662,6 @@ class VrpcAgent extends EventEmitter {
       this._serving = true
       this.emit('connect')
     }
-    if (pending === 0) {
-      announce()
-      return
-    }
     for (const topic of batches) {
       this._mqttSubscribe(topic, undefined, () => {
         pending -= 1
@@ -743,7 +742,38 @@ class VrpcAgent extends EventEmitter {
     return topics
   }
 
-  _handleMessage (topic, data) {
+  /**
+   * A class info under this agent's own name. What the broker retained of
+   * a class this agent does not offer is a ghost of an earlier run - a
+   * class info only `end({ unregister: true })` would have cleared - and
+   * clients would list the class forever: it is cleared, in full and
+   * concise. Everything else on the topic - the agent's own announcements
+   * and clears, routed back live - passes without a word.
+   *
+   * @returns {Boolean} whether the message was a class info
+   * @private
+   */
+  _sweepClassInfo (topic, data, packet) {
+    const prefix = `${this._baseTopic}/`
+    if (!topic.startsWith(prefix)) return false
+    const tokens = topic.slice(prefix.length).split('/')
+    if (tokens.length !== 2) return false
+    const [className, info] = tokens
+    if (info !== '__classInfoConcise__' && info !== '__classInfo__') {
+      return false
+    }
+    const retained = !!packet && packet.retain
+    if (!retained || data.length === 0) return true
+    if (this._getClasses().includes(className)) return true
+    this._log.info(`Clearing the class info of ${className}, no longer offered`)
+    for (const name of ['__classInfo__', '__classInfoConcise__']) {
+      this._mqttPublish(`${prefix}${className}/${name}`, null, { retain: true })
+    }
+    return true
+  }
+
+  _handleMessage (topic, data, packet) {
+    if (this._sweepClassInfo(topic, data, packet)) return
     let json
     try {
       json = JSON.parse(data.toString())

package/vrpc/VrpcBrowserAdapter.js

@@ -69,7 +69,9 @@ class VrpcAdapter {
    * @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)
+   * parameters (only works if registered code reflects a single class). The
+   * browser bundle (`browser/vrpc.js`) does not validate: it warns once and
+   * constructs with the arguments as given
    */
   static registerClass (
     Klass,
@@ -467,8 +469,15 @@ class VrpcAdapter {
       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`)
+      if (existing) {
+        // an id is never re-homed: an isolated instance stays isolated
+        if (existing.isIsolated) {
+          throw new Error(`Instance '${instanceId}' exists as an isolated instance`)
+        }
+        // a create of a name that exists returns it unchanged: its class
+        // and arguments stay, and nothing announces it (no 'create' event)
+        json.r = instanceId
+        return existing.instance
       }
       instance = VrpcAdapter._create(className, instanceId, ...args)
       VrpcAdapter._instances.set(instanceId, {
@@ -912,6 +921,17 @@ class VrpcAdapter {
   }
 
   static _validate (schema, params) {
+    // the browser bundle leaves ajv out - a fifth of its size, for agents in
+    // a page, which are rare: there a schema is not checked
+    if (typeof Ajv !== 'function') {
+      if (!VrpcAdapter._warnedNoSchemas) {
+        VrpcAdapter._warnedNoSchemas = true
+        console.warn(
+          'vrpc: schema validation is not available in the browser build, constructor arguments are not checked'
+        )
+      }
+      return
+    }
     if (!VrpcAdapter._ajv) {
       VrpcAdapter._ajv = new Ajv({ useDefaults: true })
     }
@@ -983,13 +1003,15 @@ class VrpcAdapter {
   }
 
   /**
-   * 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 }`.
+   * Answers a promise twice: at once with `r: '__p__<f>-<nonce>-<n>'`, and
+   * once it settled with a second answer under that id, `{ s, i, r }` or
+   * `{ s, i, e }`. A client waits for the second answer under the bare id,
+   * whichever agent sends it: the nonce keeps the ids of two agents apart,
+   * whose counters may well stand at the same value.
    */
   static _handlePromise (json, promise) {
     const cid = VrpcAdapter._correlationId++ % Number.MAX_SAFE_INTEGER
-    const id = `__p__${json.f}-${cid}`
+    const id = `__p__${json.f}-${VrpcAdapter._promiseNonce}-${cid}`
     const { s } = json
     json.r = id
     promise.then(
@@ -1117,7 +1139,8 @@ class VrpcAdapter {
 /**
  * Event 'create'
  *
- * Emitted on creation of shared instance
+ * Emitted once an instance was created. A create of a name that exists
+ * returns that instance and emits nothing.
  *
  * @event VrpcAdapter#create
  * @type {Object}
@@ -1157,6 +1180,8 @@ VrpcAdapter._functionRegistry = new Map()
 VrpcAdapter._instances = new Map()
 VrpcAdapter._emitter = new EventEmitter()
 VrpcAdapter._correlationId = 0
+// tells this process's promise ids from those of every other agent
+VrpcAdapter._promiseNonce = nanoid(8)
 // the event registrations of every context and their subscriptions
 VrpcAdapter._registrations = new Registrations({
   publish: message => VrpcAdapter._callback(message),

package/vrpc/VrpcBrowserAgent.js

@@ -478,6 +478,9 @@ class VrpcAgent extends EventEmitter {
     ] of VrpcAdapter._instances.entries()) {
       batches.push(this._methodsTopic(className, instanceId))
     }
+    // what the broker retains of this agent's classes: an earlier run's
+    // class that is no longer offered is cleared (_sweepClassInfo)
+    batches.push(`${this._baseTopic}/+/__classInfoConcise__`)
     let pending = batches.length
     const announce = () => {
       // a connection that ended meanwhile announces nothing: the next
@@ -490,10 +493,6 @@ class VrpcAgent extends EventEmitter {
       this._serving = true
       this.emit('connect')
     }
-    if (pending === 0) {
-      announce()
-      return
-    }
     for (const topic of batches) {
       this._mqttSubscribe(topic, undefined, () => {
         pending -= 1
@@ -566,7 +565,38 @@ class VrpcAgent extends EventEmitter {
     return topics
   }
 
-  _handleMessage (topic, data) {
+  /**
+   * A class info under this agent's own name. What the broker retained of
+   * a class this agent does not offer is a ghost of an earlier run - a
+   * class info only `end({ unregister: true })` would have cleared - and
+   * clients would list the class forever: it is cleared, in full and
+   * concise. Everything else on the topic - the agent's own announcements
+   * and clears, routed back live - passes without a word.
+   *
+   * @returns {Boolean} whether the message was a class info
+   * @private
+   */
+  _sweepClassInfo (topic, data, packet) {
+    const prefix = `${this._baseTopic}/`
+    if (!topic.startsWith(prefix)) return false
+    const tokens = topic.slice(prefix.length).split('/')
+    if (tokens.length !== 2) return false
+    const [className, info] = tokens
+    if (info !== '__classInfoConcise__' && info !== '__classInfo__') {
+      return false
+    }
+    const retained = !!packet && packet.retain
+    if (!retained || data.length === 0) return true
+    if (this._getClasses().includes(className)) return true
+    this._log.info(`Clearing the class info of ${className}, no longer offered`)
+    for (const name of ['__classInfo__', '__classInfoConcise__']) {
+      this._mqttPublish(`${prefix}${className}/${name}`, null, { retain: true })
+    }
+    return true
+  }
+
+  _handleMessage (topic, data, packet) {
+    if (this._sweepClassInfo(topic, data, packet)) return
     let json
     try {
       json = JSON.parse(data.toString())

package/vrpc/VrpcClient.js

@@ -180,6 +180,9 @@ class VrpcClient extends EventEmitter {
     this._pendingWithdrawals = new Map()
     // the client's own inbox is subscribed (answers can arrive)
     this._inboxReady = false
+    // the answers this client waits for ({ agent, second, lose, forget }),
+    // lost when the path an answer would travel breaks (see _loseAnswers)
+    this._waiting = new Set()
     // labels callbacks carry towards the agent's list of registrations
     this._subscriberLabels = new WeakMap()
     if (log === 'console') {
@@ -323,6 +326,12 @@ class VrpcClient extends EventEmitter {
       this.emit('error', err)
     })
 
+    // a clean session keeps nothing for this connection while it is gone:
+    // an answer published meanwhile never arrives
+    this._client.on('close', () => {
+      this._loseAnswers(() => true, 'this client lost its connection')
+    })
+
     this._client.stream.on('error', err => {
       this.emit('error', err)
     })
@@ -377,7 +386,7 @@ class VrpcClient extends EventEmitter {
       }
     })
 
-    this._client.on('message', (topic, message) => {
+    this._client.on('message', (topic, message, packet) => {
       if (message.length === 0) return
       try {
         const tokens = topic.split('/')
@@ -398,8 +407,21 @@ class VrpcClient extends EventEmitter {
           // the agent's protocol version (undefined before 3)
           this._agents[agent].v = v
           if (status === 'offline') {
+            this._loseAnswers(
+              w => w.second && w.agent === agent,
+              'the agent went offline'
+            )
             this._loseAgent(agent, v)
           } else {
+            // an agent announces itself from a new connection only (a
+            // retained announcement is old news a subscription brings):
+            // the promises its former connection was to answer are gone
+            if (!packet.retain) {
+              this._loseAnswers(
+                w => w.second && w.agent === agent,
+                'the agent connected anew'
+              )
+            }
             this._redeclareTo(agent)
             this._flushWithdrawals(agent)
           }
@@ -1400,6 +1422,7 @@ class VrpcClient extends EventEmitter {
         v: VRPC_PROTOCOL_VERSION
       })
     )
+    this._loseAnswers(() => true, 'the client ended')
     this._eventEmitter.removeAllListeners()
     this.removeAllListeners()
     // the agents withdraw what this connection held: nothing to declare
@@ -1604,12 +1627,16 @@ class VrpcClient extends EventEmitter {
     await this._waitUntilClassIsOnline(agent, className)
     this._mqttPublish(topic, JSON.stringify(json))
     return new Promise((resolve, reject) => {
-      const msg = `Proxy creation for class "${className}" on agent "${agent}" and domain "${this._domain}" timed out (> ${this._timeout} ms)`
+      const call = `Proxy creation for class "${className}" on agent "${agent}" and domain "${this._domain}"`
       const timer = setTimeout(() => {
-        this._eventEmitter.removeAllListeners(i)
-        reject(new Error(msg))
+        forget()
+        reject(new Error(`${call} timed out (> ${this._timeout} ms)`))
       }, this._timeout)
-      this._eventEmitter.once(i, ({ e, r }) => {
+      const lose = reason => {
+        clearTimeout(timer)
+        reject(new Error(`${call} lost its answer: ${reason}`))
+      }
+      const forget = this._awaitAnswer(i, { agent, lose }, ({ e, r }) => {
         clearTimeout(timer)
         if (e) {
           // the agent answers a throwing constructor with { message, cause }
@@ -1813,27 +1840,33 @@ class VrpcClient extends EventEmitter {
 
   async _handleAgentAnswer ({ i, c, f, a }, agent) {
     return new Promise((resolve, reject) => {
-      const msg = `Function call "${c}::${f}()" on agent "${agent}" timed out (> ${this._timeout} ms)`
+      const call = `Function call "${c}::${f}()" on agent "${agent}"`
       const timer = setTimeout(() => {
-        this._eventEmitter.removeAllListeners(i)
-        reject(new Error(msg))
+        forget()
+        reject(new Error(`${call} timed out (> ${this._timeout} ms)`))
       }, this._timeout)
+      const lose = reason => {
+        clearTimeout(timer)
+        reject(new Error(`${call} lost its answer: ${reason}`))
+      }
       // a protocol-4 agent that answers a declaring call without an error
       // holds every subscription the call carried
       const confirm = () => {
         const info = this._agents[agent]
         if (info && info.v >= 4) this._confirmSubscriptions(a)
       }
-      this._eventEmitter.once(i, data => {
+      const forget = this._awaitAnswer(i, { agent, lose }, data => {
         clearTimeout(timer)
         if (data.e) {
           const { message, cause } = VrpcClient._prepareError(data.e)
           reject(new Error(`[vrpc ${agent}-${c}-${f}]: ${message}`, { cause }))
         } else {
           const ret = data.r
-          // Handle functions returning a promise
+          // Handle functions returning a promise: the result follows when
+          // it settles, however long that takes - unless the path it would
+          // travel breaks first
           if (typeof ret === 'string' && ret.substring(0, 5) === '__p__') {
-            this._eventEmitter.once(ret, promiseData => {
+            this._awaitAnswer(ret, { agent, lose, second: true }, promiseData => {
               if (promiseData.e) {
                 const { message, cause } = VrpcClient._prepareError(
                   promiseData.e
@@ -1855,6 +1888,44 @@ class VrpcClient extends EventEmitter {
     })
   }
 
+  /**
+   * Waits for the answer with id `id`.
+   *
+   * @param {String} id
+   * @param {Object} waiter
+   * @param {String} waiter.agent the agent that answers
+   * @param {Function} waiter.lose called with a reason when the answer can
+   * no longer arrive
+   * @param {Boolean} [waiter.second] a promise's result, the second answer
+   * to its call
+   * @param {Function} onAnswer called with the answer
+   * @returns {Function} stops waiting, without a call to `lose`
+   */
+  _awaitAnswer (id, { agent, lose, second = false }, onAnswer) {
+    const waiter = { agent, lose, second }
+    const listener = data => {
+      this._waiting.delete(waiter)
+      onAnswer(data)
+    }
+    waiter.forget = () => {
+      this._waiting.delete(waiter)
+      this._eventEmitter.removeListener(id, listener)
+    }
+    this._waiting.add(waiter)
+    this._eventEmitter.once(id, listener)
+    return waiter.forget
+  }
+
+  // the answers that can no longer arrive: their calls reject at once, and
+  // a late answer finds no listener
+  _loseAnswers (selects, reason) {
+    for (const waiter of Array.from(this._waiting)) {
+      if (!selects(waiter)) continue
+      waiter.forget()
+      waiter.lose(reason)
+    }
+  }
+
   static _prepareError (rpcError) {
     if (typeof rpcError === 'object') {
       return { message: rpcError.message, cause: rpcError.cause }