@bsv/sdk 2.1.1 → 2.1.3

package/src/overlay-tools/LookupResolver.ts

@@ -1,4 +1,5 @@
 import { Transaction } from '../transaction/index.js'
+import { Beef } from '../transaction/Beef.js'
 import OverlayAdminTokenTemplate from './OverlayAdminTokenTemplate.js'
 import * as Utils from '../primitives/utils.js'
 import { getOverlayHostReputationTracker, HostReputationTracker } from './HostReputationTracker.js'
@@ -35,6 +36,8 @@ export type LookupAnswer =
       beef: number[]
       outputIndex: number
       context?: number[]
+      /** Optional txid hint. When present, consumers can skip re-parsing beef to derive the txid. */
+      txid?: string
     }>
   }
 
@@ -65,7 +68,7 @@ export interface LookupQueryOptions {
  */
 export interface LookupAnswerProgress {
   type: 'output-list'
-  outputs: Array<{ beef: number[], outputIndex: number, context?: number[] }>
+  outputs: Array<{ beef: number[], outputIndex: number, context?: number[], txid?: string }>
   /** Parallel array of resolved tx ids for each output (same index as `outputs`). */
   txIds: string[]
   /** True only for the final emission, after every in-flight host has settled. */
@@ -102,6 +105,73 @@ export const DEFAULT_TESTNET_SLAP_TRACKERS: string[] = [
 
 const MAX_TRACKER_WAIT_TIME = 5000
 
+/** A wall-clock deadline that rejects after `timeoutMs`, optionally aborting a controller. */
+interface Deadline {
+  /** Rejects with `Error('Request timed out')` once the timer fires. */
+  promise: Promise<never>
+  /** Clears the underlying timer. Safe to call after the timer has already fired. */
+  cancel: () => void
+  /** Returns true once the timer has fired. */
+  didTimeOut: () => boolean
+}
+
+function createDeadline (timeoutMs: number, controller?: AbortController): Deadline {
+  let expired = false
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const promise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      expired = true
+      try { controller?.abort() } catch { /* noop */ }
+      reject(new Error('Request timed out'))
+    }, timeoutMs)
+  })
+  return {
+    promise,
+    cancel: () => {
+      if (timer !== null) clearTimeout(timer)
+    },
+    didTimeOut: () => expired
+  }
+}
+
+function normalizeLookupError (err: unknown, timedOut: boolean): Error {
+  if (timedOut) return new Error('Request timed out')
+  if ((err as { name?: string })?.name === 'AbortError') return new Error('Request timed out')
+  if (err instanceof Error) return err
+  return new Error(stringifyErrorValue(err))
+}
+
+/**
+ * Coerce a non-Error thrown value to a human-readable string without falling
+ * back to the default `'[object Object]'` for plain objects.
+ */
+function stringifyErrorValue (value: unknown): string {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  if (typeof value === 'string') return value
+  if (typeof value === 'number') return value.toString()
+  if (typeof value === 'boolean') return value ? 'true' : 'false'
+  if (typeof value === 'bigint') return value.toString()
+  const message = (value as { message?: unknown }).message
+  if (typeof message === 'string' && message.length > 0) return message
+  try {
+    return JSON.stringify(value) ?? 'Unknown error'
+  } catch {
+    return 'Unknown error'
+  }
+}
+
+/**
+ * Returns true when the given Content-Type header value represents
+ * `application/octet-stream`, ignoring case and any media-type parameters
+ * (e.g. `; charset=utf-8`).
+ */
+function isOctetStream (contentType: string | null): boolean {
+  if (typeof contentType !== 'string') return false
+  const baseType = contentType.split(';', 1)[0].trim().toLowerCase()
+  return baseType === 'application/octet-stream'
+}
+
 /** Internal cache options. Kept optional to preserve drop-in compatibility. */
 interface CacheOptions {
   /** How long (ms) a hosts entry is considered fresh. Default 5 minutes. */
@@ -178,62 +248,89 @@ export class HTTPSOverlayLookupFacilitator implements OverlayLookupFacilitator {
     }
 
     const controller = typeof AbortController === 'undefined' ? undefined : new AbortController()
-    const timer = setTimeout(() => {
-      try { controller?.abort() } catch { /* noop */ }
-    }, timeout)
+    const deadline = createDeadline(timeout, controller)
+
+    // Hard wall-clock deadline: in some environments (e.g. browser/Electron CORS
+    // failures) the underlying fetch can stall without ever settling, and the
+    // AbortController signal alone is insufficient to make the returned promise
+    // resolve or reject. Race the fetch against a setTimeout-backed reject so
+    // the consumer-facing promise always settles within `timeout` ms.
+    const fetchPromise = this.performLookupRequest(url, question, controller?.signal)
+    // Swallow background rejection if the deadline wins first.
+    fetchPromise.catch(() => { /* noop */ })
 
     try {
-      const fco: RequestInit = {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-Aggregation': 'yes'
-        },
-        body: JSON.stringify({ service: question.service, query: question.query }),
-        signal: controller?.signal
-      }
-      const response: Response = await this.fetchClient(`${url}/lookup`, fco)
-
-      if (!response.ok) throw new Error(`Failed to facilitate lookup (HTTP ${response.status})`)
-      if (response.headers.get('content-type') === 'application/octet-stream') {
-        const payload = await response.arrayBuffer()
-        const r = new Utils.Reader([...new Uint8Array(payload)])
-        const nOutpoints = r.readVarIntNum()
-        const outpoints: Array<{ txid: string, outputIndex: number, context?: number[] }> = []
-        for (let i = 0; i < nOutpoints; i++) {
-          const txid = Utils.toHex(r.read(32))
-          const outputIndex = r.readVarIntNum()
-          const contextLength = r.readVarIntNum()
-          let context
-          if (contextLength > 0) {
-            context = r.read(contextLength)
-          }
-          outpoints.push({
-            txid,
-            outputIndex,
-            context
-          })
-        }
-        const beef = r.read()
-        return {
-          type: 'output-list',
-          outputs: outpoints.map(x => ({
-            outputIndex: x.outputIndex,
-            context: x.context,
-            beef: Transaction.fromBEEF(beef, x.txid).toBEEF()
-          }))
-        }
-      } else {
-        return await response.json()
-      }
+      return await Promise.race([fetchPromise, deadline.promise])
     } catch (e) {
-      // Normalize timeouts to a consistent error message
-      if ((e as { name?: string })?.name === 'AbortError') throw new Error('Request timed out')
-      throw e
+      throw normalizeLookupError(e, deadline.didTimeOut())
     } finally {
-      clearTimeout(timer)
+      deadline.cancel()
     }
   }
