@qvac/registry-client 0.1.8 → 0.2.1

package/README.md

@@ -1,4 +1,4 @@
-# @tetherto/qvac-lib-registry-client
+# @qvac/registry-client
 
 Read-only client library for querying the QVAC Registry. It replicates the registry HyperDB via Hyperswarm and provides APIs for searching and retrieving model information.
 
@@ -13,7 +13,7 @@ Read-only client library for querying the QVAC Registry. It replicates the regis
 ## Installation
 
 ```bash
-npm install @tetherto/qvac-lib-registry-client
+npm install @qvac/registry-client
 ```
 
 Ensure the registry core key is available via environment variables or provided via options.
@@ -24,7 +24,7 @@ Ensure the registry core key is available via environment variables or provided
 
 ```javascript
 'use strict'
-const { QVACRegistryClient } = require('@tetherto/qvac-lib-registry-client')
+const { QVACRegistryClient } = require('@qvac/registry-client')
 
 async function main () {
   const client = new QVACRegistryClient({
@@ -106,18 +106,45 @@ const fs = require('fs')
 result.artifact.stream.pipe(fs.createWriteStream('./model.ggml'))
 ```
 
+#### Direct Blob Download
+
+- `downloadBlob(blobBinding, options)`: Downloads a blob directly using known blob coordinates, bypassing the metadata core lookup. Useful when `coreKey`, `blockOffset`, `blockLength`, and `byteLength` are already known (e.g., from a previous query or generated model constants).
+  - `blobBinding`: `{ coreKey, blockOffset, blockLength, byteOffset, byteLength }` — `coreKey` accepts Buffer, hex, or z-base-32 strings
+  - `options`:
+    - `timeout`: Download timeout in ms (default: 30000)
+    - `outputFile`: Optional file path to save directly to disk
+    - `onProgress`: Callback `({ downloaded, total, cachedBlocks, totalBlocks }) => void`
+    - `signal`: `AbortSignal` for cancellation
+  - Returns: `{ artifact: { path, totalSize } | { stream, totalSize } }`
+
+This method only waits for the network layer (Corestore + Hyperswarm) — it does not wait for the metadata core to sync, making it faster for known blob coordinates.
+
+```javascript
+const result = await client.downloadBlob({
+  coreKey: 'ey46cahego89xox118uhyryakz47bcs8bbxu97tnnpmuwmgi5wmo',
+  blockOffset: 0,
+  blockLength: 665,
+  byteOffset: 0,
+  byteLength: 43537433
+}, {
+  outputFile: './downloaded/ggml-tiny-q8_0.bin',
+  timeout: 60000
+})
+console.log('Downloaded to:', result.artifact.path)
+```
+
 ## CLI
 
 The package includes a CLI for querying and downloading models from the registry.
 
 ### Install
 
-The package is hosted on GitHub Packages. Configure npm to use the GitHub registry for the `@tetherto` scope, then install globally:
+The package is hosted on npm. Configure npm to use the registry for the `@qvac` scope, then install globally:
 
 ```bash
-echo "@tetherto:registry=https://npm.pkg.github.com" >> ~/.npmrc
-echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc
-npm install -g @tetherto/registry-client-mono
+echo "@qvac:registry=https://registry.npmjs.org" >> ~/.npmrc
+echo "//registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN" >> ~/.npmrc
+npm install -g @qvac/registry-client
 ```
 
 Verify installation:
@@ -220,7 +247,8 @@ $ qvac-registry list --engine @qvac/transcription-whispercpp --json | jq '.[0].p
 See the `examples/` folder for complete working examples:
 
 - `example.js`: List models, query by engine/name/quantization, find shards
-- `download-model.js`: Download a single model to disk
+- `download-model.js`: Download a single model to disk via metadata lookup
+- `download-blob.js`: Download a blob directly using known blob coordinates
 - `download-all-models.js`: Download all models in the registry
 
 Run examples:
@@ -229,6 +257,7 @@ Run examples:
 cd client
 node examples/example.js
 node examples/download-model.js
