libp2r2p 0.10.19 → 0.10.21

package/relay/services/relay-pool.js

@@ -1,6 +1,7 @@
 import { ValidationError } from '../../error/index.js'
 import { decodeHll, encodeHll, estimateHllCount, mergeHll } from '../helpers/hll.js'
 import { createPublishSettlements, firstFulfillment, publishSummary } from '../helpers/publish.js'
+import { ReadAdmission } from '../helpers/read-admission.js'
 import { drainableStream } from '../helpers/drainable-stream.js'
 import { maybeUnref } from '../helpers/timer.js'
 import { categorizeRelayError } from '../helpers/error.js'
@@ -91,6 +92,12 @@ function assertReadOptions (filter, timeouts) {
   }
 }
 
+function assertBufferOptions (options) {
+  for (const value of [options.maxBufferedLiveEvents === undefined ? 1000 : options.maxBufferedLiveEvents, options.maxBufferedLiveBytes === undefined ? 8 * 1024 * 1024 : options.maxBufferedLiveBytes]) {
+    if (!Number.isSafeInteger(value) || value < 1) throw new ValidationError('INVALID_RELAY_BUFFER_CAPACITY')
+  }
+}
+
 function normalizedRelayUrls (relays) {
   const urls = []
   const seen = new Set()
@@ -127,14 +134,19 @@ export class RelayPool {
   #liveSubCounts = new Map() // url -> number of active live subscriptions
   #timeout = 30000 // 30 seconds
   #createRelay
+  #admission
 
-  constructor ({ _createRelay = url => new RelayConnection(url) } = {}) {
+  constructor ({ _createRelay = url => new RelayConnection(url), ...capacity } = {}) {
     this.#createRelay = _createRelay
+    this.#admission = new ReadAdmission(capacity)
   }
 
   #scheduleIdleDisconnect (url) {
     clearTimeout(this.#relayTimeouts.get(url))
-    this.#relayTimeouts.set(url, maybeUnref(setTimeout(() => this.disconnect(url), this.#timeout)))
+    this.#relayTimeouts.set(url, maybeUnref(setTimeout(() => {
+      if (this.#admission.states.get(url)?.active) this.#scheduleIdleDisconnect(url)
+      else this.disconnect(url)
+    }, this.#timeout)))
   }
 
   // Opens a normalized pooled connection. Failed connects are evicted so a later
@@ -191,6 +203,7 @@ export class RelayPool {
   // Disconnect from a relay
   async disconnect (url) {
     const normalizedUrl = normalizeRelayUrl(url)
+    this.#admission.cancelQueued(normalizedUrl)
     if (this.#relays.has(normalizedUrl)) {
       const relay = this.#relays.get(normalizedUrl)
       if (relay.ws?.readyState < 2) await relay.close()?.catch(console.log)
@@ -202,7 +215,7 @@ export class RelayPool {
 
   // Disconnect from all relays
   async disconnectAll () {
-    for (const url of [...this.#relays.keys()]) {
+    for (const url of new Set([...this.#relays.keys(), ...this.#admission.states.keys()])) {
       await this.disconnect(url)
     }
   }
@@ -352,8 +365,8 @@ export class RelayPool {
   // grace window; null disables that window so callers wait for every relay or
   // the operation deadline. Disabling cross-relay deduplication still suppresses
   // repeated ids from the same relay; callbacks remain immediate in both modes.
-  async getEvents (filter, relays, { timeout = 5000, timeoutAfterFirstEose = 500, callback, signal, deduplicateAcrossRelays = true } = {}) {
-    assertReadOptions(filter, { timeout, timeoutAfterFirstEose })
+  async getEvents (filter, relays, { timeout = 5000, timeoutAfterFirstEose = 500, callback, signal, deduplicateAcrossRelays = true, queueTimeout = 30000, _admissions } = {}) {
+    assertReadOptions(filter, { timeout, timeoutAfterFirstEose, queueTimeout })
     if (typeof deduplicateAcrossRelays !== 'boolean') throw new ValidationError('INVALID_DEDUPLICATE_ACROSS_RELAYS')
     if (signal?.aborted) throw new Error('Aborted')
     const urls = normalizedRelayUrls(relays)
@@ -364,15 +377,21 @@ export class RelayPool {
     const eventIds = deduplicateAcrossRelays ? new Set() : null
     let isResolved = false
     let eoseTimer = null
-    let timeoutTimer = null
+    const timers = new Map()
+    const leases = new Map()
+    const admissionAbort = new AbortController()
+    const admissionSignal = signal ? AbortSignal.any([signal, admissionAbort.signal]) : admissionAbort.signal
 
     return await new Promise((resolve, reject) => {
       const cleanup = () => {
-        clearTimeout(timeoutTimer)
+        admissionAbort.abort()
+        for (const timer of timers.values()) clearTimeout(timer)
         clearTimeout(eoseTimer)
         signal?.removeEventListener('abort', onAbort)
         for (const sub of subscriptions.values()) sub.close()
         subscriptions.clear()
+        for (const lease of leases.values()) lease.release()
+        leases.clear()
       }
       const fail = error => {
         if (isResolved) return
@@ -386,6 +405,11 @@ export class RelayPool {
       const settleRelay = (relay, status, error) => {
         if (isResolved || outcomes.has(relay)) return
         outcomes.set(relay, { relay, status, ...(error ? { error } : {}) })
+        clearTimeout(timers.get(relay))
+        subscriptions.get(relay)?.close()
+        subscriptions.delete(relay)
+        leases.get(relay)?.release()
+        leases.delete(relay)
         if (error) {
           errors.push({ relay, reason: error })
           notify({ type: 'error', relay, error })
@@ -412,12 +436,22 @@ export class RelayPool {
       const finishIfComplete = () => { if (outcomes.size === urls.length) finish() }
       const onAbort = () => fail(new Error('Aborted'))
       signal?.addEventListener('abort', onAbort, { once: true })
-      if (timeout !== null) timeoutTimer = maybeUnref(setTimeout(() => finish('timeout'), timeout))
       if (!urls.length) { finish(); return }
 
       for (const url of urls) {
         const seenIds = eventIds ?? new Set()
-        this.#getRelay(url).then(relay => {
+        const reservation = _admissions?.get(url) ?? this.#admission.acquire(normalizeRelayUrl(url), { history: true, signal: admissionSignal, queueTimeout })
+        reservation.then(async slots => {
+          const lease = slots.history
+          if (isResolved || outcomes.has(url)) { lease.release(); return }
+          leases.set(url, lease)
+          if (timeout !== null) {
+            timers.set(url, maybeUnref(setTimeout(() => {
+              settleRelay(url, 'timeout', getEventsTimeoutError())
+              finishIfComplete()
+            }, timeout)))
+          }
+          const relay = await this.#getRelay(url)
           if (isResolved || outcomes.has(url)) return
           let hasEvents = false
           // Subscription callbacks may run before subscribe() returns.
@@ -467,7 +501,11 @@ export class RelayPool {
     })
   }
 
-  async * getEventsGenerator (filter, relays, options = {}) {
+  getEventsGenerator (filter, relays, options = {}) {
+    return drainableStream(options => this.#getEventsGenerator(filter, relays, options), options)
+  }
+
+  async * #getEventsGenerator (filter, relays, options = {}) {
     const queue = []
     let p = Promise.withResolvers()
     let isDone = false
@@ -504,7 +542,8 @@ export class RelayPool {
   // Returns a strictly-live stream. `ready` reports the first initial EOSE window,
   // while `readyRelays` follows relays that are currently past their own EOSE.
   getLiveEventsGenerator (filter, relays, options = {}) {
-    assertReadOptions(filter, { timeout: options.timeout === undefined ? 5000 : options.timeout, timeoutAfterFirstEose: options.timeoutAfterFirstEose === undefined ? 500 : options.timeoutAfterFirstEose })
+    assertBufferOptions(options)
+    assertReadOptions(filter, { timeout: options.timeout === undefined ? 5000 : options.timeout, timeoutAfterFirstEose: options.timeoutAfterFirstEose === undefined ? 500 : options.timeoutAfterFirstEose, queueTimeout: options.queueTimeout === undefined ? 30000 : options.queueTimeout })
     const ready = Promise.withResolvers()
     const readyRelays = new Set()
     const stream = drainableStream(options => this.#getLiveEventsGenerator(filter, relays, options, { ready, readyRelays }), options)
@@ -530,6 +569,10 @@ export class RelayPool {
     _stopSignal,
     timeout = 5000,
     timeoutAfterFirstEose = 500,
+    queueTimeout = 30000,
+    _admissions,
+    maxBufferedLiveEvents = 1000,
+    maxBufferedLiveBytes = 8 * 1024 * 1024,
     timeoutForReconnectGap = 5000,
     timeoutAfterFirstReconnectGapEose = 500,
     _gapEventsGenerator = (...args) => this.getEventsGenerator(...args)
@@ -539,12 +582,17 @@ export class RelayPool {
     let p = Promise.withResolvers()
     let isDone = false
     let draining = false
+    let failure
+    let queuedBytes = 0
+    const encoder = new TextEncoder()
     const gapTasks = new Set()
     const liveSubs = new Map() // url → live sub
     const retryTimers = new Map()
     const initialPending = new Set(urls)
     const initialOutcomes = new Map()
-    let readyTimeout = null
+    const readyTimeouts = new Map()
+    const liveLeases = new Map()
+    const initialAdmissions = new Set()
     let readyTimer = null
     let isReady = false
 
@@ -566,16 +614,31 @@ export class RelayPool {
     const seenIds = new Set()
 
     let untilTimer = null
+    const overflow = relay => {
+      failure = Object.assign(new Error('RELAY_LIVE_BUFFER_FULL'), { code: 'RELAY_LIVE_BUFFER_FULL', relay, phase: 'live-buffer' })
+      teardown()
+    }
     const enqueue = item => {
-      queue.push(item)
+      const bytes = encoder.encode(JSON.stringify(item)).byteLength
+      if (queue.length >= maxBufferedLiveEvents || queuedBytes + bytes > maxBufferedLiveBytes) {
+        overflow(item.relay)
+        return
+      }
+      queuedBytes += bytes
+      queue.push({ item, bytes })
       p.resolve()
       p = Promise.withResolvers()
     }
+    const shift = () => {
+      const { item, bytes } = queue.shift()
+      queuedBytes -= bytes
+      return item
+    }
     const finishReady = (pendingStatus = 'cutoff', emit = true) => {
       if (isReady) return
       isReady = true
       clearTimeout(readyTimer)
-      clearTimeout(readyTimeout)
+      for (const timer of readyTimeouts.values()) clearTimeout(timer)
       for (const relay of initialPending) {
         const error = pendingStatus === 'timeout' ? getEventsTimeoutError() : undefined
         initialOutcomes.set(relay, { relay, status: pendingStatus, ...(error ? { error } : {}) })
@@ -594,7 +657,7 @@ export class RelayPool {
       if (isDone && (drain || !draining)) return
       draining = drain
       isDone = true
-      if (!drain) queue.length = 0
+      if (!drain) { queue.length = 0; queuedBytes = 0 }
       clearTimeout(untilTimer)
       finishReady('closed', false)
       gapAc.abort()
@@ -602,6 +665,8 @@ export class RelayPool {
       retryTimers.clear()
       liveSubs.forEach(sub => sub.close())
       liveSubs.clear()
+      for (const lease of liveLeases.values()) lease.release()
+      liveLeases.clear()
       p.resolve()
     }
 
@@ -625,13 +690,12 @@ export class RelayPool {
     signal?.addEventListener('abort', abort, { once: true })
     _stopSignal?.addEventListener('abort', stop, { once: true })
 
-    if (timeout !== null) readyTimeout = maybeUnref(setTimeout(() => finishReady('timeout'), timeout))
-
     const maybeFinishInitialReady = () => {
       if (initialPending.size === 0) finishReady()
     }
 
     const markInitialEose = (url) => {
+      clearTimeout(readyTimeouts.get(url))
       readyRelays.add(url)
       if (isReady || !initialPending.delete(url)) return
       initialOutcomes.set(url, { relay: url, status: 'eose' })
@@ -645,12 +709,14 @@ export class RelayPool {
       if (isDone) return
       enqueue({ type: 'error', relay: url, error })
       if (!isReady && initialPending.delete(url)) {
+        clearTimeout(readyTimeouts.get(url))
         initialOutcomes.set(url, { relay: url, status: 'error', error })
         maybeFinishInitialReady()
       }
     }
     const reportClosed = url => {
       if (!isReady && initialPending.delete(url)) {
+        clearTimeout(readyTimeouts.get(url))
         initialOutcomes.set(url, { relay: url, status: 'closed' })
         maybeFinishInitialReady()
       }
@@ -674,10 +740,12 @@ export class RelayPool {
 
     // Runs a reconnect gap fill for a single relay and returns a promise that resolves
     // when it completes. now is shared with the live sub so both use the same boundary.
-    const runReconnectGapFill = (url, gapSince, now) => {
+    const runReconnectGapFill = (url, gapSince, now, slots) => {
       const gapUntil = filterUntil !== null ? Math.min(now, filterUntil) : now
       const gapFilter = { ...baseFilter, since: gapSince, until: gapUntil }
       const gapGen = _gapEventsGenerator(gapFilter, [url], {
+        _admissions: new Map([[url, Promise.resolve(slots)]]),
+        queueTimeout,
         timeout: timeoutForReconnectGap,
         timeoutAfterFirstEose: timeoutAfterFirstReconnectGapEose,
         signal,
@@ -690,20 +758,41 @@ export class RelayPool {
         }
       })().catch(err => {
         reportFailure(url, asError(err))
-      })
+      }).finally(() => slots.history.release())
     }
 
     const subscribeToRelay = (url, gapSince, reconnectDelay = 1000) => {
-      const now = Math.floor(Date.now() / 1000)
+      let now = Math.floor(Date.now() / 1000)
       // Don't reconnect if we're past the until boundary
       if (filterUntil !== null && now >= filterUntil) return
-      this.#getRelay(url).then(relay => {
-        if (isDone) return
+      const reservation = !initialAdmissions.has(url) && _admissions?.get(url)
+      const recovering = gapSince !== null && gapSince > 0
+      let recoveryLease
+      initialAdmissions.add(url)
+      Promise.resolve(reservation || this.#admission.acquire(normalizeRelayUrl(url), { live: true, history: recovering, signal: gapAc.signal, queueTimeout })).then(async slots => {
+        const lease = slots.live
+        recoveryLease = recovering ? slots.history : null
+        if (isDone) { lease.release(); recoveryLease?.release(); return }
+        liveLeases.set(url, lease)
+        if (timeout !== null && initialPending.has(url)) {
+          readyTimeouts.set(url, maybeUnref(setTimeout(() => {
+            if (!initialPending.delete(url)) return
+            const error = getEventsTimeoutError()
+            initialOutcomes.set(url, { relay: url, status: 'timeout', error })
+            enqueue({ type: 'error', relay: url, error })
+            maybeFinishInitialReady()
+          }, timeout)))
+        }
+        const relay = await this.#getRelay(url)
+        if (isDone) { recoveryLease?.release(); return }
+        now = Math.floor(Date.now() / 1000)
+        if (filterUntil !== null && now >= filterUntil) { lease.release(); recoveryLease?.release(); return }
 
         // Buffer post-EOSE live events while a reconnect gap fill is running so
         // the historical gap is yielded before newer socket events.
         let liveBuffer = (gapSince !== null && gapSince > 0) ? [] : null
         let liveEose = false
+        let bufferedBytes = 0
 
         // Open the live sub first so the relay starts buffering incoming events
         // before we scan its database for the reconnect gap fill.
@@ -715,12 +804,21 @@ export class RelayPool {
             // A limit:0 relay may still send retained events before EOSE. Do not
             // expose them from a strictly-live stream.
             if (isDone || liveSubs.get(url) !== liveSub || !liveEose) return
-            if (liveBuffer) liveBuffer.push(event)
-            else pushEvent(event, url)
+            if (liveBuffer) {
+              const bytes = encoder.encode(JSON.stringify(event)).byteLength
+              if (liveBuffer.length >= maxBufferedLiveEvents || bufferedBytes + bytes > maxBufferedLiveBytes) {
+                overflow(url)
+                return
+              }
+              bufferedBytes += bytes
+              liveBuffer.push(event)
+            } else pushEvent(event, url)
           },
           onclose: error => {
             if (liveSubs.get(url) === liveSub) liveSubs.delete(url)
             else if (liveSubs.has(url)) return
+            lease.release()
+            if (liveLeases.get(url) === lease) liveLeases.delete(url)
             readyRelays.delete(url)
             if (!isDone) {
               if (error !== undefined) reportFailure(url, asError(error))
@@ -735,11 +833,11 @@ export class RelayPool {
             markInitialEose(url)
           }
         })
-        if (isDone) { liveSub.close(); return }
+        if (isDone) { liveSub.close(); recoveryLease?.release(); return }
         liveSubs.set(url, liveSub)
 
         if (gapSince !== null && gapSince > 0) {
-          const task = runReconnectGapFill(url, gapSince, now).finally(() => {
+          const task = runReconnectGapFill(url, gapSince, now, slots).finally(() => {
             const buf = liveBuffer
             liveBuffer = null
             for (const event of buf) pushEvent(event, url, true)
@@ -749,6 +847,9 @@ export class RelayPool {
           gapTasks.add(task)
         }
       }).catch(err => {
+        recoveryLease?.release()
+        liveLeases.get(url)?.release()
+        liveLeases.delete(url)
         readyRelays.delete(url)
         const reason = err instanceof Error ? err : new Error(String(err))
         reportFailure(url, reason)
@@ -759,7 +860,10 @@ export class RelayPool {
 
     if (!urls.length) {
       finishReady()
-      try { yield queue.shift() } finally {
+      try {
+        if (failure) throw failure
+        yield shift()
+      } finally {
         teardown()
         signal?.removeEventListener('abort', abort)
         _stopSignal?.removeEventListener('abort', stop)
@@ -776,9 +880,10 @@ export class RelayPool {
       // eslint-disable-next-line no-unmodified-loop-condition
       while (!isDone || (draining && gapTasks.size > 0) || queue.length > 0) {
         if (signal?.aborted) break
-        if (queue.length > 0) yield queue.shift()
+        if (queue.length > 0) yield shift()
         else { await p.promise; p = Promise.withResolvers() }
       }
+      if (failure) throw failure
     } finally {
       signal?.removeEventListener('abort', abort)
       _stopSignal?.removeEventListener('abort', stop)
@@ -789,8 +894,8 @@ export class RelayPool {
 
   // All-in-one event feed generator. For live:true, handles the full sequence:
   //
-  // - live:true (default): unless filter.limit === 0, starts the live sub immediately
-  //   (so no incoming events are missed), runs an initial one-shot fetch of stored events
+  // - live:true (default): unless filter.limit === 0, reserves live+history capacity,
+  //   starts live input, then runs an initial one-shot fetch of stored events
   //   concurrently, yields stored events first, then flushes buffered live events (deduped
   //   against stored ones), then yields live events indefinitely. With limit:0 the relay
   //   sends no stored events, so the fetch is skipped and only the live sub runs.
@@ -798,9 +903,13 @@ export class RelayPool {
   //   short-circuits after the fastest relay with events EOSEs, or waits for all
   //   relays when null.
   //
+  // snapshot:true captures a historical until after initial live readiness;
+  // that bound is reported in the history marker and never stops live input.
   // All underlying generators are injectable for testing.
   getEventsFeedGenerator (filter, relays, options = {}) {
-    assertReadOptions(filter, { timeout: options.timeout === undefined ? 5000 : options.timeout, timeoutAfterFirstEose: options.timeoutAfterFirstEose === undefined ? 500 : options.timeoutAfterFirstEose })
+    if (options.snapshot !== undefined && typeof options.snapshot !== 'boolean') throw new ValidationError('INVALID_RELAY_SNAPSHOT')
+    assertBufferOptions(options)
+    assertReadOptions(filter, { timeout: options.timeout === undefined ? 5000 : options.timeout, timeoutAfterFirstEose: options.timeoutAfterFirstEose === undefined ? 500 : options.timeoutAfterFirstEose, queueTimeout: options.queueTimeout === undefined ? 30000 : options.queueTimeout })
     return drainableStream(options => this.#getEventsFeedGenerator(filter, relays, options), options)
   }
 
@@ -808,95 +917,138 @@ export class RelayPool {
     signal,
     _stopSignal,
     live = true,
+    snapshot = false,
     timeout = 5000,
     timeoutAfterFirstEose = 500,
+    queueTimeout = 30000,
+    maxBufferedLiveEvents = 1000,
+    maxBufferedLiveBytes = 8 * 1024 * 1024,
     _liveGenerator = (...args) => this.getLiveEventsGenerator(...args),
     _eventsGenerator = (...args) => this.getEventsGenerator(...args)
   } = {}) {
     if (signal.aborted || _stopSignal.aborted) return
+    const options = { timeout, timeoutAfterFirstEose, queueTimeout, signal, _stopSignal }
     if (!live) {
-      const gen = _eventsGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal, _stopSignal })
-      for await (const item of gen) {
+      const bounds = { since: filter.since ?? 0, until: Math.min(filter.until ?? Infinity, Math.floor(Date.now() / 1000)) }
+      for await (const item of _eventsGenerator(snapshot ? { ...filter, ...bounds } : filter, relays, options)) {
         if (signal.aborted) return
-        yield item
+        yield snapshot && item.type === 'eose' ? { ...item, snapshot: bounds } : item
       }
       return
     }
 
-    // limit:0 means "no stored events, live only" — skip the initial fetch.
+    // limit:0 is a live-only stream and reports that stream's initial window.
     if (filter.limit === 0) {
-      for await (const event of _liveGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal, _stopSignal })) {
-        if (signal.aborted) return
-        yield event
-      }
+      yield * _liveGenerator(filter, relays, options)
       return
     }
 
-    // Start live generator immediately so the relay opens the live sub and starts
-    // buffering incoming events before we query stored ones.
-    // Relays always send stored matching events before EOSE (unless limit:0),
-    // so the initial fetch + buffering is always needed.
-    const liveGen = _liveGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal, _stopSignal })
+    const urls = normalizedRelayUrls(relays)
+    const inputAbort = new AbortController()
+    const inputSignal = AbortSignal.any([signal, inputAbort.signal])
+    const admissionSignal = AbortSignal.any([inputSignal, _stopSignal])
+    const reservations = new Map()
+    const leases = new Set()
+    for (const url of urls) {
+      const reservation = this.#admission.acquire(normalizeRelayUrl(url), { history: true, live: true, signal: admissionSignal, queueTimeout }).then(slots => {
+        for (const lease of Object.values(slots)) {
+          leases.add(lease)
+          if (admissionSignal.aborted) lease.release()
+        }
+        return slots
+      })
+      // Both readers consume the same attempt, including admission failures.
+      reservation.catch(() => {})
+      reservations.set(url, reservation)
+    }
+    const readOptions = { ...options, signal: inputSignal, _admissions: reservations, maxBufferedLiveEvents, maxBufferedLiveBytes }
+    const liveFilter = { ...filter }
+    if (snapshot) delete liveFilter.until
+    const liveGen = _liveGenerator(liveFilter, urls, readOptions)
     const liveBuffer = []
+    const encoder = new TextEncoder()
+    let bufferedBytes = 0
     let liveDone = false
     let liveFailure
     let liveWake = Promise.withResolvers()
-
+    const initialReady = Promise.withResolvers()
+    const shift = () => {
+      const entry = liveBuffer.shift()
+      bufferedBytes -= entry.bytes
+      return entry.item
+    }
     const bgLoop = (async () => {
       try {
-        for await (const event of liveGen) {
-          if (signal.aborted) break
-          if (event.type !== 'eose') liveBuffer.push(event)
+        for await (const item of liveGen) {
+          if (inputSignal.aborted) break
+          if (item.type === 'eose') initialReady.resolve()
+          else {
+            const bytes = encoder.encode(JSON.stringify(item)).byteLength
+            if (liveBuffer.length >= maxBufferedLiveEvents || bufferedBytes + bytes > maxBufferedLiveBytes) {
+              throw Object.assign(new Error('RELAY_LIVE_BUFFER_FULL'), { code: 'RELAY_LIVE_BUFFER_FULL', relay: item.relay, phase: 'live-buffer' })
+            }
+            liveBuffer.push({ item, bytes })
+            bufferedBytes += bytes
+          }
           liveWake.resolve()
           liveWake = Promise.withResolvers()
         }
       } catch (error) {
         liveFailure = error
+        if (error.code === 'RELAY_LIVE_BUFFER_FULL') inputAbort.abort()
       } finally {
         liveDone = true
+        initialReady.resolve()
         liveWake.resolve()
       }
     })()
 
     try {
-      // Yield stored events from the initial one-shot fetch
-      const fetchGen = _eventsGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal, _stopSignal })
-
+      if (snapshot) await initialReady.promise
+      if (liveFailure?.code === 'RELAY_LIVE_BUFFER_FULL') throw liveFailure
+      if (signal.aborted) return
+      const bounds = { since: filter.since ?? 0, until: Math.min(filter.until ?? Infinity, Math.floor(Date.now() / 1000)) }
+      const historyFilter = snapshot ? { ...filter, ...bounds } : filter
+      const fetchGen = _eventsGenerator(historyFilter, urls, readOptions)
       const seenIds = new Set()
       for await (const item of fetchGen) {
+        if (liveFailure?.code === 'RELAY_LIVE_BUFFER_FULL') throw liveFailure
         if (signal.aborted) return
         if (item?.type === 'event' && !seenIds.has(item.event.id)) {
           seenIds.add(item.event.id)
           yield item
-        } else if (item?.type !== 'event') yield item
+        } else if (item?.type !== 'event') {
+          yield snapshot && item.type === 'eose' ? { ...item, snapshot: bounds } : item
+        }
       }
+      if (liveFailure?.code === 'RELAY_LIVE_BUFFER_FULL') throw liveFailure
 
-      // Flush buffered live events that arrived during the initial fetch, deduping
-      // against stored ones (overlap is possible around the fetch's until boundary)
       while (liveBuffer.length > 0) {
         if (signal.aborted) return
-        const item = liveBuffer.shift()
+        const item = shift()
         if (item.type !== 'event' || !seenIds.has(item.event.id)) {
           if (item.type === 'event') seenIds.add(item.event.id)
           yield item
         }
       }
-
       seenIds.clear()
 
-      // Yield subsequent live events directly — no more overlap with stored events
       // eslint-disable-next-line no-unmodified-loop-condition
       while (!liveDone || liveBuffer.length > 0) {
+        if (liveFailure?.code === 'RELAY_LIVE_BUFFER_FULL') throw liveFailure
         while (liveBuffer.length > 0) {
           if (signal.aborted) return
-          yield liveBuffer.shift()
+          yield shift()
         }
         if (!liveDone) await liveWake.promise
       }
       if (liveFailure) throw liveFailure
     } finally {
+      inputAbort.abort()
       await liveGen.return()
       await bgLoop
+      liveBuffer.length = 0
+      for (const lease of leases) lease.release()
     }
   }