+
+  private async performLookupRequest (
+    url: string,
+    question: LookupQuestion,
+    signal: AbortSignal | undefined
+  ): Promise<LookupAnswer> {
+    const fco: RequestInit = {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Aggregation': 'yes'
+      },
+      body: JSON.stringify({ service: question.service, query: question.query }),
+      signal
+    }
+    const response: Response = await this.fetchClient(`${url}/lookup`, fco)
+    if (!response.ok) throw new Error(`Failed to facilitate lookup (HTTP ${response.status})`)
+    if (isOctetStream(response.headers.get('content-type'))) {
+      return await this.parseOctetStreamLookup(response)
+    }
+    return await response.json()
+  }
+
+  /** Parse the aggregated octet-stream lookup response into an output-list LookupAnswer. */
+  private async parseOctetStreamLookup (response: Response): Promise<LookupAnswer> {
+    const payload = await response.arrayBuffer()
+    const r = new Utils.Reader([...new Uint8Array(payload)])
+    const nOutpoints = r.readVarIntNum()
+    const outpoints: Array<{ txid: string, outputIndex: number, context?: number[] }> = []
+    for (let i = 0; i < nOutpoints; i++) {
+      const txid = Utils.toHex(r.read(32))
+      const outputIndex = r.readVarIntNum()
+      const contextLength = r.readVarIntNum()
+      const context = contextLength > 0 ? r.read(contextLength) : undefined
+      outpoints.push({ txid, outputIndex, context })
+    }
+    const beef = r.read()
+    const beefObj = Beef.fromBinary(beef)
+    const outputs = await this.extractAtomicOutputs(outpoints, beefObj)
+    return { type: 'output-list', outputs }
+  }
+
+  /** Memoize per-txid atomic BEEF extraction, yielding to the event loop between outputs. */
+  private async extractAtomicOutputs (
+    outpoints: Array<{ txid: string, outputIndex: number, context?: number[] }>,
+    beefObj: Beef
+  ): Promise<Array<{ outputIndex: number, context?: number[], beef: number[], txid: string }>> {
+    const beefByTxid = new Map<string, number[]>()
+    const outputs: Array<{ outputIndex: number, context?: number[], beef: number[], txid: string }> = new Array(outpoints.length)
+    for (let idx = 0; idx < outpoints.length; idx++) {
+      const x = outpoints[idx]
+      let beefBytes = beefByTxid.get(x.txid)
+      if (beefBytes === undefined) {
+        beefBytes = beefObj.toBinaryAtomic(x.txid)
+        beefByTxid.set(x.txid, beefBytes)
+      }
+      outputs[idx] = { outputIndex: x.outputIndex, context: x.context, beef: beefBytes, txid: x.txid }
+      // Yield to event loop so UI animations and other JS don't starve.
+      if (idx > 0 && idx < outpoints.length - 1) {
+        await new Promise<void>((resolve) => setTimeout(resolve, 0))
+      }
+    }
+    return outputs
+  }
 }
 
 /**
@@ -296,13 +393,18 @@ export default class LookupResolver {
     timeout?: number,
     options?: LookupQueryOptions
   ): Promise<LookupAnswer> {
-    let last: LookupAnswerProgress | null = null
     // Existing fast-but-narrow contract: return at the first cumulative emission
     // (the post-grace aggregate, or the final emission when every host settles
     // before the grace window). Callers wanting progressive enrichment use query$().
-    for await (const partial of this.query$(question, timeout, options)) {
-      last = partial
-      break
+    // Take only the first emission, then explicitly close the iterator so the
+    // generator's `finally` block runs and clears any outstanding timers.
+    const iter = this.query$(question, timeout, options)[Symbol.asyncIterator]()
+    let last: LookupAnswerProgress | null = null
+    try {
+      const { value, done } = await iter.next()
+      if (done !== true && value != null) last = value
+    } finally {
+      await iter.return?.(undefined)
     }
     return {
       type: 'output-list',
@@ -401,31 +503,16 @@ export default class LookupResolver {
     let graceFired = false
     let emittedOnce = false
 
-    const beefKey = (beef: number[] | undefined): string => {
-      if (typeof beef !== 'object' || beef == null) return ''
-      return beef.join(',')
-    }
-
     const mergeAnswer = (answer: LookupAnswer): boolean => {
       let added = false
+      const now = Date.now()
       for (const output of answer.outputs) {
-        const keyForBeef = beefKey(output.beef)
-        let memo = this.txMemo.get(keyForBeef)
-        const now = Date.now()
-        if (typeof memo !== 'object' || memo === null || memo.expiresAt <= now) {
-          try {
-            const txId = Transaction.fromBEEF(output.beef).id('hex')
-            memo = { txId, expiresAt: now + this.txMemoTtlMs }
-            if (this.txMemo.size > 4096) this.evictOldest(this.txMemo)
-            this.txMemo.set(keyForBeef, memo)
-          } catch {
-            continue
-          }
-        }
-        const uniqKey = `${memo.txId}.${output.outputIndex}`
+        const txId = this.resolveTxIdForOutput(output, now)
+        if (txId === null) continue
+        const uniqKey = `${txId}.${output.outputIndex}`
         if (!outputsMap.has(uniqKey)) {
           outputsMap.set(uniqKey, output)
-          txIds.push(memo.txId)
+          txIds.push(txId)
           added = true
         }
       }
@@ -603,7 +690,7 @@ export default class LookupResolver {
               resolve([...allHosts])
             }
           })
-          .catch(() => { /* tracker failed; tracked by lookupHostWithTracking */ })
+          .catch(() => { /* tracker failure tracked in reputation */ })
           .finally(() => {
             pending--
             if (pending === 0 && !resolved) {
@@ -615,7 +702,34 @@ export default class LookupResolver {
     })
   }
 
-  /** Evict an arbitrary “oldest” entry from a Map (iteration order). */
+  /**
+   * Resolve a txid for an aggregated lookup output. Uses the threaded-through `output.txid`
+   * fast path when present; otherwise memoizes Transaction.fromBEEF(beef).id('hex') keyed by
+   * the BEEF byte sequence. Returns null when the BEEF is unparseable.
+   */
+  private resolveTxIdForOutput (
+    output: { txid?: string, beef: number[], outputIndex: number, context?: number[] },
+    now: number
+  ): string | null {
+    if (typeof output.txid === 'string' && output.txid.length > 0) {
+      return output.txid
+    }
+    const keyForBeef = Array.isArray(output.beef) ? output.beef.join(',') : ''
+    const memo = this.txMemo.get(keyForBeef)
+    if (typeof memo === 'object' && memo !== null && memo.expiresAt > now) {
+      return memo.txId
+    }
+    try {
+      const txId = Transaction.fromBEEF(output.beef).id('hex')
+      if (this.txMemo.size > 4096) this.evictOldest(this.txMemo)
+      this.txMemo.set(keyForBeef, { txId, expiresAt: now + this.txMemoTtlMs })
+      return txId
+    } catch {
+      return null
+    }
+  }
+
+  /** Evict an arbitrary "oldest" entry from a Map (iteration order). */
   private evictOldest<T>(m: Map<string, T>): void {
     const firstKey = m.keys().next().value
     if (firstKey !== undefined) m.delete(firstKey)

package/src/overlay-tools/__tests/LookupResolver.additional.test.ts

@@ -472,6 +472,22 @@ describe('LookupResolver – additional coverage', () => {
       ).rejects.toThrow('Request timed out')
     })
 
+    it('rejects within the timeout even when fetch never settles', async () => {
+      // Simulate the CORS-blocked / hung-preflight case where the fetch promise
+      // does not honor the AbortController signal and never settles.
+      const neverFetch = jest.fn().mockImplementation(
+        () => new Promise(() => { /* never resolves */ })
+      )
+      const facilitator = new HTTPSOverlayLookupFacilitator(neverFetch, true)
+      const start = Date.now()
+      await expect(
+        facilitator.lookup('http://host', { service: 'ls_test', query: {} }, 50)
+      ).rejects.toThrow('Request timed out')
+      const elapsed = Date.now() - start
+      // Allow generous slack but must complete well before any global jest timeout.
+      expect(elapsed).toBeLessThan(2000)
+    })
+
     it('parses octet-stream responses', async () => {
       // Build a minimal octet-stream payload: 1 outpoint, then BEEF bytes
       const tx = new Transaction(
@@ -506,6 +522,36 @@ describe('LookupResolver – additional coverage', () => {
       expect(result.outputs[0].outputIndex).toBe(0)
     })
 
+    it('parses octet-stream responses when header carries parameters or differing case', async () => {
+      const tx = new Transaction(
+        1,
+        [],
+        [{ lockingScript: LockingScript.fromHex('88'), satoshis: 1 }],
+        0
+      )
+      const beef = tx.toBEEF()
+      const txid = Buffer.from(tx.id('hex'), 'hex')
+      const payload = Buffer.concat([
+        Buffer.from([0x01]), txid, Buffer.from([0x00]), Buffer.from([0x00]), Buffer.from(beef)
+      ])
+
+      for (const header of [
+        'application/octet-stream; charset=utf-8',
+        'Application/Octet-Stream',
+        '  application/octet-stream  '
+      ]) {
+        const mockFetch = jest.fn().mockResolvedValue({
+          ok: true,
+          headers: { get: () => header },
+          arrayBuffer: async () => payload.buffer.slice(payload.byteOffset, payload.byteOffset + payload.byteLength)
+        })
+        const facilitator = new HTTPSOverlayLookupFacilitator(mockFetch, true)
+        const result = await facilitator.lookup('https://host', { service: 'ls_test', query: {} })
+        expect(result.type).toBe('output-list')
+        expect(result.outputs).toHaveLength(1)
+      }
+    })
+
     it('parses octet-stream responses with context bytes', async () => {
       const tx = new Transaction(
         1,
@@ -547,6 +593,50 @@ describe('LookupResolver – additional coverage', () => {
       ).rejects.toThrow('DNS failure')
     })
 
+    it('normalises string thrown values from fetch', async () => {
+      const mockFetch = jest.fn().mockRejectedValue('boom')
+      const facilitator = new HTTPSOverlayLookupFacilitator(mockFetch, true)
+      await expect(
+        facilitator.lookup('https://host', { service: 'ls_test', query: {} })
+      ).rejects.toThrow('boom')
+    })
+
+    it('normalises object-with-message thrown values from fetch', async () => {
+      const mockFetch = jest.fn().mockRejectedValue({ message: 'object boom' })
+      const facilitator = new HTTPSOverlayLookupFacilitator(mockFetch, true)
+      await expect(
+        facilitator.lookup('https://host', { service: 'ls_test', query: {} })
+      ).rejects.toThrow('object boom')
+    })
+
+    it('normalises plain-object thrown values via JSON', async () => {
+      const mockFetch = jest.fn().mockRejectedValue({ code: 42 })
+      const facilitator = new HTTPSOverlayLookupFacilitator(mockFetch, true)
+      await expect(
+        facilitator.lookup('https://host', { service: 'ls_test', query: {} })
+      ).rejects.toThrow('{"code":42}')
+    })
+
+    it('normalises number/boolean/null thrown values from fetch', async () => {
+      for (const value of [123, true, null]) {
+        const mockFetch = jest.fn().mockRejectedValue(value)
+        const facilitator = new HTTPSOverlayLookupFacilitator(mockFetch, true)
+        await expect(
+          facilitator.lookup('https://host', { service: 'ls_test', query: {} })
+        ).rejects.toThrow(String(value))
+      }
+    })
+
+    it('normalises circular thrown values without crashing', async () => {
+      const circular: { self?: unknown } = {}
+      circular.self = circular
+      const mockFetch = jest.fn().mockRejectedValue(circular)
+      const facilitator = new HTTPSOverlayLookupFacilitator(mockFetch, true)
+      await expect(
+        facilitator.lookup('https://host', { service: 'ls_test', query: {} })
+      ).rejects.toThrow('Unknown error')
+    })
+
     it('sends correct request body to /lookup endpoint', async () => {
       const mockFetch = jest.fn().mockResolvedValue({
         ok: true,