+node examples/download-blob.js
 node examples/download-all-models.js
 ```
 
@@ -271,8 +300,8 @@ The client uses custom error codes in the range 19001-20000. All errors extend `
 ### Error Handling Example
 
 ```javascript
-const { QVACRegistryClient } = require('@tetherto/qvac-lib-registry-client')
-const { QvacErrorRegistryClient } = require('@tetherto/qvac-lib-registry-client/utils/error')
+const { QVACRegistryClient } = require('@qvac/registry-client')
+const { QvacErrorRegistryClient } = require('@qvac/registry-client/utils/error')
 
 async function handleErrors () {
   const client = new QVACRegistryClient({

package/index.d.ts

@@ -1,5 +1,5 @@
 export interface QVACBlobBinding {
-  coreKey: Buffer
+  coreKey: Buffer | string
   blockOffset: number
   blockLength: number
   byteOffset: number
@@ -43,6 +43,17 @@ export interface QVACDownloadOptions {
   outputFile?: string
 }
 
+export interface QVACBlobDownloadOptions {
+  timeout?: number
+  outputFile?: string
+  onProgress?: (progress: { downloaded: number, total: number, cachedBlocks: number, totalBlocks: number }) => void
+  signal?: AbortSignal
+}
+
+export interface QVACBlobDownloadResult {
+  artifact: QVACDownloadedArtifact & { totalSize: number }
+}
+
 export interface QVACRegistryClientOptions {
   storage?: string
   registryCoreKey?: string
@@ -75,6 +86,7 @@ export class QVACRegistryClient {
 
   getModel (path: string, source: string): Promise<QVACModelEntry | null>
   downloadModel (path: string, source: string, options?: QVACDownloadOptions): Promise<QVACDownloadResult>
+  downloadBlob (blobBinding: QVACBlobBinding, options?: QVACBlobDownloadOptions): Promise<QVACBlobDownloadResult>
 
   findBy (params?: FindByParams): Promise<QVACModelEntry[]>
   findModels (query?: QVACModelQuery): Promise<QVACModelEntry[]>

package/lib/client.js

@@ -23,6 +23,7 @@ class QVACRegistryClient extends ReadyResource {
     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)
@@ -38,11 +39,6 @@ class QVACRegistryClient extends ReadyResource {
   async _open () {
     this.logger.debug('_open called')
 
-    if (!this.registryCoreKey) {
-      this.logger.error('Missing registry core key for read mode')
-      throw new QvacErrorRegistryClient({ code: ERR_CODES.FAILED_TO_CONNECT, adds: 'Missing registry core key. Set QVAC_REGISTRY_CORE_KEY environment variable.' })
-    }
-
     this.logger.debug('Creating corestore for open')
     this.corestore = new Corestore(this.storage)
     await this.corestore.ready()
@@ -56,6 +52,15 @@ class QVACRegistryClient extends ReadyResource {
     }
     this.hyperswarm.on('connection', this._connectionHandler)
 
+    this._metadataReady = this._connectMetadataCore()
+  }
+
+  async _connectMetadataCore () {
+    if (!this.registryCoreKey) {
+      this.logger.error('Missing registry core key for read mode')
+      throw new QvacErrorRegistryClient({ code: ERR_CODES.FAILED_TO_CONNECT, adds: 'Missing registry core key. Set QVAC_REGISTRY_CORE_KEY environment variable.' })
+    }
+
     const viewKey = IdEnc.decode(this.registryCoreKey)
     const viewCore = this.corestore.get({ key: viewKey })
     await viewCore.ready()
@@ -65,28 +70,37 @@ class QVACRegistryClient extends ReadyResource {
       discoveryKey: IdEnc.normalize(viewCore.discoveryKey)
     })
 
+    const foundPeers = viewCore.findingPeers()
     this.hyperswarm.join(viewCore.discoveryKey, { client: true, server: false })
-    await this.hyperswarm.flush()
+    this.hyperswarm.flush().then(() => foundPeers())
 
     this.logger.debug('Waiting for view core sync')
-    await viewCore.update({ wait: true })
+    await viewCore.update()
 
     this.logger.debug('Creating RegistryDatabase from view core')
     this.db = new RegistryDatabase(viewCore, { extension: false })
     await this.db.ready()
 
-    this.logger.debug('QVACRegistryClient ready', {
+    this.logger.debug('QVACRegistryClient metadata ready', {
       length: viewCore.length
     })
   }
 
+  async _ensureMetadata () {
+    await this.ready()
+    await this._metadataReady
+    if (!this.db) {
+      throw new QvacErrorRegistryClient({ code: ERR_CODES.FAILED_TO_CONNECT, adds: 'Registry database not available.' })
+    }
+  }
+
   async getModel (path, source) {
     this._validateString(path, 'path')
     this._validateString(source, 'source')
 
     try {
       this.logger.info('Getting model', { path, source })
-      await this.ready()
+      await this._ensureMetadata()
 
       const result = await this.db.getModel(path, source)
       this.logger.debug('getModel result', { result })
@@ -98,7 +112,7 @@ class QVACRegistryClient extends ReadyResource {
   }
 
   async findModels (query = {}, opts = {}) {
-    await this.ready()
+    await this._ensureMetadata()
     const { includeDeprecated = false } = opts
     this.logger.debug('findModels called', { query, includeDeprecated })
 
@@ -112,19 +126,19 @@ class QVACRegistryClient extends ReadyResource {
   }
 
   async findModelsByEngine (query = {}) {
-    await this.ready()
+    await this._ensureMetadata()
     this.logger.debug('findModelsByEngine called', { query })
     return this.db.findModelsByEngine(query).toArray()
   }
 
   async findModelsByName (query = {}) {
-    await this.ready()
+    await this._ensureMetadata()
     this.logger.debug('findModelsByName called', { query })
     return this.db.findModelsByName(query).toArray()
   }
 
   async findModelsByQuantization (query = {}) {
-    await this.ready()
+    await this._ensureMetadata()
     this.logger.debug('findModelsByQuantization called', { query })
     return this.db.findModelsByQuantization(query).toArray()
   }
@@ -140,7 +154,7 @@ class QVACRegistryClient extends ReadyResource {
    * @returns {Promise<Array>} Array of matching models
    */
   async findBy (params = {}) {
-    await this.ready()
+    await this._ensureMetadata()
     this.logger.debug('findBy called', { params })
     return this.db.findBy(params)
   }
@@ -169,9 +183,14 @@ class QVACRegistryClient extends ReadyResource {
   }
 
   async _getBlobsCore (blobsCoreKey) {
-    const keyBuffer = Buffer.isBuffer(blobsCoreKey)
-      ? blobsCoreKey
-      : Buffer.from(blobsCoreKey.data || blobsCoreKey, 'hex')
+    let keyBuffer
+    if (Buffer.isBuffer(blobsCoreKey)) {
+      keyBuffer = blobsCoreKey
+    } else if (typeof blobsCoreKey === 'object' && blobsCoreKey.data) {
+      keyBuffer = Buffer.from(blobsCoreKey.data)
+    } else {
+      keyBuffer = IdEnc.decode(blobsCoreKey)
+    }
 
     this.logger.debug('Creating hyperblobs core', {
       blobCore: IdEnc.normalize(keyBuffer)
@@ -198,7 +217,7 @@ class QVACRegistryClient extends ReadyResource {
 
     try {
       this.logger.info('Downloading model', { path, source })
-      await this.ready()
+      await this._ensureMetadata()
 
       const model = await this.getModel(path, source)
       if (!model) {
@@ -219,19 +238,30 @@ class QVACRegistryClient extends ReadyResource {
         discoveryKey: IdEnc.normalize(core.discoveryKey)
       })
 
+      const foundBlobPeers = core.findingPeers()
       this.hyperswarm.join(core.discoveryKey, { client: true, server: false })
-      await this.hyperswarm.flush()
+      this.hyperswarm.flush().then(() => foundBlobPeers())
 
-      await core.update({ wait: true })
+      await core.update()
       this.logger.debug('Blobs core updated')
 
       const totalSize = model.blobBinding.byteLength
 
+      const rangeDownload = core.download({
+        start: model.blobBinding.blockOffset,
+        length: model.blobBinding.blockLength
+      })
+
+      const blockStart = model.blobBinding.blockOffset
+      const blockEnd = blockStart + model.blobBinding.blockLength
+
       let artifact
       if (options.outputFile) {
         await this._streamBlobToFile(blobs, core, model.blobBinding, options.outputFile, options)
         artifact = { path: options.outputFile, totalSize }
 
+        rangeDownload.destroy()
+        await this._clearBlobBlocks(core, blockStart, blockEnd)
         if (blobs) await blobs.close()
         if (core) await core.close()
       } else {
@@ -242,6 +272,8 @@ class QVACRegistryClient extends ReadyResource {
         artifact = { stream, totalSize }
 
         const cleanup = async () => {
+          rangeDownload.destroy()
+          await this._clearBlobBlocks(core, blockStart, blockEnd)
           if (blobs) {
             try {
               await blobs.close()
@@ -259,7 +291,7 @@ class QVACRegistryClient extends ReadyResource {
           this.logger.debug('Blob resources closed after stream end')
         }
 
-        stream.on('close', cleanup)
+        stream.once('end', cleanup)
       }
 
       this.logger.info('Model downloaded successfully')
@@ -290,6 +322,129 @@ class QVACRegistryClient extends ReadyResource {
     }
   }
 
+  async downloadBlob (blobBinding, options = {}) {
+    if (!blobBinding || !blobBinding.coreKey) {
+      throw new Error('Invalid blobBinding: coreKey is required')
+    }
+    if (typeof blobBinding.blockOffset !== 'number' ||
+        typeof blobBinding.blockLength !== 'number' ||
+        typeof blobBinding.byteLength !== 'number') {
+      throw new Error('Invalid blobBinding: blockOffset, blockLength, and byteLength are required numbers')
+    }
+
+    if (options && typeof options !== 'object') {
+      throw new Error(`Invalid options: ${typeof options}`)
+    }
+
+    let core, blobs
+
+    try {
+      this.logger.info('Downloading blob directly', {
+        coreKey: typeof blobBinding.coreKey === 'string' ? blobBinding.coreKey.slice(0, 12) + '...' : '(buffer)',
+        blockOffset: blobBinding.blockOffset,
+        blockLength: blobBinding.blockLength,
+        byteLength: blobBinding.byteLength
+      })
+
+      await this.ready()
+
+      const blobsCore = await this._getBlobsCore(blobBinding.coreKey)
+      core = blobsCore.core
+      blobs = blobsCore.blobs
+
+      this.logger.debug('Joining swarm for blobs core (direct)', {
+        discoveryKey: IdEnc.normalize(core.discoveryKey)
+      })
+
+      const foundBlobPeers = core.findingPeers()
+      this.hyperswarm.join(core.discoveryKey, { client: true, server: false })
+      this.hyperswarm.flush().then(() => foundBlobPeers())
+
+      await core.update()
+      this.logger.debug('Blobs core updated (direct)')
+
+      const pointer = {
+        blockOffset: blobBinding.blockOffset,
+        blockLength: blobBinding.blockLength,
+        byteOffset: blobBinding.byteOffset || 0,
+        byteLength: blobBinding.byteLength
+      }
+      const totalSize = blobBinding.byteLength
+
+      const blockStart = pointer.blockOffset
+      const blockEnd = blockStart + pointer.blockLength
+
+      const rangeDownload = core.download({
+        start: pointer.blockOffset,
+        length: pointer.blockLength
+      })
+
+      let artifact
+      if (options.outputFile) {
+        await this._streamBlobToFile(blobs, core, pointer, options.outputFile, options)
+        artifact = { path: options.outputFile, totalSize }
+
+        rangeDownload.destroy()
+        await this._clearBlobBlocks(core, blockStart, blockEnd)
+        if (blobs) await blobs.close()
+        if (core) await core.close()
+      } else {
+        const stream = blobs.createReadStream(pointer, {
+          wait: true,
+          timeout: options.timeout || 30000
+        })
+        artifact = { stream, totalSize }
+
+        const cleanup = async () => {
+          rangeDownload.destroy()
+          await this._clearBlobBlocks(core, blockStart, blockEnd)
+          if (blobs) {
+            try { await blobs.close() } catch (e) {
+              this.logger.warn('Error closing blob instance', { error: e.message })
+            }
+          }
+          if (core) {
+            try { await core.close() } catch (e) {
+              this.logger.warn('Error closing blob core', { error: e.message })
+            }
+          }
+          this.logger.debug('Blob resources closed after stream end')
+        }
+
+        stream.once('end', cleanup)
+      }
+
+      this.logger.info('Blob download complete (direct)')
+
+      return { artifact }
+    } catch (error) {
+      this.logger.error('Error downloading blob directly', error)
+
+      if (blobs) {
+        try { await blobs.close() } catch (e) {
+          this.logger.warn('Error closing blob instance on error', { error: e.message })
+        }
+      }
+      if (core) {
+        try { await core.close() } catch (e) {
+          this.logger.warn('Error closing blob core on error', { error: e.message })
+        }
+      }
+
+      throw error
+    }
+  }
+
+  async _clearBlobBlocks (core, start, end) {
+    try {
+      const cleared = await core.clear(start, end, { diff: true })
+      await core.compact()
+      this.logger.info('Cleared blob blocks from corestore', { start, end, blocks: cleared ? cleared.blocks : end - start })
+    } catch (err) {
+      this.logger.warn('Failed to clear blob blocks from corestore', { error: err.message })
+    }
+  }
+
   async _streamBlobToFile (blobs, core, blobPointer, filePath, options) {
     const { cachedBlocks, totalBlocks, totalBytes } = await this._checkBlobProgress(core, blobPointer)
 
@@ -329,6 +484,11 @@ class QVACRegistryClient extends ReadyResource {
 
     core.on('download', progressHandler)
 
+    const rangeDownload = core.download({
+      start: blobPointer.blockOffset,
+      length: blobPointer.blockLength
+    })
+
     const stream = blobs.createReadStream(blobPointer, {
       wait: true,
       timeout: options.timeout || 30000
@@ -361,6 +521,7 @@ class QVACRegistryClient extends ReadyResource {
         }
       })
     } finally {
+      rangeDownload.destroy()
       core.off('download', progressHandler)
     }
   }
@@ -368,6 +529,11 @@ class QVACRegistryClient extends ReadyResource {
   async _close () {
     this.logger.debug('_close called')
 
+    if (this._metadataReady) {
+      await this._metadataReady.catch(() => {})
+      this._metadataReady = null
+    }
+
     if (this.db) {
       this.logger.debug('Closing database')
       await this.db.close()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/registry-client",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "description": "QVAC Registry client library for read-only queries via Hyperswarm",
   "license": "Apache-2.0",
   "type": "commonjs",