vrpc 3.14.0 → 3.16.0

package/vrpc/VrpcBrowserAgent.js

@@ -1,10 +1,12 @@
 const os = require('os')
 const mqtt = require('mqtt')
 const VrpcAdapter = require('./VrpcBrowserAdapter')
+const SubscribeRetrier = require('./SubscribeRetrier')
+const ReconnectBackoff = require('./ReconnectBackoff')
 const EventEmitter = require('events')
 const { nanoid } = require('nanoid')
 
-const VRPC_PROTOCOL_VERSION = 3
+const VRPC_PROTOCOL_VERSION = 4
 
 /**
  * Agent capable of making existing code available to remote control by clients.
@@ -21,10 +23,11 @@ class VrpcAgent extends EventEmitter {
    * @param {String} [obj.password] MQTT password (if no token is provided)
    * @param {String} [obj.token] Access token
    * @param {String} [obj.domain='vrpc'] The domain under which the agent-provided code is reachable
-   * @param {String} [obj.agent='<user>-<pathId>@<hostname>-<platform>-js'] This agent's name
+   * @param {String} [obj.agent='<random>'] This agent's name; the default is
+   * eight random characters, new on every start
    * @param {String} [obj.broker='mqtts://broker.hivemq.com:8883'] Broker url in form: `<scheme>://<host>:<port>`
    * @param {Object} [obj.log=console] Log object (must support debug, info, warn, and error level)
-   * @param {String} [obj.bestEffort=false] If true, message will be sent with best effort, i.e. no caching if offline
+   * @param {Boolean} [obj.bestEffort=true] If true, messages are sent at QoS 0 (best effort), else at QoS 1
    * @param {String} [obj.version=''] The (user-defined) version of this agent
    * @param {String} [obj.mqttClientId='<generated()>'] Explicitly set the mqtt client id.
    *
@@ -42,7 +45,7 @@ class VrpcAgent extends EventEmitter {
     agent = nanoid(8),
     broker = 'mqtts://broker.hivemq.com:8883',
     log = 'console',
-    bestEffort = false,
+    bestEffort = true,
     version = '',
     mqttClientId = null
   } = {}) {
@@ -75,9 +78,29 @@ class VrpcAgent extends EventEmitter {
         `Dispose of deleted instance ${className}::${instance} failed: ${error.message}`
       )
     VrpcAdapter.on('disposeFailed', this._handleDisposeFailed)
-    // maps clientId to instanceId
+    // a registration whose release failed is gone from the book anyway
+    this._handleReleaseFailed = ({ context, error, ...rest }) =>
+      this._log.warn(
+        error,
+        `Release of registration ${context}::${rest.function} failed: ${error && error.message}`
+      )
+    VrpcAdapter.on('releaseFailed', this._handleReleaseFailed)
+    // a greeting that failed leaves its subscription in place
+    this._handleGreetFailed = ({ context, error, ...rest }) =>
+      this._log.warn(
+        error,
+        `Greeting of a subscriber to ${context}::${rest.function} failed: ${error && error.message}`
+      )
+    VrpcAdapter.on('greetFailed', this._handleGreetFailed)
+    // connection id -> Set(isolated instance ids it owns)
     this._isolatedInstances = new Map()
-    this._sharedInstances = new Map()
+    // connection ids whose presence is watched (see _watch)
+    this._watched = new Set()
+    // refused subscriptions are retried until granted
+    this._subscribeRetrier = new SubscribeRetrier({
+      subscribe: (topics, options) => this._mqttSubscribe(topics, options),
+      log: this._log
+    })
     // counts the connections: an announcement belongs to the connection
     // that prepared it (see _handleConnect)
     this._connectGeneration = 0
@@ -121,6 +144,10 @@ class VrpcAgent extends EventEmitter {
       password,
       keepalive: 30,
       connectTimeout: 10 * 1000,
+      // a refused CONNACK is retried like any other failed attempt: an
+      // authorization service that is briefly away refuses, too, and an
+      // agent must come back when it does (mqtt >= 5 stops otherwise)
+      reconnectOnConnackError: true,
       clientId: this._mqttClientId,
       rejectUnauthorized: false,
       will: {
@@ -135,6 +162,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))
@@ -154,8 +183,16 @@ class VrpcAgent extends EventEmitter {
    */
   async end ({ unregister = false } = {}) {
     VrpcAdapter.off('disposeFailed', this._handleDisposeFailed)
+    VrpcAdapter.off('releaseFailed', this._handleReleaseFailed)
+    VrpcAdapter.off('greetFailed', this._handleGreetFailed)
+    this._subscribeRetrier.cancel()
     try {
       if (!this._client || !this._client.connected) {
+        // a client that is still trying stops trying: end() is final
+        if (this._client) {
+          const client = this._client
+          await new Promise(resolve => client.end(true, {}, resolve))
+        }
         this.emit('end')
         return
       }
@@ -166,11 +203,16 @@ class VrpcAgent extends EventEmitter {
         { retain: true }
       )
       if (unregister) {
+        // empty retained messages clear what the broker keeps of this agent
         this._mqttPublish(agentTopic, null, { retain: true })
-        const classes = this._getClasses()
-        for (const className of classes) {
-          const infoTopic = `${this._baseTopic}/${className}/__classInfo__`
-          this._mqttPublish(infoTopic, null, { retain: true })
+        for (const className of this._getClasses()) {
+          for (const info of ['__classInfo__', '__classInfoConcise__']) {
+            this._mqttPublish(
+              `${this._baseTopic}/${className}/${info}`,
+              null,
+              { retain: true }
+            )
+          }
         }
       }
       await new Promise(resolve => this._client.end(false, {}, resolve))
@@ -248,16 +290,19 @@ class VrpcAgent extends EventEmitter {
     this._client.subscribe(
       topic,
       { qos: this._qos, ...options },
-      (err, granted) => {
-        if (err) {
+      (subscribeError, subs) => {
+        const { refused, granted, error } = SubscribeRetrier.outcome(
+          subscribeError,
+          subs
+        )
+        if (error) {
           this._log.warn(
-            `Could not subscribe to topic(s) '${topic}', because: ${err.message}`
+            `Could not subscribe to topic(s) '${topic}', because: ${error.message}`
           )
         } else {
+          let err
           const topicArray = Array.isArray(topic) ? topic : [topic]
-          const erroneousGranted = granted
-            .filter(x => x.qos === 128)
-            .map(x => x.topic)
+          const erroneousGranted = refused
           if (erroneousGranted.length > 0) {
             err = new Error(
               `Could not subscribe all ${topicArray.length} topic(s) but got error qos=128 on following ${erroneousGranted.length} topic(s): ${erroneousGranted}`
@@ -266,7 +311,9 @@ class VrpcAgent extends EventEmitter {
             err.subscribeOptions = options
             this._log.error(err)
             this.emit('error', err)
+            this._subscribeRetrier.schedule(erroneousGranted, options)
           }
+          this._subscribeRetrier.granted(granted.map(x => x.topic))
           const reducedQos = granted.filter(x => x.qos < this._qos)
           if (reducedQos.length > 0) {
             err = new Error(
@@ -338,15 +385,43 @@ class VrpcAgent extends EventEmitter {
     })
   }
 
+  /**
+   * Publishes what the adapter sends on its own: a callback or an event
+   * `{ a, i, v }`, the second answer of a promise `{ r | e, i, v }`, an
+   * ended notice `{ i, end, v }`. Events and notices go to the topic their
+   * subscription id names, everything else to the sender.
+   *
+   * An event or a callback whose arguments JSON cannot carry (a BigInt) is
+   * not dropped silently: a receiver of protocol 4 gets `{ i, e, v }`
+   * instead (EV-22, CALL-10). An older one would call its handler without
+   * arguments, so it gets nothing, and the agent logs a warning.
+   */
   _handleVrpcCallback (json) {
-    const { s, i, r, e, a } = json
+    const { s, i, r, e, a, end, receiverVersion } = json
     const topic = i.startsWith('__e__') ? i.slice(5) : s
+    const v = VRPC_PROTOCOL_VERSION
+    let message
+    if (end) message = { i, end, v }
+    else if (a !== undefined) message = { a, i, v }
+    else message = VrpcAgent._answer({ r, e, i })
+    let payload
     try {
-      this._log.debug(`Forwarding callback to: ${topic} with payload:`, json)
-      this._mqttPublish(
-        topic,
-        VrpcAgent._stringifySafely({ a, r, e, i, v: VRPC_PROTOCOL_VERSION })
+      payload = VrpcAgent._stringifySafely(message)
+    } catch (err) {
+      const what = i.startsWith('__e__') ? 'event' : 'callback'
+      this._log.warn(
+        `The arguments of ${what === 'event' ? 'an' : 'a'} ${what} to ${topic} cannot be encoded as JSON: ${err.message}`
       )
+      if (!(receiverVersion >= 4)) return
+      payload = JSON.stringify({
+        i,
+        e: { message: `The arguments of this ${what} cannot be encoded as JSON: ${err.message}` },
+        v
+      })
+    }
+    try {
+      this._log.debug(`Forwarding callback to: ${topic} with payload:`, json)
+      this._mqttPublish(topic, payload)
     } catch (err) {
       this._log.warn(
         err,
@@ -355,19 +430,22 @@ class VrpcAgent extends EventEmitter {
     }
   }
 
-  static _stringifySafely (json) {
-    let str
-    const { c, f } = json
+  /**
+   * A message as JSON. A result JSON cannot carry (a circular structure, a
+   * BigInt) is answered as an error; an event or a callback that cannot
+   * travel is dropped (thrown).
+   */
+  static _stringifySafely (message) {
     try {
-      str = JSON.stringify(json)
+      return JSON.stringify(message)
     } catch (err) {
-      this._log.debug(
-        `Failed serialization of return value for: ${c}::${f}, because: ${err.message}`
-      )
-      json.r = '__vrpc::not-serializable__'
-      str = JSON.stringify(json)
+      if (message.a !== undefined || message.end) throw err
+      return JSON.stringify({
+        e: { message: `The result cannot be encoded as JSON: ${err.message}` },
+        i: message.i,
+        v: message.v
+      })
     }
-    return str
   }
 
   /**
@@ -380,6 +458,8 @@ class VrpcAgent extends EventEmitter {
    */
   _handleConnect () {
     this._log.info('[OK]')
+    // everything is subscribed afresh: pending retries are moot
+    this._subscribeRetrier.cancel()
     const generation = ++this._connectGeneration
     const batches = []
     try {
@@ -430,6 +510,11 @@ class VrpcAgent extends EventEmitter {
     )
   }
 
+  /**
+   * Publishes the class info twice, as every agent does: in full
+   * (`__classInfo__`, with meta data) and concise (`__classInfoConcise__`,
+   * without), which is what clients subscribe to by default.
+   */
   _publishClassInfoMessage (className) {
     const json = {
       className,
@@ -439,12 +524,18 @@ class VrpcAgent extends EventEmitter {
       meta: this._getMetaData(className),
       v: VRPC_PROTOCOL_VERSION
     }
+    const { meta, ...concise } = json
     try {
       this._mqttPublish(
         `${this._baseTopic}/${className}/__classInfo__`,
         JSON.stringify(json),
         { retain: true }
       )
+      this._mqttPublish(
+        `${this._baseTopic}/${className}/__classInfoConcise__`,
+        JSON.stringify(concise),
+        { retain: true }
+      )
     } catch (err) {
       this._log.error(
         err,
@@ -467,19 +558,30 @@ class VrpcAgent extends EventEmitter {
         topics.push(`${this._baseTopic}/${className}/__static__/${func}`)
       })
     })
+    // the subscription protocol (version 4) answers on the static topic of
+    // any class: withdraw by id, list and end registrations
+    for (const func of ['__unsubscribe__', '__registrations__', '__end__']) {
+      topics.push(`${this._baseTopic}/+/__static__/${func}`)
+    }
     return topics
   }
 
   _handleMessage (topic, data) {
+    let json
+    try {
+      json = JSON.parse(data.toString())
+    } catch (err) {
+      this._log.warn(`Ignoring a message that is no JSON on: ${topic}`)
+      return
+    }
     try {
-      const json = JSON.parse(data.toString())
       this._log.debug(`Message arrived with topic: ${topic} and payload:`, json)
       const tokens = topic.split('/')
       const [, , className, instance, method] = tokens
 
       // Special case: clientInfo message
       if (tokens.length === 4 && tokens[3] === '__clientInfo__') {
-        this._handleClientInfoMessage(topic, json)
+        if (VrpcAgent._isObject(json)) this._handleClientInfoMessage(topic, json)
         return
       }
 
@@ -489,49 +591,55 @@ class VrpcAgent extends EventEmitter {
         return
       }
 
+      // the sender names where answers, callbacks and events go: without a
+      // connection id of this domain there is nowhere safe to answer
+      if (!VrpcAgent._isObject(json) || !this._isConnectionId(json.s)) {
+        this._log.warn(`Ignoring a request without a valid sender on: ${topic}`)
+        return
+      }
+
       // Prepare RPC json
       // SECURITY: take as much as possible params from topic structure as this
       // can be authorized by the broker. Content can't be checked...
       json.c = instance === '__static__' ? className : instance
       json.f = method
 
+      // what a lifecycle call works on, as it was before the call
+      const named = Array.isArray(json.a) ? json.a[0] : undefined
+      const before = VrpcAdapter._instances.get(named)
+
       // Mutates json and adds return value
       const mustTrack = VrpcAdapter._call(json)
+      if (mustTrack) this._watch(json.s)
 
-      if (mustTrack) {
-        this._mqttSubscribe(`${json.s}/__clientInfo__`)
-      }
-
-      // Intersecting life-cycle functions
-      switch (method) {
-        case '__createIsolated__': {
-          // TODO handle instantiation errors
-          const instanceId = json.r
-          // TODO await this
-          this._subscribeToMethodsOfNewInstance(className, instanceId)
-          this._registerIsolatedInstance(instanceId, json.s)
-          break
-        }
-        case '__createShared__': {
-          // TODO handle instantiation errors
-          const instanceId = json.r
-          if (!this._hasSharedInstance(instanceId)) {
-            this._subscribeToMethodsOfNewInstance(className, instanceId)
-            this._publishClassInfoMessage(className)
-          }
-          this._registerSharedInstance(instanceId, json.s)
-          break
+      if (json.e) {
+        if (method === '__createIsolated__' || method === '__createShared__') {
+          // a constructor that threw leaves nothing behind: no instance, no
+          // subscription, no lifetime bookkeeping
+          this._log.warn(
+            `Instantiation of ${className} failed: ${json.e.message}`
+          )
         }
-        case '__delete__': {
-          this._unsubscribeMethodsOfDeletedInstance(className, instance)
-          const wasShared = this._unregisterInstance(json.a[0], json.s)
-          if (wasShared) this._publishClassInfoMessage(className)
-          break
+      } else {
+        switch (method) {
+          case '__createIsolated__':
+            if (!before) this._subscribeToMethodsOfNewInstance(className, json.r)
+            this._registerIsolatedInstance(json.r, json.s)
+            break
+          case '__createShared__':
+            if (!before) {
+              this._subscribeToMethodsOfNewInstance(className, json.r)
+              this._publishClassInfoMessage(className)
+            }
+            // its creator's going is told (clientGone)
+            this._watch(json.s)
+            break
+          case '__delete__':
+            if (before) this._forgetInstance(named, before)
+            break
         }
       }
-      const { a, r, e, i, v } = json
-      const res = e ? { a, r, e, i, v } : { a, r, i, v }
-      this._mqttPublish(json.s, VrpcAgent._stringifySafely(res))
+      this._mqttPublish(json.s, VrpcAgent._stringifySafely(VrpcAgent._answer(json)))
     } catch (err) {
       this._log.error(
         err,
@@ -540,6 +648,50 @@ class VrpcAgent extends EventEmitter {
     }
   }
 
+  /**
+   * The answer to a request: its result `r` or its error `e`, the request's
+   * correlation id `i` and this agent's protocol version - nothing of the
+   * request is echoed.
+   */
+  static _answer ({ r, e, i }) {
+    return e
+      ? { e, i, v: VRPC_PROTOCOL_VERSION }
+      : { r, i, v: VRPC_PROTOCOL_VERSION }
+  }
+
+  static _isObject (json) {
+    return !!json && typeof json === 'object' && !Array.isArray(json)
+  }
+
+  /**
+   * Whether a request's sender is a connection id of this domain:
+   * `<domain>/<mqttClientId>/<secret>`, three levels, none empty or a
+   * wildcard - and never an agent's info topic, the one other topic of
+   * three levels.
+   */
+  _isConnectionId (s) {
+    if (typeof s !== 'string') return false
+    const levels = s.split('/')
+    return (
+      levels.length === 3 &&
+      levels[0] === this._domain &&
+      levels[2] !== '__agentInfo__' &&
+      levels.every(level => level.length > 0 && !/[+#]/.test(level))
+    )
+  }
+
+  /**
+   * Watches a connection's presence while it holds anything here: isolated
+   * instances, subscriptions, shared instances it created. The watch ends
+   * when the connection goes.
+   */
+  _watch (connectionId) {
+    if (this._watched.has(connectionId)) return
+    this._watched.add(connectionId)
+    this._mqttSubscribe(`${connectionId}/__clientInfo__`)
+    this._log.debug(`Tracking lifetime of client: ${connectionId}`)
+  }
+
   _handleClientInfoMessage (topic, json) {
     // A client connection went offline. The topic carries the connection
     // id (unique per VrpcClient instance) - the key of all bookkeeping -
@@ -548,6 +700,7 @@ class VrpcAgent extends EventEmitter {
     if (json.status === 'offline') {
       VrpcAdapter._unregisterClient(connectionId)
       const entry = this._isolatedInstances.get(connectionId)
+      this._isolatedInstances.delete(connectionId)
       if (entry) {
         entry.forEach(instanceId => {
           const known = VrpcAdapter._instances.get(instanceId)
@@ -555,7 +708,6 @@ class VrpcAgent extends EventEmitter {
             c: known && known.className,
             f: '__delete__',
             a: [instanceId],
-            r: null,
             s: VrpcAdapter.LOCAL_SENDER
           }
           VrpcAdapter._call(json)
@@ -566,6 +718,9 @@ class VrpcAgent extends EventEmitter {
           }
         })
       }
+      // a connection id is kept across reconnects: whatever the connection
+      // holds after it comes back is watched afresh
+      this._watched.delete(connectionId)
       this._mqttUnsubscribe(`${connectionId}/__clientInfo__`)
       // clientId: the identity-derived id shared by all connections of one
       // identity (undefined for clients < 3.8.0)
@@ -573,73 +728,29 @@ class VrpcAgent extends EventEmitter {
     }
   }
 
-  _registerIsolatedInstance (instanceId, clientId) {
-    const entry = this._isolatedInstances.get(clientId)
-    if (entry) {
-      // already seen
-      entry.add(instanceId)
-    } else {
-      // new instance
-      this._isolatedInstances.set(clientId, new Set([instanceId]))
-      if (!this._sharedInstances.has(clientId)) {
-        this._mqttSubscribe(`${clientId}/__clientInfo__`)
-      }
-      this._log.info(`Tracking lifetime of client: ${clientId}`)
-    }
-  }
-
-  _registerSharedInstance (instanceId, clientId) {
-    const entry = this._sharedInstances.get(clientId)
-    if (entry) {
-      // already seen
-      entry.add(instanceId)
-    } else {
-      // new instance
-      this._sharedInstances.set(clientId, new Set([instanceId]))
-      if (!this._isolatedInstances.has(clientId)) {
-        this._mqttSubscribe(`${clientId}/__clientInfo__`)
-      }
-      this._log.debug(`Tracking lifetime of client: ${clientId}`)
-    }
-  }
-
-  _hasSharedInstance (instanceId) {
-    for (const [, instances] of this._sharedInstances) {
-      if (instances.has(instanceId)) return true
-    }
-    return false
+  _registerIsolatedInstance (instanceId, connectionId) {
+    const entry = this._isolatedInstances.get(connectionId)
+    if (entry) entry.add(instanceId)
+    else this._isolatedInstances.set(connectionId, new Set([instanceId]))
+    this._watch(connectionId)
   }
 
-  _unregisterInstance (instanceId, clientId) {
-    const entryIsolated = this._isolatedInstances.get(clientId)
-    if (entryIsolated && entryIsolated.has(instanceId)) {
-      entryIsolated.delete(instanceId)
-      if (entryIsolated.size === 0) {
-        this._isolatedInstances.delete(clientId)
-        this._mqttUnsubscribe(`${clientId}/__clientInfo__`)
-        this._log.debug(`Stopped tracking lifetime of client: ${clientId}`)
-      }
-      return false
-    }
-    let found = false
-    this._sharedInstances.forEach(async v => {
-      if (v.has(instanceId)) {
-        found = true
-        v.delete(instanceId)
-        if (v.size === 0) {
-          this._sharedInstances.delete(clientId)
-          this._mqttUnsubscribe(`${clientId}/__clientInfo__`)
-          this._log.debug(`Stopped tracking lifetime of client: ${clientId}`)
-        }
+  /**
+   * A deleted instance leaves the agent: no request topic outlives it, an
+   * isolated one leaves its owner's bookkeeping, a shared one leaves its
+   * class info.
+   */
+  _forgetInstance (instanceId, { className, isIsolated, owner }) {
+    this._unsubscribeMethodsOfDeletedInstance(className, instanceId)
+    if (isIsolated) {
+      const entry = this._isolatedInstances.get(owner)
+      if (entry) {
+        entry.delete(instanceId)
+        if (entry.size === 0) this._isolatedInstances.delete(owner)
       }
-    })
-    if (!found) {
-      this._log.warn(
-        `Failed un-registering not registered instance: ${instanceId}`
-      )
-      return false
+    } else {
+      this._publishClassInfoMessage(className)
     }
-    return true
   }
 
   /** The request topics of one instance: every method of it. */