@bsv/sdk 1.4.1 → 1.4.2

package/docs/storage.md

@@ -6,6 +6,8 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 | |
 | --- |
+| [DownloadResult](#interface-downloadresult) |
+| [DownloaderConfig](#interface-downloaderconfig) |
 | [UploadFileResult](#interface-uploadfileresult) |
 | [UploadableFile](#interface-uploadablefile) |
 | [UploaderConfig](#interface-uploaderconfig) |
@@ -14,6 +16,29 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ---
 
+### Interface: DownloadResult
+
+```ts
+export interface DownloadResult {
+    data: Buffer;
+    mimeType: string | null;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+### Interface: DownloaderConfig
+
+```ts
+export interface DownloaderConfig {
+    networkPreset: string;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
 ### Interface: UploadFileResult
 
 ```ts
@@ -54,6 +79,32 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ---
 ## Classes
 
+| |
+| --- |
+| [StorageDownloader](#class-storagedownloader) |
+| [StorageUploader](#class-storageuploader) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+
+### Class: StorageDownloader
+
+Locates HTTP URLs where content can be downloaded. It uses the passed or the default one.
+
+```ts
+export class StorageDownloader {
+    constructor(config?: DownloaderConfig) 
+    public async resolve(uhrpUrl: string): Promise<string[]> 
+    public async download(uhrpUrl: string) 
+}
+```
+
+See also: [DownloaderConfig](./storage.md#interface-downloaderconfig)
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
 ### Class: StorageUploader
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/sdk",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "type": "module",
   "description": "BSV Blockchain Software Development Kit",
   "main": "dist/cjs/mod.js",

package/src/storage/StorageDownloader.ts

@@ -0,0 +1,91 @@
+import { LookupResolver } from '../overlay-tools/index.js'
+import { StorageUtils } from './index.js'
+import PushDrop from '../script/templates/PushDrop.js'
+import Transaction from '../transaction/Transaction.js'
+import { Hash, Utils } from '../primitives/index.js'
+
+export interface DownloaderConfig {
+  networkPreset: 'mainnet' | 'testnet' | 'local'
+}
+
+export interface DownloadResult {
+  data: number[]
+  mimeType: string | null
+}
+
+/**
+ * Locates HTTP URLs where content can be downloaded. It uses the passed or the default one.
+ *
+ * @param {Object} obj All parameters are passed in an object.
+ * @param {String} obj.uhrpUrl The UHRP url to resolve.
+ * @param {string} obj.confederacyHost HTTPS URL for for the with default setting.
+ *
+ * @return {Array<String>} An array of HTTP URLs where content can be downloaded.
+ * @throws {Error} If UHRP url parameter invalid or is not an array
+ * or there is an error retrieving url(s) stored in the UHRP token.
+ */
+export class StorageDownloader {
+  private readonly networkPreset?: 'mainnet' | 'testnet' | 'local' = 'mainnet'
+
+  constructor (config?: DownloaderConfig) {
+    this.networkPreset = config?.networkPreset
+  }
+
+  public async resolve (uhrpUrl: string): Promise<string[]> {
+    // Use UHRP lookup service
+    const lookupResolver = new LookupResolver({ networkPreset: this.networkPreset })
+    const response = await lookupResolver.query({ service: 'ls_uhrp', query: { uhrpUrl } })
+    if (response.type !== 'output-list') {
+      throw new Error('Lookup answer must be an output list')
+    }
+    const decodedResults: string[] = []
+    for (let i = 0; i < response.outputs.length; i++) {
+      const tx = Transaction.fromBEEF(response.outputs[i].beef)
+      const { fields } = PushDrop.decode(tx.outputs[response.outputs[i].outputIndex].lockingScript)
+      decodedResults.push(Utils.toUTF8(fields[2]))
+    }
+    return decodedResults
+  }
+
+  public async download (uhrpUrl: string): Promise<DownloadResult> {
+    if (!StorageUtils.isValidURL(uhrpUrl)) {
+      throw new Error('Invalid parameter UHRP url')
+    }
+    const hash = StorageUtils.getHashFromURL(uhrpUrl)
+    const downloadURLs = await this.resolve(uhrpUrl)
+
+    if (!Array.isArray(downloadURLs) || downloadURLs.length === 0) {
+      throw new Error('No one currently hosts this file!')
+    }
+
+    for (let i = 0; i < downloadURLs.length; i++) {
+      try {
+        // The url is fetched
+        const result = await fetch(downloadURLs[i], { method: 'GET' })
+
+        // If the request fails, continue to the next url
+        if (!result.ok || result.status >= 400) {
+          continue
+        }
+        const body = await result.arrayBuffer()
+
+        // The body is loaded into a number array
+        const content: number[] = [...new Uint8Array(body)]
+        const contentHash = Hash.sha256(content)
+        for (let i = 0; i < contentHash.length; ++i) {
+          if (contentHash[i] !== hash[i]) {
+            throw new Error('Value of content does not match hash of the url given')
+          }
+        }
+
+        return {
+          data: content,
+          mimeType: result.headers.get('Content-Type')
+        }
+      } catch (error) {
+        continue
+      }
+    }
+    throw new Error(`Unable to download content from ${uhrpUrl}`)
+  }
+}

package/src/storage/__test/StorageDownloader.test.ts

@@ -0,0 +1,170 @@
+import { StorageDownloader } from '../StorageDownloader.js'
+import { StorageUtils } from '../index.js'
+import { LookupResolver } from '../../overlay-tools/index.js'
+import Transaction from '../../transaction/Transaction.js'
+import PushDrop from '../../script/templates/PushDrop.js'
+import { Hash, PublicKey } from '../../primitives/index.js'
+import { Utils } from '../../primitives/index.js'
+
+beforeEach(() => {
+    jest.restoreAllMocks()
+})
+
+describe('StorageDownloader', () => {
+    let downloader: StorageDownloader
+
+    beforeEach(() => {
+        // Create a fresh instance
+        downloader = new StorageDownloader()
+    })
+
+    describe('resolve()', () => {
+        it('throws if the lookup response is not "output-list"', async () => {
+            // Mock the LookupResolver to return something invalid
+            jest.spyOn(LookupResolver.prototype, 'query').mockResolvedValue({
+                type: 'something-else',
+                outputs: []
+            } as any)
+
+            await expect(downloader.resolve('fakeUhrpUrl'))
+                .rejects
+                .toThrow('Lookup answer must be an output list')
+        })
+
+        it('decodes each output with Transaction.fromBEEF and PushDrop.decode', async () => {
+            // 1) Mock lookup response
+            jest.spyOn(LookupResolver.prototype, 'query').mockResolvedValue({
+                type: 'output-list',
+                outputs: [
+                    { beef: 'fake-beef-a', outputIndex: 0 },
+                    { beef: 'fake-beef-b', outputIndex: 1 }
+                ]
+            } as any)
+
+            // 2) Mock Transaction.fromBEEF -> returns a dummy transaction
+            jest.spyOn(Transaction, 'fromBEEF').mockImplementation(() => {
+                // Each transaction might have multiple outputs; we only care about `outputIndex`
+                return {
+                    outputs: [
+                        { lockingScript: {} }, // index 0
+                        { lockingScript: {} }  // index 1
+                    ]
+                } as any
+            })
+
+            // 3) Mock PushDrop.decode -> returns { fields: number[][] }
+            jest.spyOn(PushDrop, 'decode').mockImplementation(() => {
+                // The decode function returns an object with `fields`,
+                return {
+                    lockingPublicKey: {} as PublicKey,
+                    fields: [
+                        [11],
+                        [22],
+                        [104, 116, 116, 112, 58, 47, 47, 97, 46, 99, 111, 109]
+                    ]
+                }
+            })
+
+            // 4) Mock Utils.toUTF8 to convert that number[] to a string
+            jest.spyOn(Utils, 'toUTF8').mockReturnValue('http://a.com')
+
+            const resolved = await downloader.resolve('fakeUhrpUrl')
+            expect(resolved).toEqual(['http://a.com', 'http://a.com'])
+        })
+    })
+
+    describe('download()', () => {
+        it('throws if UHRP URL is invalid', async () => {
+            jest.spyOn(StorageUtils, 'isValidURL').mockReturnValue(false)
+
+            await expect(downloader.download('invalidUrl'))
+                .rejects
+                .toThrow('Invalid parameter UHRP url')
+        })
+
+        it('throws if no hosts are found', async () => {
+            // Valid UHRP URL
+            jest.spyOn(StorageUtils, 'isValidURL').mockReturnValue(true)
+            // Return some random 32-byte hash so we can pass the check
+            jest.spyOn(StorageUtils, 'getHashFromURL').mockReturnValue(new Array(32).fill(0))
+
+            // Force resolve() to return an empty array
+            jest.spyOn(downloader, 'resolve').mockResolvedValue([])
+
+            await expect(downloader.download('validButUnhostedUrl'))
+                .rejects
+                .toThrow('No one currently hosts this file!')
+        })
+
+        it('downloads successfully from the first working host', async () => {
+            jest.spyOn(StorageUtils, 'isValidURL').mockReturnValue(true)
+            const knownHash = [
+                102, 104, 122, 173, 248, 98, 189, 119, 108, 143,
+                193, 139, 142, 159, 142, 32, 8, 151, 20, 133,
+                110, 226, 51, 179, 144, 42, 89, 29, 13, 95,
+                41, 37
+              ]
+            jest.spyOn(StorageUtils, 'getHashFromURL').mockReturnValue(knownHash)
+
+            // Suppose two possible download URLs
+            jest.spyOn(downloader, 'resolve').mockResolvedValue([
+                'http://host1/404',
+                'http://host2/ok'
+            ])
+
+            // The first fetch -> 404, second fetch -> success
+            const fetchSpy = jest.spyOn(global, 'fetch')
+                .mockResolvedValueOnce(new Response(null, { status: 404 }))
+                .mockResolvedValueOnce(new Response(new Uint8Array(32).fill(0), {
+                    status: 200,
+                    headers: { 'Content-Type': 'application/test' }
+                }))
+
+            const result = await downloader.download('validUrl')
+            expect(fetchSpy).toHaveBeenCalledTimes(2)
+            expect(result).toEqual({
+                data: new Array(32).fill(0),
+                mimeType: 'application/test'
+            })
+        })
+
+        it('throws if content hash mismatches the UHRP hash', async () => {
+            jest.spyOn(StorageUtils, 'isValidURL').mockReturnValue(true)
+            // The expected hash is all zeros
+            jest.spyOn(StorageUtils, 'getHashFromURL').mockReturnValue(new Array(32).fill(0))
+
+            // One potential host
+            jest.spyOn(downloader, 'resolve').mockResolvedValue([
+                'http://bad-content.test'
+            ])
+
+            // The fetch returns 32 bytes of all 1's => hash mismatch
+            jest.spyOn(global, 'fetch').mockResolvedValue(
+                new Response(new Uint8Array(32).fill(1), { status: 200 })
+            )
+
+            await expect(downloader.download('validButBadHashUrl'))
+                .rejects
+                .toThrow()
+        })
+
+        it('throws if all hosts fail or mismatch', async () => {
+            jest.spyOn(StorageUtils, 'isValidURL').mockReturnValue(true)
+            jest.spyOn(StorageUtils, 'getHashFromURL').mockReturnValue(new Array(32).fill(0))
+
+            jest.spyOn(downloader, 'resolve').mockResolvedValue([
+                'http://host1.test',
+                'http://host2.test'
+            ])
+
+            // Both fetches fail with 500 or something >=400
+            jest.spyOn(global, 'fetch').mockResolvedValue(
+                new Response(null, { status: 500 })
+            )
+
+            await expect(downloader.download('validButNoGoodHostUrl'))
+                .rejects
+                .toThrow('Unable to download content from validButNoGoodHostUrl')
+        })
+    })
+})

package/src/storage/index.ts

@@ -1,2 +1,5 @@
 export * as StorageUtils from './StorageUtils.js'
+
 export { StorageUploader } from './StorageUploader.js'
+
+export { StorageDownloader } from './StorageDownloader.js'