@qvac/registry-client 0.5.0 → 0.6.1

package/lib/client.js

@@ -16,6 +16,12 @@ const fs = require('#fs')
 const DEFAULT_DOWNLOAD_MAX_RETRIES = 3
 const RETRIABLE_DOWNLOAD_CODES = ['REQUEST_TIMEOUT']
 
+// While the app is backgrounded the swarm is suspended; a retry must wait for
+// resume rather than burn its (small) retry budget timing out against a dead
+// swarm. Bounded so a never-resumed runtime still fails instead of hanging.
+const RESUME_WAIT_MAX_MS = 5 * 60 * 1000
+const RESUME_WAIT_POLL_MS = 200
+
 class QVACRegistryClient extends ReadyResource {
   constructor (opts = {}) {
     super()
@@ -209,6 +215,81 @@ class QVACRegistryClient extends ReadyResource {
     return { core, blobs }
   }
 
+  /**
+   * Blocks while the swarm is suspended (app backgrounded), so a retry does not
+   * fire against a swarm that cannot connect yet and exhaust the retry budget.
+   * Bounded by RESUME_WAIT_MAX_MS; returns (and lets the retry proceed/fail) if
+   * the runtime never resumes.
+   */
+  async _waitForSwarmResumed (signal) {
+    if (!this.hyperswarm || !this.hyperswarm.suspended) return
+
+    const start = Date.now()
+    while (this.hyperswarm.suspended) {
+      if (signal && signal.aborted) throw new Error('Download cancelled')
+      if (Date.now() - start > RESUME_WAIT_MAX_MS) {
+        this.logger.warn('Swarm still suspended after resume wait; retrying anyway')
+        return
+      }
+      await new Promise(resolve => setTimeout(resolve, RESUME_WAIT_POLL_MS))
+    }
+  }
+
+  /**
+   * Blocks until at least one peer is replicating the core, so a retry after a
+   * network drop waits for the network to actually return instead of firing
+   * (and timing out) against zero peers and burning the retry budget. Bounded
+   * by RESUME_WAIT_MAX_MS. No-op when peer info is unavailable.
+   */
+  async _waitForPeers (core, signal) {
+    if (!core || !Array.isArray(core.peers)) return
+    if (core.peers.length > 0) return
+
+    const start = Date.now()
+    while (core.peers.length === 0) {
+      if (signal && signal.aborted) throw new Error('Download cancelled')
+      if (Date.now() - start > RESUME_WAIT_MAX_MS) {
+        this.logger.warn('No peers after reconnect wait; retrying anyway')
+        return
+      }
+      await new Promise(resolve => setTimeout(resolve, RESUME_WAIT_POLL_MS))
+    }
+  }
+
+  /**
+   * Re-establish peers for a blobs core before retrying a download. After the
+   * app backgrounds (or the network drops) the swarm connection for this core
+   * is gone; this waits for the swarm to resume and for a peer to be replicating
+   * the core, then re-runs the join + findingPeers + update sequence and awaits
+   * it. Resume itself is cheap: the next attempt reuses the blocks already
+   * cached in the core (the output file is re-streamed from those blocks, not
+   * appended to).
+   *
+   * Honours `signal`: a foreground cancel during the (bounded but up to
+   * RESUME_WAIT_MAX_MS) swarm/peer waits aborts promptly instead of blocking
+   * until peers return or the cap elapses.
+   */
+  async _reconnectCore (core, signal) {
+    if (!core || !this.hyperswarm) return
+    if (signal && signal.aborted) throw new Error('Download cancelled')
+
+    await this._waitForSwarmResumed(signal)
+
+    this.logger.debug('Re-establishing peers before download retry', {
+      discoveryKey: IdEnc.normalize(core.discoveryKey)
+    })
+
+    const done = core.findingPeers()
+    this.hyperswarm.join(core.discoveryKey, { client: true, server: false })
+    try {
+      await this.hyperswarm.flush()
+    } finally {
+      done()
+    }
+    await this._waitForPeers(core, signal)
+    await core.update()
+  }
+
   async downloadModel (path, source, options = {}) {
     this._validateString(path, 'path')
     this._validateString(source, 'source')
@@ -266,7 +347,11 @@ class QVACRegistryClient extends ReadyResource {
           {
             maxRetries: options.maxRetries != null ? options.maxRetries : DEFAULT_DOWNLOAD_MAX_RETRIES,
             retryCodes: RETRIABLE_DOWNLOAD_CODES,
-            onRetry: () => fs.promises.unlink(options.outputFile).catch(() => {}),
+            // Wait for the swarm to resume + reconnect peers before retrying,
+            // so the retry doesn't immediately time out again against a dead
+            // swarm (e.g. after the app backgrounded). The core's cached blocks
+            // are not cleared until success, so the retry re-streams cheaply.
+            beforeRetry: () => this._reconnectCore(core, options.signal),
             logger: this.logger
           }
         )
@@ -398,7 +483,9 @@ class QVACRegistryClient extends ReadyResource {
           {
             maxRetries: options.maxRetries != null ? options.maxRetries : DEFAULT_DOWNLOAD_MAX_RETRIES,
             retryCodes: RETRIABLE_DOWNLOAD_CODES,
-            onRetry: () => fs.promises.unlink(options.outputFile).catch(() => {}),
+            // Wait for swarm resume + peer reconnect before retrying (see
+            // downloadModel). Cached blocks are reused; the file is re-streamed.
+            beforeRetry: () => this._reconnectCore(core, options.signal),
             logger: this.logger
           }
         )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/registry-client",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "QVAC Registry client library for read-only queries via Hyperswarm",
   "license": "Apache-2.0",
   "repository": {
@@ -53,12 +53,15 @@
   },
   "dependencies": {
     "@qvac/error": "^0.1.0",
-    "@qvac/registry-schema": "^0.2.0",
+    "@qvac/registry-schema": "^0.3.0",
     "b4a": "^1.6.7",
     "bare-fs": "^4.5.2",
     "bare-os": "^3.6.2",
     "bare-path": "^3.0.0",
     "bare-process": "^4.2.2",
+    "corestore": "^7.4.5",
+    "hyperblobs": "^2.8.0",
+    "hyperswarm": "^4.14.0",
     "hypercore-id-encoding": "^1.3.0",
     "hypercore-stats": "^2.4.0",
     "hyperswarm-stats": "^1.3.0",
@@ -66,19 +69,9 @@
     "ready-resource": "^1.0.1",
     "tiny-byte-size": "^1.1.0"
   },
-  "peerDependencies": {
-    "corestore": "^7.4.5",
-    "hyperblobs": "^2.8.0",
-    "hyperdb": "^4.16.1",
-    "hyperswarm": "^4.14.0"
-  },
   "devDependencies": {
     "brittle": "^3.4.0",
-    "corestore": "^7.4.5",
     "dotenv": "^17.2.3",
-    "hyperblobs": "^2.8.0",
-    "hyperdb": "^4.16.1",
-    "hyperswarm": "^4.14.0",
     "standard": "^17.1.0",
     "test-tmp": "^1.4.0",
     "typescript": "^5.9.3"

package/utils/retry.js

@@ -8,11 +8,14 @@
  * @param {number} [opts.maxRetries=3] - Maximum number of attempts (including the first)
  * @param {string[]} [opts.retryCodes=[]] - Error codes that trigger a retry
  * @param {() => Promise<void>} [opts.onRetry] - Called before each retry attempt (e.g. cleanup)
+ * @param {() => Promise<void>} [opts.beforeRetry] - Awaited before the next attempt runs.
+ *   Use to re-establish prerequisites (e.g. wait for peers to reconnect) so the
+ *   retry doesn't immediately fail again against a dead connection.
  * @param {{ warn: Function }} [opts.logger] - Logger instance for retry warnings
  * @returns {Promise<unknown>}
  */
 async function withRetry (fn, opts = {}) {
-  const { maxRetries = 3, retryCodes = [], onRetry, logger } = opts
+  const { maxRetries = 3, retryCodes = [], onRetry, beforeRetry, logger } = opts
 
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
     try {
@@ -22,6 +25,7 @@ async function withRetry (fn, opts = {}) {
       if (!isRetriable || attempt >= maxRetries) throw err
       logger && logger.warn(`Retrying after ${err.code} (attempt ${attempt}/${maxRetries}): ${err.message}`)
       if (onRetry) await onRetry()
+      if (beforeRetry) await beforeRetry()
     }
   }
 }