@qvac/registry-client 0.3.0 → 0.4.1

package/NOTICE

@@ -51,42 +51,6 @@ Third-Party Model Licenses
     https://huggingface.co/personalizedrefrigerator/whisper-base-fr
   fr-tiny-ggml-model-f16
     https://huggingface.co/JaepaX/whisper-tiny-fr
-  ggml-opus-ar-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-ar-en
-  ggml-opus-de-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-de-en
-  ggml-opus-de-fr
-    https://huggingface.co/Helsinki-NLP/opus-mt-de-fr
-  ggml-opus-en-ar
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-ar
-  ggml-opus-en-es
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-es
-  ggml-opus-en-fr
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-fr
-  ggml-opus-en-it
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-it
-  ggml-opus-en-ru
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-ru
-  ggml-opus-en-zh
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-zh
-  ggml-opus-es-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-es-en
-  ggml-opus-es-fr
-    https://huggingface.co/Helsinki-NLP/opus-mt-es-fr
-  ggml-opus-fr-de
-    https://huggingface.co/Helsinki-NLP/opus-mt-fr-de
-  ggml-opus-fr-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-fr-en
-  ggml-opus-fr-es
-    https://huggingface.co/Helsinki-NLP/opus-mt-fr-es
-  ggml-opus-it-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-it-en
-  ggml-opus-ja-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-ja-en
-  ggml-opus-mt-en-roa-f16
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-roa
-  ggml-opus-mt-roa-en-f16
-    https://huggingface.co/Helsinki-NLP/opus-mt-roa-en
   gpt-oss-20b-GGUF
     https://huggingface.co/unsloth/gpt-oss-20b-GGUF
   it-base-ggml-model-f16
@@ -128,17 +92,6 @@ Third-Party Model Licenses
   SmolVLM2-500M-Video-Instruct-GGUF
     https://huggingface.co/ggml-org/SmolVLM2-500M-Video-Instruct-GGUF
 
---- cc-by-4.0 (Creative Commons Attribution 4.0 International) ---
-
-  ggml-opus-en-de
-    https://huggingface.co/Helsinki-NLP/opus-mt-en-de
-  ggml-opus-en-pt
-    https://huggingface.co/Helsinki-NLP/opus-mt-tc-big-en-pt
-  ggml-opus-ru-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-ru-en
-  ggml-opus-zh-en
-    https://huggingface.co/Helsinki-NLP/opus-mt-zh-en
-
 --- gemma (Gemma Terms of Use) ---
 
   embeddinggemma-300m-GGUF

package/README.md

@@ -139,11 +139,9 @@ The package includes a CLI for querying and downloading models from the registry
 
 ### Install
 
-The package is hosted on npm. Configure npm to use the registry for the `@qvac` scope, then install globally:
+The package is hosted on npm. Install globally:
 
 ```bash
-echo "@qvac:registry=https://registry.npmjs.org" >> ~/.npmrc
-echo "//registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN" >> ~/.npmrc
 npm install -g @qvac/registry-client
 ```
 

package/index.d.ts

