libp2r2p 0.10.20 → 0.10.21

package/README.md

@@ -30,7 +30,7 @@ partial results. Its report distinguishes actual relay EOSE from other outcomes:
 | --- | --- |
 | `eose` | The relay sent EOSE. |
 | `satisfied` | The requested limit or IDs were satisfied, so the read closed early. |
-| `timeout` | The initial operation deadline elapsed. Also emits an error item. |
+| `timeout` | The initial relay attempt deadline elapsed. Also emits an error item. |
 | `cutoff` | The grace period after the first qualifying EOSE/early completion elapsed. |
 | `closed` | The subscription ended without EOSE or an explicit error. |
 | `error` | Connection or subscription failed. Also emits an error item. |
@@ -71,7 +71,7 @@ tracks currently ready relays and can change after that snapshot. Timeouts and
 cutoffs are not acknowledgements of readiness. Reconnections do not repeat the
 initial marker. Both APIs require consuming the iterator to start its work.
 
-Live and feed iterators have a synchronous, idempotent `stopAndDrain()` method.
+Read iterators have a synchronous, idempotent `stopAndDrain()` method.
 It closes subscription input and cancels reconnections and outstanding historical
 queries, while retaining items already accepted by receive callbacks. Continue
 consuming to obtain those items and completion. This includes initial history,
@@ -101,6 +101,72 @@ content-key, private-channel and NIP-46 helpers unwrap pool results internally
 and retain their higher-level event contracts. Count, publication and disconnect
 return formats are unchanged.
 
+### Read admission and bounded snapshots (0.10.21)
+
+Each pool coordinates event reads by normalized connection URL. Constructor
+options are `maxSubscriptionsPerRelay: 28`,
+`maxConcurrentHistoryPerRelay: 2`, and `maxQueuedReadsPerRelay: 256`.
+These are local budgets, not negotiated relay limits. A stricter relay can still
+reject subscriptions. Count and publication contracts are unchanged and do not
+consume event-read slots.
+
+Admission is FIFO per connection. A history+live feed reserves two slots
+atomically before either REQ opens; completing history releases only its slot.
+One-shot queries and reconnect gap reads share this budget. Reconnection reserves
+live+history together when recovery is needed. Caller cancellation removes queued
+work; `disconnect(url)` also rejects queued work for that connection. Existing
+live streams retain their reconnect behavior until cancelled by their owner.
+
+All event reads accept `queueTimeout: 30000` (milliseconds, `null` disables).
+The network `timeout` starts **after admission for each relay**, including its
+connection setup; time in the queue does not consume it. The first-EOSE grace
+can still cut short other relay attempts. Admission failures are ordinary error
+envelopes/report entries, with `error.code`, `error.relay` and
+`error.phase === 'admission'`: `RELAY_READ_QUEUE_FULL`,
+`RELAY_READ_QUEUE_TIMEOUT`, `RELAY_READ_CAPACITY`, or `RELAY_DISCONNECTED`.
+Cancellation rejects an outstanding direct `getEvents()` call; cancelled iterators
+stop delivering. Failures on one relay continue to allow results from others.
+
+Live and feed readers limit each pending live buffer to 1,000 envelopes and
+8 MiB of serialized UTF-8 data. Options `maxBufferedLiveEvents` and
+`maxBufferedLiveBytes` customize those positive limits. They cover consumer
+backlog and reconnect buffers as well as live events waiting for history. These
+are bounds on queued data, not a measurement of total JavaScript heap usage.
+Overflow fails the attempt with `RELAY_LIVE_BUFFER_FULL` (`phase: 'live-buffer'`),
+closes input and discards pending live data. Callers decide whether to retry;
+events already delivered are not recalled. Ordinary relay failures retain the
+existing partial-result behavior; they do not automatically discard the feed.
+
+With `snapshot: true`, a feed waits for its initial live readiness window before
+capturing the historical `until`. `filter.since` defaults to zero; `filter.until`
+can provide an earlier cutoff but cannot extend a snapshot into the future.
+The historical completion includes the actual inclusive bounds:
+
+```js
+const stream = relayPool.getEventsFeedGenerator(
+  { authors: [pubkey], kinds: [1], since: lastConfirmed - 600, limit: 200 },
+  [relay],
+  { snapshot: true, timeoutAfterFirstEose: null, signal }
+)
+// Historical completion:
+// { type: 'eose', relays: [...], snapshot: { since, until } }
+```
+
+Only history is bounded: the live REQ has no `until` in this mode. Events around
+the boundary can appear in both sources and are deduplicated by ID. Empty history
+still reports its bounds. With `live: false`, the cutoff is captured when the
+iterator starts; `limit: 0` remains live-only, without a historical snapshot.
+Default `snapshot: false` retains the existing filter time-range behavior.
+
+This is a bounded time interval, not a transactional relay snapshot or proof of
+complete coverage. Check each relay's outcome, exhaust pagination and commit
+received events before checkpointing. `satisfied` can mean a truncated page;
+EOSE can also terminate a limited response. A consumer that rejects a historical
+attempt can call `return()`/abort when it receives its report, before the buffered
+live events are released. Use `stopAndDrain()` only when those pending events
+should be preserved. Slow/failed live readiness is still reported by the live
+stream according to the existing partial-failure rules.
+
 ## Private Messenger
 
 The main API is `createPrivateMessenger` from `libp2r2p/private-messenger`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.10.20",
