vrpc 3.11.1 → 3.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vrpc",
-  "version": "3.11.1",
+  "version": "3.12.1",
   "description": "Variadic Remote Procedure Calls",
   "main": "index.js",
   "directories": {

package/vrpc/VrpcAgent.js

@@ -102,6 +102,7 @@ class VrpcAgent extends EventEmitter {
    * @param {String} [obj.bestEffort=true] If true, message will be sent with best effort, i.e. no caching if offline
    * @param {String} [obj.version=''] The (user-defined) version of this agent
    * @param {String} [obj.mqttClientId='<generated()>'] Explicitly set the mqtt client id.
+   * @param {Object} [obj.tls] TLS settings for a secure broker: `{ ca, rejectUnauthorized }`. Without it the broker's certificate is not verified (the historical behaviour); with `ca` the broker must present a chain the given certificates anchor.
    *
    * @example
    * const agent = new Agent({
@@ -119,7 +120,8 @@ class VrpcAgent extends EventEmitter {
     log = 'console',
     bestEffort = true,
     version = '',
-    mqttClientId = null
+    mqttClientId = null,
+    tls = null
   } = {}) {
     super()
     this._validateDomain(domain)
@@ -132,6 +134,7 @@ class VrpcAgent extends EventEmitter {
     this._broker = broker
     this._qos = bestEffort ? 0 : 1
     this._version = version
+    this._tls = tls
     this._mqttClientId =
       mqttClientId || `va3${VrpcAgent._createHash(this._domain + this._agent)}`
     if (log === 'console') {
@@ -150,6 +153,11 @@ class VrpcAgent extends EventEmitter {
       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
+    // connected, request topics subscribed and info announced
+    this._serving = false
 
     // Handle the internal error event in case the user forgot to implement it
     this.on('error', err => {
@@ -169,8 +177,9 @@ class VrpcAgent extends EventEmitter {
    * If the connection could not be established because of authorization
    * failure, the 'error' event will be emitted.
    *
-   * @return {Promise} Resolves once connected or explicitly ended, never
-   * rejects
+   * @return {Promise} Resolves once the agent serves - connected, its
+   * request topics subscribed and its info announced - or once it was
+   * explicitly ended before that, never rejects
    */
   async serve () {
     let username = this._username
@@ -192,7 +201,7 @@ class VrpcAgent extends EventEmitter {
       // agent must come back when it does (mqtt >= 5 stops otherwise)
       reconnectOnConnackError: true,
       clientId: this._mqttClientId,
-      rejectUnauthorized: false,
+      ...VrpcAgent._tlsOptions(this._tls),
       will: {
         topic: `${this._baseTopic}/__agentInfo__`,
         payload: this._createAgentInfoPayload({ status: 'offline' }),
@@ -297,6 +306,17 @@ class VrpcAgent extends EventEmitter {
     return token.slice(0, length)
   }
 
+  /**
+   * The TLS part of the MQTT options: verification off when nothing was
+   * given (as it always was), the given anchors otherwise.
+   */
+  static _tlsOptions (tls) {
+    if (!tls) return { rejectUnauthorized: false }
+    const options = { rejectUnauthorized: tls.rejectUnauthorized !== false }
+    if (tls.ca) options.ca = tls.ca
+    return options
+  }
+
   static _generateAgentName () {
     const { username } = os.userInfo()
     const pathId = VrpcAgent._createHash(path.resolve, 4)
@@ -363,7 +383,13 @@ class VrpcAgent extends EventEmitter {
     )
   }
 
-  _mqttSubscribe (topic, options) {
+  /**
+   * Subscribes topic(s); `onSettled` is called once the broker has
+   * answered (granted, refused or failed alike).
+   *
+   * @private
+   */
+  _mqttSubscribe (topic, options, onSettled) {
     this._client.subscribe(
       topic,
       { qos: this._qos, ...options },
@@ -410,6 +436,7 @@ class VrpcAgent extends EventEmitter {
             this._log.debug(`Already subscribed to topic '${topic}'`)
           }
         }
+        if (onSettled) onSettled()
       }
     )
   }
@@ -444,12 +471,18 @@ class VrpcAgent extends EventEmitter {
     return VrpcAdapter._getMetaData(className)
   }
 
+  /**
+   * Resolves once the agent serves (its own 'connect' event: connected,
+   * request topics subscribed, info announced), or once it was ended.
+   *
+   * @private
+   */
   async _ensureConnected () {
     return new Promise(resolve => {
-      if (this._client.connected) {
+      if (this._serving) {
         resolve()
       } else {
-        this._client.once('connect', resolve)
+        this.once('connect', resolve)
         // Will be triggered if the user called 'agent.end()'
         this.once('end', resolve)
       }
@@ -488,36 +521,64 @@ class VrpcAgent extends EventEmitter {
     return str
   }
 
+  /**
+   * Serve first, announce second. The request topics - the statics and
+   * the methods of every instance that exists already - are subscribed
+   * before the agent publishes its agent and class info, and the
+   * announcement waits until the broker has answered every subscription.
+   * A client acts on the announcement at once; a request it publishes
+   * before the broker routes the topic is lost (QoS 0) and only times out
+   * on the caller's side. That was the fate of the first call into an
+   * agent that came online after the client waiting for it. A refused
+   * subscription is the retrier's business and delays nothing.
+   *
+   * @private
+   */
   _handleConnect () {
     this._log.info('[OK]')
     // everything is subscribed afresh: pending retries are moot
     this._subscribeRetrier.cancel()
+    const generation = ++this._connectGeneration
+    const batches = []
     try {
-      const topics = this._generateTopics()
-      if (topics.length > 0) this._mqttSubscribe(topics)
+      const statics = this._generateTopics()
+      if (statics.length > 0) batches.push(statics)
     } catch (err) {
       this._log.error(
         err,
         `Problem during initial topic subscription: ${err.message}`
       )
     }
-    // Publish agent online
-    this._publishAgentInfoMessage()
-
-    // Publish class information
-    const classes = this._getClasses()
-    classes.forEach(className => {
-      this._publishClassInfoMessage(className)
-      this._publishClassInfoConciseMessage(className)
-    })
-    // Register all pre-existing instances
+    // all pre-existing instances
     for (const [
       instanceId,
       { className }
     ] of VrpcAdapter._instances.entries()) {
-      this._subscribeToMethodsOfNewInstance(className, instanceId)
+      batches.push(this._methodsTopic(className, instanceId))
+    }
+    let pending = batches.length
+    const announce = () => {
+      // a connection that ended meanwhile announces nothing: the next
+      // one prepares and announces itself
+      if (generation !== this._connectGeneration) return
+      this._publishAgentInfoMessage()
+      for (const className of this._getClasses()) {
+        this._publishClassInfoMessage(className)
+        this._publishClassInfoConciseMessage(className)
+      }
+      this._serving = true
+      this.emit('connect')
+    }
+    if (pending === 0) {
+      announce()
+      return
+    }
+    for (const topic of batches) {
+      this._mqttSubscribe(topic, undefined, () => {
+        pending -= 1
+        if (pending === 0) announce()
+      })
     }
-    this.emit('connect')
   }
 
   _publishAgentInfoMessage () {
@@ -771,14 +832,23 @@ class VrpcAgent extends EventEmitter {
     return true
   }
 
+  /**
+   * The request topics of one instance: every method of it.
+   *
+   * @private
+   */
+  _methodsTopic (className, instance) {
+    return `${this._baseTopic}/${className}/${instance}/+`
+  }
+
   _subscribeToMethodsOfNewInstance (className, instance) {
-    const topic = `${this._baseTopic}/${className}/${instance}/+`
+    const topic = this._methodsTopic(className, instance)
     this._mqttSubscribe(topic)
     this._log.debug(`Subscribed to new topic after instantiation: ${topic}`)
   }
 
   _unsubscribeMethodsOfDeletedInstance (className, instance) {
-    const topic = `${this._baseTopic}/${className}/${instance}/+`
+    const topic = this._methodsTopic(className, instance)
     this._mqttUnsubscribe(topic)
     this._log.debug(`Unsubscribed from topic after deletion: ${topic}`)
   }
@@ -793,6 +863,8 @@ class VrpcAgent extends EventEmitter {
   }
 
   _handleClose () {
+    // the next connection prepares and announces itself afresh
+    this._serving = false
     this.emit('close')
   }
 

package/vrpc/VrpcBrowserAgent.js

@@ -71,6 +71,11 @@ class VrpcAgent extends EventEmitter {
     // maps clientId to instanceId
     this._isolatedInstances = new Map()
     this._sharedInstances = new Map()
+    // counts the connections: an announcement belongs to the connection
+    // that prepared it (see _handleConnect)
+    this._connectGeneration = 0
+    // connected, request topics subscribed and info announced
+    this._serving = false
 
     // Handle the internal error event in case the user forgot to implement it
     this.on('error', err => {
@@ -90,8 +95,9 @@ class VrpcAgent extends EventEmitter {
    * If the connection could not be established because of authorization
    * failure, the 'error' event will be emitted.
    *
-   * @return {Promise} Resolves once connected or explicitly ended, never
-   * rejects
+   * @return {Promise} Resolves once the agent serves - connected, its
+   * request topics subscribed and its info announced - or once it was
+   * explicitly ended before that, never rejects
    */
   async serve () {
     let username = this._username
@@ -226,7 +232,11 @@ class VrpcAgent extends EventEmitter {
     )
   }
 
-  _mqttSubscribe (topic, options) {
+  /**
+   * Subscribes topic(s); `onSettled` is called once the broker has
+   * answered (granted, refused or failed alike).
+   */
+  _mqttSubscribe (topic, options, onSettled) {
     this._client.subscribe(
       topic,
       { qos: this._qos, ...options },
@@ -269,6 +279,7 @@ class VrpcAgent extends EventEmitter {
             this._log.debug(`Already subscribed to topic '${topic}'`)
           }
         }
+        if (onSettled) onSettled()
       }
     )
   }
@@ -303,12 +314,16 @@ class VrpcAgent extends EventEmitter {
     return VrpcAdapter._getMetaData(className)
   }
 
+  /**
+   * Resolves once the agent serves (its own 'connect' event: connected,
+   * request topics subscribed, info announced), or once it was ended.
+   */
   async _ensureConnected () {
     return new Promise(resolve => {
-      if (this._client.connected) {
+      if (this._serving) {
         resolve()
       } else {
-        this._client.once('connect', resolve)
+        this.once('connect', resolve)
         // Will be triggered if the user called 'agent.end()'
         this.once('end', resolve)
       }
@@ -347,33 +362,56 @@ class VrpcAgent extends EventEmitter {
     return str
   }
 
+  /**
+   * Serve first, announce second - the twin of VrpcAgent._handleConnect:
+   * every request topic (statics, the methods of every existing instance)
+   * is subscribed before the agent and class info go out, and they go out
+   * once the broker has answered every subscription. A client acts on the
+   * announcement at once; a request published before the broker routes
+   * the topic is lost (QoS 0) and only times out on the caller's side.
+   */
   _handleConnect () {
     this._log.info('[OK]')
+    const generation = ++this._connectGeneration
+    const batches = []
     try {
-      const topics = this._generateTopics()
-      if (topics.length > 0) this._mqttSubscribe(topics)
+      const statics = this._generateTopics()
+      if (statics.length > 0) batches.push(statics)
     } catch (err) {
       this._log.error(
         err,
         `Problem during initial topic subscription: ${err.message}`
       )
     }
-    // Publish agent online
-    this._publishAgentInfoMessage()
-
-    // Publish class information
-    const classes = this._getClasses()
-    classes.forEach(className => {
-      this._publishClassInfoMessage(className)
-    })
-    // Register all pre-existing instances
+    // all pre-existing instances
     for (const [
       instanceId,
       { className }
     ] of VrpcAdapter._instances.entries()) {
-      this._subscribeToMethodsOfNewInstance(className, instanceId)
+      batches.push(this._methodsTopic(className, instanceId))
+    }
+    let pending = batches.length
+    const announce = () => {
+      // a connection that ended meanwhile announces nothing: the next
+      // one prepares and announces itself
+      if (generation !== this._connectGeneration) return
+      this._publishAgentInfoMessage()
+      for (const className of this._getClasses()) {
+        this._publishClassInfoMessage(className)
+      }
+      this._serving = true
+      this.emit('connect')
+    }
+    if (pending === 0) {
+      announce()
+      return
+    }
+    for (const topic of batches) {
+      this._mqttSubscribe(topic, undefined, () => {
+        pending -= 1
+        if (pending === 0) announce()
+      })
     }
-    this.emit('connect')
   }
 
   _publishAgentInfoMessage () {
@@ -592,14 +630,19 @@ class VrpcAgent extends EventEmitter {
     return true
   }
 
+  /** The request topics of one instance: every method of it. */
+  _methodsTopic (className, instance) {
+    return `${this._baseTopic}/${className}/${instance}/+`
+  }
+
   _subscribeToMethodsOfNewInstance (className, instance) {
-    const topic = `${this._baseTopic}/${className}/${instance}/+`
+    const topic = this._methodsTopic(className, instance)
     this._mqttSubscribe(topic)
     this._log.debug(`Subscribed to new topic after instantiation: ${topic}`)
   }
 
   _unsubscribeMethodsOfDeletedInstance (className, instance) {
-    const topic = `${this._baseTopic}/${className}/${instance}/+`
+    const topic = this._methodsTopic(className, instance)
     this._mqttUnsubscribe(topic)
     this._log.debug(`Unsubscribed from topic after deletion: ${topic}`)
   }
@@ -614,6 +657,8 @@ class VrpcAgent extends EventEmitter {
   }
 
   _handleClose () {
+    // the next connection prepares and announces itself afresh
+    this._serving = false
     this.emit('close')
   }
 

package/vrpc/VrpcClient.js

@@ -75,6 +75,7 @@ class VrpcClient extends EventEmitter {
    *   domain: 'vrpc',
    *   broker: 'mqtts://broker.hivemq.com:8883'
    * })
+   * @param {Object} [obj.tls] TLS settings for a secure broker: `{ ca, rejectUnauthorized }`. Without it the broker's certificate is not verified (the historical behaviour); with `ca` the broker must present a chain the given certificates anchor.
    */
   constructor ({
     token,
@@ -89,7 +90,8 @@ class VrpcClient extends EventEmitter {
     mqttClientId = null,
     identity = null,
     keepalive = 30,
-    requiresSchema = false
+    requiresSchema = false,
+    tls = null
   } = {}) {
     super()
     // domain sanity check
@@ -137,6 +139,7 @@ class VrpcClient extends EventEmitter {
 
     this._instance = nanoid(8)
     this._mqttClientId = mqttClientId || this._createMqttClientId()
+    this._tls = tls
     this._vrpcClientId = this._createVrpcClientId()
     // the part of the connection id nobody else can learn: a broker that
     // confines a client to topics under its own mqtt client id keeps
@@ -203,6 +206,17 @@ class VrpcClient extends EventEmitter {
     return this._vrpcConnectionId
   }
 
+  /**
+   * The TLS part of the MQTT options: verification off when nothing was
+   * given (as it always was), the given anchors otherwise.
+   */
+  static _tlsOptions (tls) {
+    if (!tls) return { rejectUnauthorized: false }
+    const options = { rejectUnauthorized: tls.rejectUnauthorized !== false }
+    if (tls.ca) options.ca = tls.ca
+    return options
+  }
+
   /**
    * Actually connects to the MQTT broker.
    *
@@ -229,7 +243,7 @@ class VrpcClient extends EventEmitter {
       clean: true,
       keepalive: this._keepalive,
       clientId: this._mqttClientId,
-      rejectUnauthorized: false,
+      ...VrpcClient._tlsOptions(this._tls),
       connectTimeout: this._timeout,
       // a refused CONNACK is retried like any other failed attempt (see
       // VrpcAgent): whoever wants a refusal to be final ends the client