vrpc 3.9.0 → 3.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vrpc",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "description": "Variadic Remote Procedure Calls",
   "main": "index.js",
   "directories": {
@@ -12,13 +12,14 @@
     "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:production",
+    "test": "npm run test:adapter && npm run test:agent && npm run test:client && npm run test:persistor && npm run test:lifecycle && 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:agent": "tests/agent/test.sh",
     "test:client": "tests/client/test.sh",
     "test:performance": "tests/performance/test.sh",
     "test:persistor": "./node_modules/.bin/mocha tests/persistor/*.js --timeout 30000 --exit",
+    "test:lifecycle": "./node_modules/.bin/mocha tests/lifecycle/*.js --timeout 30000 --exit",
     "test:production": "./node_modules/.bin/mocha tests/production/lifeCycleTest.js --timeout 30000 --exit && tests/production/test.sh"
   },
   "bin": {

package/vrpc/VrpcAdapter.js

@@ -276,6 +276,15 @@ class VrpcAdapter {
    * @param {String} description Parameter description
    * @param {String} [type] Parameter type
    * @param {Any} [default] The default to be injected when not provided
+   * @param {Callback} [callback] The signature of a function-typed
+   * parameter, when a `@callback` typedef of that name documents it
+   */
+
+  /**
+   * @typedef {Object} Callback
+   * @param {String} name Typedef name (the parameter's type)
+   * @param {String} description Callback description
+   * @param {Array.<Param>} params The arguments the function is called with
    */
 
   /**
@@ -341,27 +350,35 @@ class VrpcAdapter {
   static _parseComments (content) {
     const comments = commentParser(content, { assocFunctions: true })
     const meta = {}
+    const paramsOf = tags =>
+      tags
+        .filter(
+          ({ tag }) => tag === 'param' || tag === 'arg' || tag === 'argument'
+        )
+        .map(({ name, optional, description, type, default: defaultValue }) => {
+          return { name, optional, description, type, defaultValue }
+        })
+    // `@callback Name` blocks document the signature of a function-typed
+    // parameter; a parameter whose type names one carries it as `callback`
+    const callbacks = {}
+    comments.forEach(({ tags, description }) => {
+      const typedef = tags && tags.find(({ tag }) => tag === 'callback')
+      if (!typedef || !typedef.name) return
+      callbacks[typedef.name] = {
+        name: typedef.name,
+        description,
+        params: paramsOf(tags)
+      }
+    })
     comments.forEach(({ tags, description, functionName }) => {
+      if (tags && tags.some(({ tag }) => tag === 'callback')) return
       if (functionName) {
         if (tags) {
-          let params = tags.filter(
-            ({ tag }) => tag === 'param' || tag === 'arg' || tag === 'argument'
+          const params = paramsOf(tags).map(param =>
+            callbacks[param.type]
+              ? { ...param, callback: callbacks[param.type] }
+              : param
           )
-          if (params.length > 0) {
-            params = params.map(
-              ({
-                name,
-                optional,
-                description,
-                type,
-                default: defaultValue
-              }) => {
-                return { name, optional, description, type, defaultValue }
-              }
-            )
-          } else {
-            params = []
-          }
           let ret = tags.filter(
             ({ tag }) => tag === 'returns' || tag === 'return'
           )

package/vrpc/VrpcAgent.js

@@ -614,7 +614,14 @@ class VrpcAgent extends EventEmitter {
       // Intersecting life-cycle functions
       switch (method) {
         case '__createIsolated__': {
-          // TODO handle instantiation errors
+          if (json.e) {
+            // a constructor that threw leaves nothing behind: no instance,
+            // no subscription, no lifetime bookkeeping
+            this._log.warn(
+              `Instantiation of ${className} failed: ${json.e.message}`
+            )
+            break
+          }
           const instanceId = json.r
           // TODO await this
           this._subscribeToMethodsOfNewInstance(className, instanceId)
@@ -622,7 +629,12 @@ class VrpcAgent extends EventEmitter {
           break
         }
         case '__createShared__': {
-          // TODO handle instantiation errors
+          if (json.e) {
+            this._log.warn(
+              `Instantiation of ${className} failed: ${json.e.message}`
+            )
+            break
+          }
           const instanceId = json.r
           if (!this._hasSharedInstance(instanceId)) {
             this._subscribeToMethodsOfNewInstance(className, instanceId)

package/vrpc/VrpcClient.js

@@ -1013,7 +1013,11 @@ class VrpcClient extends EventEmitter {
       this._eventEmitter.once(i, ({ e, r }) => {
         clearTimeout(timer)
         if (e) {
-          reject(new Error(e))
+          // the agent answers a throwing constructor with { message, cause }
+          const { message, cause } = VrpcClient._prepareError(e)
+          reject(
+            new Error(`[vrpc ${agent}-${className}-${f}]: ${message}`, { cause })
+          )
         } else {
           const proxy = this._createProxy(agent, className, r)
           resolve(proxy)

package/vrpc/VrpcPersistor.js

@@ -9,12 +9,10 @@ __\/\\\_______\/\\\__/\\\///////\\\___\/\\\/////////\\\____/\\\////////__
       _______\//\\\_______\/\\\______\//\\\_\/\\\_______________\////\\\\\\\\\_
        ________\///________\///________\///__\///___________________\/////////__
 
-
 Non-intrusively adapts code and provides access in form of asynchronous remote
 procedure calls (RPC).
 Author: Dr. Burkhard C. Heisen (https://github.com/heisenware/vrpc)
 
-
 Licensed under the MIT License <http://opensource.org/licenses/MIT>.
 Copyright (c) 2018 - 2022 Dr. Burkhard C. Heisen <burkhard.heisen@heisenware.com>.
 
@@ -39,12 +37,22 @@ SOFTWARE.
 
 const VrpcAdapter = require('./VrpcAdapter')
 
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
 /**
  * Provides a persistence layer for VRPC instances.
  *
  * This class automatically saves the constructor arguments of newly created
- * instances and re-creates them when the application restarts. It also listens
- * for an 'update' event on instances to persist their state after creation.
+ * shared instances and re-creates them when the application restarts. It also
+ * listens for an 'update' event on instances to persist their state after
+ * creation (the event's payload is used as the single constructor argument
+ * upon restoration). Isolated instances belong to the connection that
+ * created them and are never persisted.
+ *
+ * A record that cannot be restored is never deleted: it is quarantined
+ * (marked with the error, kept on disk), retried once per start so it heals
+ * by itself once the cause is fixed, and can be inspected (`status`), retried
+ * (`retry`) or removed on purpose (`forget`).
  *
  * @requires @heisenware/storage - This peer dependency must be installed.
  * Storage 1.x (synchronous constructor) and >= 2.x (async `Storage.open`)
@@ -59,8 +67,16 @@ class VrpcPersistor {
    * @param {VrpcAgent} options.agentInstance The VRPC agent whose instances should be persisted.
    * @param {string} [options.dir] Optional directory for storage. Defaults to a path derived from the agent's name.
    * @param {object} [options.log] Optional logger object (e.g. console) with info, warn, and error methods.
+   * @param {number} [options.retries=5] How often a record that fails on a fresh restore is retried before it is quarantined.
+   * @param {number} [options.retryDelay=1000] Milliseconds between retries, multiplied by the attempt number.
    */
-  constructor ({ agentInstance, dir, log = console }) {
+  constructor ({
+    agentInstance,
+    dir,
+    log = console,
+    retries = 5,
+    retryDelay = 1000
+  }) {
     let Storage
     try {
       Storage = require('@heisenware/storage')
@@ -72,6 +88,8 @@ class VrpcPersistor {
 
     this._agentInstance = agentInstance
     this._log = log
+    this._retries = retries
+    this._retryDelay = retryDelay
 
     this._dir =
       dir ||
@@ -90,79 +108,149 @@ class VrpcPersistor {
   /**
    * Restores all persisted instances from storage.
    *
-   * It attempts to recreate each instance using its saved className and args.
-   * If an instance fails to restore after several retries with exponential backoff,
-   * it is considered "broken" and removed from storage to prevent startup loops.
+   * A record seen for the first time is retried with a growing delay; a
+   * record that still fails is quarantined: it stays on disk, marked with
+   * the error and the number of attempts. A quarantined record gets one
+   * attempt per restore, so it heals on the next start once its cause is
+   * fixed, and never turns a start into a retry storm.
+   *
+   * @returns {Promise<{restored: string[], quarantined: Array<{instance: string, className: string, error: string, attempts: number, since: string}>}>}
    */
   async restore () {
     await this._isInitialized
+    const summary = { restored: [], quarantined: [] }
     const allIds = this._storage.keys()
     if (allIds.length === 0) {
       this._log.info('[VrpcPersistor] No instances to restore.')
-      return
+      return summary
     }
-
     this._log.info(
       `[VrpcPersistor] Found ${allIds.length} persisted instance(s) to restore.`
     )
 
-    let failedIds = []
-    const restorationPromises = allIds.map(async id => {
-      try {
-        const { className, args } = await this._storage.getItem(id)
-        this._log.info(
-          `[VrpcPersistor] Restoring instance: ${id} (${className})`
-        )
-        this._agentInstance.create({ className, args, instance: id })
-      } catch (err) {
+    let failing = []
+    for (const id of allIds) {
+      const record = await this._storage.getItem(id)
+      if (!record || !record.className) {
+        this._log.warn(`[VrpcPersistor] Skipping ${id}: record is missing or broken.`)
+        continue
+      }
+      if (record.restoreError) {
+        // quarantined: one attempt per start
+        const err = this._tryCreate(id, record)
+        if (!err) {
+          summary.restored.push(id)
+          this._log.info(
+            `[VrpcPersistor] Healed ${id} (${record.className}) after ${record.restoreError.attempts} failed attempt(s).`
+          )
+        } else {
+          summary.quarantined.push(await this._quarantine(id, record, err, 1))
+        }
+        continue
+      }
+      this._log.info(`[VrpcPersistor] Restoring instance: ${id} (${record.className})`)
+      const err = this._tryCreate(id, record)
+      if (!err) {
+        summary.restored.push(id)
+      } else {
         this._log.warn(
           `[VrpcPersistor] Could not restore ${id}: ${err.message}. Will retry.`
         )
-        failedIds.push(id)
+        failing.push({ id, record, err })
       }
-    })
-    await Promise.all(restorationPromises)
+    }
 
-    // Retry failed instances
+    // Retry fresh failures with a growing delay
     let trial = 0
-    const MAX_TRIALS = 5
-    while (failedIds.length > 0 && trial++ < MAX_TRIALS) {
+    while (failing.length > 0 && trial++ < this._retries) {
       this._log.info(
-        `[VrpcPersistor] Retrying ${failedIds.length} failed instance(s), attempt ${trial}.`
+        `[VrpcPersistor] Retrying ${failing.length} failed instance(s), attempt ${trial} of ${this._retries}.`
       )
-      await new Promise(resolve => setTimeout(resolve, 1000 * trial)) // Exponential backoff
+      await sleep(this._retryDelay * trial)
       const stillFailing = []
-      for (const id of failedIds) {
-        try {
-          const { className, args } = await this._storage.getItem(id)
-          this._agentInstance.create({ className, args, instance: id })
-          this._log.info(
-            `[VrpcPersistor] Successfully restored ${id} on retry.`
-          )
-        } catch (err) {
-          stillFailing.push(id)
+      for (const entry of failing) {
+        const err = this._tryCreate(entry.id, entry.record)
+        if (!err) {
+          summary.restored.push(entry.id)
+          this._log.info(`[VrpcPersistor] Successfully restored ${entry.id} on retry.`)
+        } else {
+          stillFailing.push({ ...entry, err })
         }
       }
-      failedIds = stillFailing
+      failing = stillFailing
     }
 
-    // Cleanup instances that could not be restored
-    if (failedIds.length > 0) {
-      this._log.warn(
-        '[VrpcPersistor] The following instances could not be restored and will be removed:'
+    for (const { id, record, err } of failing) {
+      summary.quarantined.push(
+        await this._quarantine(id, record, err, 1 + this._retries)
       )
-      const deletionPromises = failedIds.map(id => {
-        this._log.warn(` - ${id}`)
-        return this._storage.removeItem(id)
+    }
+
+    this._log.info(
+      `[VrpcPersistor] Restored ${summary.restored.length} of ${allIds.length} instance(s)` +
+        (summary.quarantined.length > 0
+          ? `, ${summary.quarantined.length} quarantined: ${summary.quarantined
+              .map(x => `${x.instance} (${x.className}): ${x.error}`)
+              .join('; ')}`
+          : '.')
+    )
+    return summary
+  }
+
+  /**
+   * Lists every persisted record with its quarantine mark, if any.
+   *
+   * @returns {Promise<{dir: string, instances: Array<{instance: string, className: string, restoreError: (object|null)}>}>}
+   */
+  async status () {
+    await this._isInitialized
+    const instances = []
+    for (const id of this._storage.keys()) {
+      const record = await this._storage.getItem(id)
+      if (!record) continue
+      instances.push({
+        instance: id,
+        className: record.className,
+        restoreError: record.restoreError || null
       })
-      try {
-        await Promise.all(deletionPromises)
-      } catch (err) {
-        this._log.error(
-          `[VrpcPersistor] Failed to delete broken instances: ${err.message}`
-        )
-      }
     }
+    return { dir: this._dir, instances }
+  }
+
+  /**
+   * Attempts one more time to restore a persisted instance (quarantined or
+   * not). A success clears the quarantine mark, a failure updates it.
+   *
+   * @param {string} id The instance id
+   * @returns {Promise<boolean>} true when the instance exists afterwards
+   */
+  async retry (id) {
+    await this._isInitialized
+    const record = await this._storage.getItem(id)
+    if (!record) throw new Error(`Unknown persisted instance: ${id}`)
+    const err = this._tryCreate(id, record)
+    if (!err) {
+      this._log.info(`[VrpcPersistor] Restored ${id} (${record.className}) on request.`)
+      return true
+    }
+    await this._quarantine(id, record, err, 1)
+    return false
+  }
+
+  /**
+   * Removes a persisted record on purpose, the only way a record leaves the
+   * storage other than the deletion of a live instance.
+   *
+   * @param {string} id The instance id
+   * @returns {Promise<boolean>} true
+   */
+  async forget (id) {
+    await this._isInitialized
+    const record = await this._storage.getItem(id)
+    if (!record) throw new Error(`Unknown persisted instance: ${id}`)
+    await this._storage.removeItem(id)
+    this._log.info(`[VrpcPersistor] Forgot ${id} (${record.className}).`)
+    return true
   }
 
   /**
@@ -175,8 +263,15 @@ class VrpcPersistor {
       // after construction must be caught. The operations they trigger wait
       // for the storage layer opened below.
 
-      // Persist new instance creation
-      VrpcAdapter.on('create', async ({ instance, className, args }) => {
+      // Persist new instance creation (a restore passes here too, which
+      // rewrites the record and thereby clears a quarantine mark)
+      VrpcAdapter.on('create', async ({ instance, className, args, isIsolated }) => {
+        if (isIsolated) {
+          this._log.info(
+            `[VrpcPersistor] Not persisting isolated instance: ${instance} (${className})`
+          )
+          return
+        }
         this._log.info(
           `[VrpcPersistor] Persisting new instance: ${instance} (${className})`
         )
@@ -235,6 +330,49 @@ class VrpcPersistor {
     }
   }
 
+  /**
+   * Creates the instance from its record; returns the error instead of
+   * throwing (an existing instance counts as success).
+   * @private
+   */
+  _tryCreate (id, { className, args }) {
+    try {
+      this._agentInstance.create({ className, args, instance: id })
+      return null
+    } catch (err) {
+      return err
+    }
+  }
+
+  /**
+   * Marks a record as not restorable and keeps it.
+   * @private
+   */
+  async _quarantine (id, record, err, attempts) {
+    const previous = record.restoreError || { attempts: 0, since: new Date().toISOString() }
+    const restoreError = {
+      message: err.message,
+      at: new Date().toISOString(),
+      since: previous.since,
+      attempts: previous.attempts + attempts
+    }
+    await this._storage.setItem(
+      id,
+      { className: record.className, args: record.args, restoreError },
+      { folder: record.className }
+    )
+    this._log.warn(
+      `[VrpcPersistor] Quarantined ${id} (${record.className}) after ${restoreError.attempts} attempt(s): ${err.message}. The record is kept; fix the cause and restart, or call retry()/forget().`
+    )
+    return {
+      instance: id,
+      className: record.className,
+      error: err.message,
+      attempts: restoreError.attempts,
+      since: restoreError.since
+    }
+  }
+
   /**
    * Saves an instance's details to storage.
    * @private

package/vrpc/comment-parser/parser.js

@@ -219,12 +219,15 @@ function mkextract (opts) {
 
     // if open marker detected and it's not, skip one
     if (startPos !== -1 && line.indexOf(MARKER_START_SKIP) !== startPos) {
-      chunk = []
-      indent = startPos + MARKER_START.length
+      // A block still waiting for its function is followed by another
+      // block: it documents no function (a typedef, a callback) and is
+      // returned as it is - parsed BEFORE the chunk makes way
       if (findMethod) {
         result = parse_block(chunk, opts)
         findMethod = false
       }
+      chunk = []
+      indent = startPos + MARKER_START.length
     }
 
     if (findMethod) {