+  "version": "0.10.21",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",

package/relay/helpers/read-admission.js

@@ -0,0 +1,92 @@
+import { ValidationError } from '../../error/index.js'
+import { maybeUnref } from './timer.js'
+
+export function admissionError (code, relay) {
+  return Object.assign(new Error(code), { code, relay, phase: 'admission' })
+}
+
+// One FIFO per pooled connection. A feed reserves both REQs atomically; its
+// history and live leases can subsequently be released independently.
+export class ReadAdmission {
+  constructor ({ maxSubscriptionsPerRelay = 28, maxConcurrentHistoryPerRelay = 2, maxQueuedReadsPerRelay = 256 } = {}) {
+    for (const value of [maxSubscriptionsPerRelay, maxConcurrentHistoryPerRelay, maxQueuedReadsPerRelay]) {
+      if (!Number.isSafeInteger(value) || value < 1) throw new ValidationError('INVALID_RELAY_READ_CAPACITY')
+    }
+    Object.assign(this, { maxSubscriptionsPerRelay, maxConcurrentHistoryPerRelay, maxQueuedReadsPerRelay })
+    this.states = new Map()
+  }
+
+  acquire (relay, { history = false, live = false, signal, queueTimeout = 30000 } = {}) {
+    if (queueTimeout !== null && (!Number.isFinite(queueTimeout) || queueTimeout < 0)) throw new ValidationError('INVALID_RELAY_TIMEOUT')
+    const weight = Number(history) + Number(live)
+    if (!weight || weight > this.maxSubscriptionsPerRelay) return Promise.reject(admissionError('RELAY_READ_CAPACITY', relay))
+    if (signal?.aborted) return Promise.reject(admissionError('RELAY_READ_CANCELLED', relay))
+    let state = this.states.get(relay)
+    if (!state) {
+      state = { active: 0, history: 0, queue: [] }
+      this.states.set(relay, state)
+    }
+    const deferred = Promise.withResolvers()
+    let timer
+    const job = {
+      history, weight, grant: () => {
+        cleanup()
+        state.active += weight
+        state.history += Number(history)
+        const leases = {}
+        for (const kind of ['history', 'live']) {
+          if (!(kind === 'history' ? history : live)) continue
+          let released = false
+          leases[kind] = {
+            release: () => {
+              if (released) return
+              released = true
+              state.active--
+              if (kind === 'history') state.history--
+              this.drain(relay, state)
+            }
+          }
+        }
+        deferred.resolve(leases)
+      }, cancel: code => {
+        const index = state.queue.indexOf(job)
+        if (index < 0) return
+        state.queue.splice(index, 1)
+        cleanup()
+        deferred.reject(admissionError(code, relay))
+        this.drain(relay, state)
+      }
+    }
+    const abort = () => job.cancel('RELAY_READ_CANCELLED')
+    const cleanup = () => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', abort)
+    }
+    if (state.queue.length >= this.maxQueuedReadsPerRelay) return Promise.reject(admissionError('RELAY_READ_QUEUE_FULL', relay))
+    state.queue.push(job)
+    signal?.addEventListener('abort', abort, { once: true })
+    if (queueTimeout !== null) timer = maybeUnref(setTimeout(() => job.cancel('RELAY_READ_QUEUE_TIMEOUT'), queueTimeout))
+    this.drain(relay, state)
+    return deferred.promise
+  }
+
+  drain (relay, state) {
+    while (state.queue.length) {
+      const job = state.queue[0]
+      if (state.active + job.weight > this.maxSubscriptionsPerRelay || (job.history && state.history >= this.maxConcurrentHistoryPerRelay)) break
+      state.queue.shift().grant()
+    }
+    if (!state.active && !state.queue.length && this.states.get(relay) === state) this.states.delete(relay)
+  }
+
+  cancelQueued (relay) {
+    const state = this.states.get(relay)
+    if (!state) return
+    // Remove the entire queue first: cancelling one entry must not admit another.
+    const jobs = state.queue.splice(0)
+    for (const job of jobs) {
+      state.queue.push(job)
+      job.cancel('RELAY_DISCONNECTED')
+    }
+  }
+}

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()
     }
   }