vrpc 3.13.0 → 3.15.0

package/index.js

@@ -1,8 +1,8 @@
 'use strict'
-module.exports = {
-  VrpcNative: require('./vrpc/VrpcNative'),
-  VrpcClient: require('./vrpc/VrpcClient'),
-  VrpcAdapter: require('./vrpc/VrpcAdapter'),
-  VrpcAgent: require('./vrpc/VrpcAgent'),
-  VrpcPersistor: require('./vrpc/VrpcPersistor')
-}
+// one assignment per name: Node detects them as named exports, so
+// `import { VrpcClient } from 'vrpc'` works from ES modules, too
+exports.VrpcNative = require('./vrpc/VrpcNative')
+exports.VrpcClient = require('./vrpc/VrpcClient')
+exports.VrpcAdapter = require('./vrpc/VrpcAdapter')
+exports.VrpcAgent = require('./vrpc/VrpcAgent')
+exports.VrpcPersistor = require('./vrpc/VrpcPersistor')

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vrpc",
-  "version": "3.13.0",
-  "description": "Variadic Remote Procedure Calls",
+  "version": "3.15.0",
+  "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": {
     "example": "examples",
@@ -11,10 +11,14 @@
   "scripts": {
     "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:legacy-runtime && npm run test:production",
+    "build:doc": "node scripts/build-docs.js",
+    "check:links": "node scripts/check-links.js",
+    "test": "npm run test:adapter && npm run test:subscriptions && npm run test:examples && 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:subscriptions": "./node_modules/.bin/mocha tests/subscriptions/*.spec.js --exit",
+    "test:examples": "./node_modules/.bin/mocha tests/examples/*.spec.js --exit",
     "test:agent": "tests/agent/test.sh",
     "test:client": "tests/client/test.sh",
     "test:performance": "tests/performance/test.sh",
@@ -27,27 +31,32 @@
     "vrpc-agent-js": "./vrpc/vrpc-agent-js"
   },
   "keywords": [
-    "communication",
-    "iot",
+    "rpc",
     "mqtt",
+    "remote objects",
+    "remote procedure call",
+    "mqtt-rpc",
+    "iot",
     "edge-to-cloud",
-    "rpc",
-    "remote procedural calls",
-    "language binding",
-    "C++",
-    "C++ embedding",
-    "header-only"
+    "events",
+    "microservices",
+    "browser",
+    "react",
+    "arduino",
+    "esp32",
+    "python",
+    "c++"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/heisenware/vrpc.git"
+    "url": "git+https://github.com/heisenware/vrpc-js.git"
   },
   "author": "Burkhard C. Heisen <burkhard.heisen@heisenware.com>",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/heisenware/vrpc/issues"
+    "url": "https://github.com/heisenware/vrpc-js/issues"
   },
-  "homepage": "https://docs.heisenware.com/developers/vrpc",
+  "homepage": "https://vrpc.io",
   "devDependencies": {
     "@heisenware/storage": "^3.0.2",
     "assert": "^2.1.0",
@@ -57,6 +66,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