@@ -1,3 +1,9 @@
+import ReadyResource = require('ready-resource')
+
+export interface LifecycleLogOptions {
+  log?: (msg: string) => Promise<void> | void
+}
+
 export interface QVACBlobBinding {
   coreKey: Buffer | string
   blockOffset: number
@@ -41,6 +47,8 @@ export interface QVACDownloadOptions {
   timeout?: number
   peerTimeout?: number
   outputFile?: string
+  onProgress?: (progress: { downloaded: number, total: number, cachedBlocks: number, totalBlocks: number }) => void
+  signal?: AbortSignal
 }
 
 export interface QVACBlobDownloadOptions {
@@ -58,6 +66,7 @@ export interface QVACRegistryClientOptions {
   storage?: string
   registryCoreKey?: string
   logger?: any
+  corestoreOpts?: { wait?: boolean }
 }
 
 export interface QVACModelQuery {
@@ -78,11 +87,29 @@ export interface FindByParams {
   includeDeprecated?: boolean
 }
 
-export class QVACRegistryClient {
+export interface LifecycleSwarmHandle {
+  readonly suspended: boolean
+  suspend (opts?: LifecycleLogOptions): Promise<void>
+  resume (opts?: LifecycleLogOptions): Promise<void>
+}
+
+export interface LifecycleStoreHandle {
+  suspend (opts?: LifecycleLogOptions): Promise<void>
+  resume (): Promise<void>
+}
+
+export class QVACRegistryClient extends ReadyResource {
   constructor (opts?: QVACRegistryClientOptions)
 
+  /** Valid only while the client remains open. Cached handles become stale after close(). */
+  readonly corestore: LifecycleStoreHandle | null
+  /** Valid only while the client remains open. Cached handles become stale after close(). */
+  readonly hyperswarm: LifecycleSwarmHandle | null
+
   ready (): Promise<void>
   close (): Promise<void>
+  suspend (opts?: LifecycleLogOptions): Promise<void>
+  resume (opts?: LifecycleLogOptions): Promise<void>
 
   getModel (path: string, source: string): Promise<QVACModelEntry | null>
   downloadModel (path: string, source: string, options?: QVACDownloadOptions): Promise<QVACDownloadResult>

package/lib/client.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const { QvacErrorRegistryClient, ERR_CODES } = require('../utils/error')
+const { withRetry } = require('../utils/retry')
 const RegistryConfig = require('./config')
 const { RegistryDatabase } = require('@qvac/registry-schema')
 const ReadyResource = require('ready-resource')
@@ -12,6 +13,9 @@ const IdEnc = require('hypercore-id-encoding')
 const path = require('#path')
 const fs = require('#fs')
 
+const DEFAULT_DOWNLOAD_MAX_RETRIES = 3
+const RETRIABLE_DOWNLOAD_CODES = ['REQUEST_TIMEOUT']
+
 class QVACRegistryClient extends ReadyResource {
   constructor (opts = {}) {
     super()
@@ -20,13 +24,13 @@ class QVACRegistryClient extends ReadyResource {
     this.registryConfig = new RegistryConfig({ logger: this.logger })
 
     this.db = null
-    this.corestore = null
     this.hyperswarm = null
     this._connectionHandler = null
     this._metadataReady = null
 
     this.storage = this.registryConfig.getRegistryStorage(opts.storage)
     this.registryCoreKey = this.registryConfig.getRegistryCoreKey(opts.registryCoreKey)
+    this.corestore = new Corestore(this.storage, opts.corestoreOpts || {})
 
     this.logger.debug('Initializing QVAC Registry Client', {
       mode: 'read',
@@ -39,8 +43,7 @@ class QVACRegistryClient extends ReadyResource {
   async _open () {
     this.logger.debug('_open called')
 
-    this.logger.debug('Creating corestore for open')
-    this.corestore = new Corestore(this.storage)
+    this.logger.debug('Opening corestore')
     await this.corestore.ready()
 
     this.logger.debug('Creating Hyperswarm for open')
@@ -257,7 +260,15 @@ class QVACRegistryClient extends ReadyResource {
 
       let artifact
       if (options.outputFile) {
-        await this._streamBlobToFile(blobs, core, model.blobBinding, options.outputFile, options)
+        await withRetry(
+          () => this._streamBlobToFile(blobs, core, model.blobBinding, options.outputFile, options),
+          {
+            maxRetries: options.maxRetries != null ? options.maxRetries : DEFAULT_DOWNLOAD_MAX_RETRIES,
+            retryCodes: RETRIABLE_DOWNLOAD_CODES,
+            onRetry: () => fs.promises.unlink(options.outputFile).catch(() => {}),
+            logger: this.logger
+          }
+        )
         artifact = { path: options.outputFile, totalSize }
 
         rangeDownload.destroy()
@@ -381,7 +392,15 @@ class QVACRegistryClient extends ReadyResource {
 
       let artifact
       if (options.outputFile) {
-        await this._streamBlobToFile(blobs, core, pointer, options.outputFile, options)
+        await withRetry(
+          () => this._streamBlobToFile(blobs, core, pointer, options.outputFile, options),
+          {
+            maxRetries: options.maxRetries != null ? options.maxRetries : DEFAULT_DOWNLOAD_MAX_RETRIES,
+            retryCodes: RETRIABLE_DOWNLOAD_CODES,
+            onRetry: () => fs.promises.unlink(options.outputFile).catch(() => {}),
+            logger: this.logger
+          }
+        )
         artifact = { path: options.outputFile, totalSize }
 
         rangeDownload.destroy()
@@ -526,6 +545,42 @@ class QVACRegistryClient extends ReadyResource {
     }
   }
 
+  async suspend (opts = {}) {
+    this.logger.debug('suspend called')
+
+    if (!this.opened || this.closing) {
+      this.logger.debug('Skipping suspend while client is not open or is closing')
+      return
+    }
+
+    if (this.hyperswarm && !this.hyperswarm.suspended) {
+      await this.hyperswarm.suspend(opts)
+    }
+    if (this.corestore) {
+      await this.corestore.suspend(opts)
+    }
+
+    this.logger.debug('QVACRegistryClient suspended')
+  }
+
+  async resume (opts = {}) {
+    this.logger.debug('resume called')
+
+    if (!this.opened || this.closing) {
+      this.logger.debug('Skipping resume while client is not open or is closing')
+      return
+    }
+
+    if (this.corestore) {
+      await this.corestore.resume()
+    }
+    if (this.hyperswarm && this.hyperswarm.suspended) {
+      await this.hyperswarm.resume(opts)
+    }
+
+    this.logger.debug('QVACRegistryClient resumed')
+  }
+
   async _close () {
     this.logger.debug('_close called')
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/registry-client",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "QVAC Registry client library for read-only queries via Hyperswarm",
   "license": "Apache-2.0",
   "repository": {
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@qvac/error": "^0.1.0",
-    "@qvac/registry-schema": "^0.1.1",
+    "@qvac/registry-schema": "^0.1.2",
     "b4a": "^1.6.7",
     "bare-fs": "^4.5.2",
     "bare-os": "^3.6.2",
@@ -62,8 +62,8 @@
     "corestore": "^7.4.5",
     "hyperblobs": "^2.8.0",
     "hypercore-id-encoding": "^1.3.0",
-    "hyperdb": "^4.16.1",
     "hypercore-stats": "^2.4.0",
+    "hyperdb": "^4.16.1",
     "hyperswarm": "^4.14.0",
     "hyperswarm-stats": "^1.3.0",
     "paparam": "^1.10.0",

package/utils/retry.js

@@ -0,0 +1,29 @@
+'use strict'
+
+/**
+ * Executes an async function with automatic retry on specific error codes.
+ *
+ * @param {() => Promise<unknown>} fn - The async operation to attempt
+ * @param {object} opts
+ * @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 {{ warn: Function }} [opts.logger] - Logger instance for retry warnings
+ * @returns {Promise<unknown>}
+ */
+async function withRetry (fn, opts = {}) {
+  const { maxRetries = 3, retryCodes = [], onRetry, logger } = opts
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn()
+    } catch (err) {
+      const isRetriable = retryCodes.length > 0 && retryCodes.includes(err && err.code)
+      if (!isRetriable || attempt >= maxRetries) throw err
+      logger && logger.warn(`Retrying after ${err.code} (attempt ${attempt}/${maxRetries}): ${err.message}`)
+      if (onRetry) await onRetry()
+    }
+  }
+}
+
+module.exports = { withRetry }