libp2r2p 0.10.20 → 0.10.22

package/README.md

@@ -21,6 +21,7 @@ never decorated with `meta`; relay provenance belongs to its enclosing item:
 { type: 'event', event, relay }
 { type: 'error', relay, error }
 { type: 'eose', relays: [{ relay, status, error }] } // error is optional
+{ type: 'live-progress', relay, epoch, since, until } // live and live-enabled feeds only
 ```
 
 `eose` means the **initial read attempt is complete**, including empty reads and
@@ -30,7 +31,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 +72,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 +102,117 @@ 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.
 
+### Live overlap and progress (0.10.22)
+
+Every live subscription opens with `since = max(filter.since ?? 0, now - 600, 0)`,
+including its first connection. This accepts events that arrive after opening
+but carry a timestamp up to ten minutes earlier. Explicit filter boundaries still
+apply, and retained events before EOSE remain excluded from strictly-live output.
+
+Reconnect recovery overlaps each relay's last received timestamp by 600 seconds,
+without going below the caller's `since` or zero. Empty connections use their
+opening time instead. Cursors advance independently even for events deduplicated
+across relays; future timestamps are capped at their local receipt time. Failed
+or interrupted recoveries retain their earlier baseline for the next reconnect.
+
+Live readers automatically enqueue a `live-progress` envelope every 60 seconds
+while ready, including when no events arrive. There is no enabling option.
+`epoch` is a numeric connection-attempt identifier scoped to this iterator;
+compare it together with `relay`, not across separate iterators. `since` is the
+local EOSE time (or the explicit filter lower bound if later), and `until` is the
+local time at the tick, both inclusive Unix seconds. Repeated markers describe
+the same continuous epoch with an increasing `until`.
+
+Progress starts only after that relay's EOSE and successful completion of any
+pending recovery. It pauses on disconnection, does not span connection epochs,
+and stops on cancellation, draining or `until`. History-only and empty-relay
+reads do not emit it. Timers never issue extra network queries.
+
+Markers share the bounded queue with events and follow all earlier received
+items. A feed preserves that ordering behind its initial history and queued live
+events. Consumers must finish persisting preceding events before persisting
+progress, and must not treat a marker as proof of historical completeness or as
+coverage of a disconnected interval. This is client-observed continuity, not a
+relay acknowledgement; delayed relay delivery or clock skew beyond the overlap
+can still leave gaps. A backward local clock cannot regress an emitted boundary.
+
+Every involuntary live close emits an error and still permits automatic recovery.
+A close without an explicit cause uses `error.code === 'RELAY_LIVE_INTERRUPTED'`
+and `category === 'transport'`; a pre-EOSE close retains status `closed` in the
+initial report. Explicit causes are preserved. Caller cancellation, draining and
+expiry of `filter.until` do not manufacture interruption errors.
+
+Process Nostr events only under `item.type === 'event'`. Handle controls you need
+and ignore unknown types; a new control is neither an event nor stream completion.
+The internal query, private-channel and NIP-46 consumers retain their existing
+higher-level event-only contracts.
+
+### 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.22",
   "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'
@@ -12,6 +13,8 @@ const COUNT_TIMEOUT_MS = 5000
 const COUNT_TIMEOUT_AFTER_FIRST_COUNT_MS = 500
 const SEND_TIMEOUT_UNTIL_FIRST_FULFILLMENT_MS = 3000
 const SEND_TIMEOUT_MS = 30000
+const LIVE_OVERLAP_SECONDS = 600
+const LIVE_PROGRESS_INTERVAL_MS = 60000
 
 // Returns a function that should be called for each received event (valid or invalid).
 // Calls onSatisfied() and stops counting once the filter is fully satisfied per relay:
@@ -91,6 +94,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 +136,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 +205,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 +217,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 +367,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 +379,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 +407,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 +438,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 +503,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 +544,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 +571,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 +584,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
 
@@ -559,23 +609,64 @@ export class RelayPool {
     // Preserve until for forwarding to the live sub filter and the teardown timer
     const filterUntil = filter.until > 0 ? filter.until : null
 
-    // lastSeenAt: the highest created_at received so far; used as since on reconnect gap fill
-    let lastSeenAt = (filter.since > 0) ? filter.since : null
+    // Recovery uses each relay's received timestamps, or its opening time when empty.
+    const lastSeenAt = new Map()
+    const openedAt = new Map()
+    const pendingGaps = new Map()
+    const attempts = new Map()
+    let nextEpoch = 0
+    const sinceFloor = Math.max(0, filter.since ?? 0)
+    const overlappingSince = timestamp => Math.max(sinceFloor, timestamp - LIVE_OVERLAP_SECONDS)
+    const observeEvent = (event, url) => {
+      // Every relay advances independently, including cross-relay duplicates.
+      // Future-dated events cannot hide an offline interval during recovery.
+      const timestamp = Math.min(event.created_at, Math.floor(Date.now() / 1000))
+      if (Number.isFinite(timestamp) && timestamp > (lastSeenAt.get(url) ?? -Infinity)) lastSeenAt.set(url, timestamp)
+    }
+    const scheduleProgress = attempt => {
+      if (isDone || attempt.closed || attempts.get(attempt.url) !== attempt ||
+          attempt.since === null || !attempt.recovered || attempt.timer) return
+      attempt.timer = maybeUnref(setTimeout(() => {
+        attempt.timer = null
+        if (isDone || attempt.closed || attempts.get(attempt.url) !== attempt) return
+        const until = Math.min(filterUntil ?? Infinity, Math.floor(Date.now() / 1000))
+        if (until > attempt.lastProgress && until >= attempt.since) {
+          enqueue({ type: 'live-progress', relay: attempt.url, epoch: attempt.epoch, since: attempt.since, until })
+          attempt.lastProgress = until
+        }
+        scheduleProgress(attempt)
+      }, LIVE_PROGRESS_INTERVAL_MS))
+    }
 
     // Bounded dedup set to handle overlap between reconnect gap fill and live sub.
     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,14 +685,20 @@ 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()
+      for (const attempt of attempts.values()) {
+        clearTimeout(attempt.timer)
+        attempt.stop.abort()
+      }
       for (const timer of retryTimers.values()) clearTimeout(timer)
       retryTimers.clear()
       liveSubs.forEach(sub => sub.close())
       liveSubs.clear()
+      for (const lease of liveLeases.values()) lease.release()
+      liveLeases.clear()
       p.resolve()
     }
 
@@ -612,7 +709,6 @@ export class RelayPool {
         if (seenIds.size >= 500) seenIds.delete(seenIds.values().next().value) // evict oldest
         seenIds.add(event.id)
       }
-      if (event.created_at > (lastSeenAt ?? 0)) lastSeenAt = event.created_at
       enqueue({ type: 'event', event, relay: url })
     }
 
@@ -625,13 +721,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,13 +740,15 @@ 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 => {
+    const reportClosed = (url, error) => {
       if (!isReady && initialPending.delete(url)) {
-        initialOutcomes.set(url, { relay: url, status: 'closed' })
+        clearTimeout(readyTimeouts.get(url))
+        initialOutcomes.set(url, { relay: url, status: 'closed', error })
         maybeFinishInitialReady()
       }
     }
@@ -661,7 +758,7 @@ export class RelayPool {
       const nextDelay = Math.min(reconnectDelay * 2, 5 * 60_000)
       const timer = maybeUnref(setTimeout(() => {
         retryTimers.delete(url)
-        subscribeToRelay(url, lastSeenAt, nextDelay)
+        subscribeToRelay(url, pendingGaps.get(url) ?? lastSeenAt.get(url) ?? openedAt.get(url) ?? null, nextDelay)
       }, reconnectDelay))
       retryTimers.set(url, timer)
     }
@@ -674,81 +771,143 @@ 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, attempt) => {
       const gapUntil = filterUntil !== null ? Math.min(now, filterUntil) : now
-      const gapFilter = { ...baseFilter, since: gapSince, until: gapUntil }
+      const gapFilter = { ...baseFilter, since: overlappingSince(gapSince), until: gapUntil }
       const gapGen = _gapEventsGenerator(gapFilter, [url], {
+        _admissions: new Map([[url, Promise.resolve(slots)]]),
+        queueTimeout,
         timeout: timeoutForReconnectGap,
         timeoutAfterFirstEose: timeoutAfterFirstReconnectGapEose,
         signal,
-        _stopSignal: gapAc.signal
+        _stopSignal: AbortSignal.any([gapAc.signal, attempt.stop.signal])
       })
       return (async () => {
+        let completed = false
+        let failed = false
         for await (const item of gapGen) {
-          if (item?.type === 'event') pushEvent(item.event, url, true)
-          else if (item?.type === 'error' && !isDone) enqueue(item)
+          if (item?.type === 'event') {
+            observeEvent(item.event, url)
+            pushEvent(item.event, url, true)
+          } else if (item?.type === 'error') {
+            failed = true
+            if (!isDone) enqueue(item)
+          } else if (item?.type === 'eose') {
+            completed = item.relays?.length === 1 && ['eose', 'satisfied'].includes(item.relays[0].status)
+          }
         }
+        return completed && !failed
       })().catch(err => {
         reportFailure(url, asError(err))
-      })
+        return false
+      }).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
+      if (recovering) pendingGaps.set(url, gapSince)
+      const attempt = { url, epoch: ++nextEpoch, since: null, lastProgress: -Infinity, recovered: !recovering, timer: null, closed: false, stop: new AbortController() }
+      attempts.set(url, attempt)
+      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 liveBuffer = recovering ? [] : 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.
         // Forward until to the relay so it can enforce the boundary server-side.
-        const liveFilter = { ...baseFilter, since: now, limit: 0 }
+        if (!openedAt.has(url)) openedAt.set(url, now)
+        const liveFilter = { ...baseFilter, since: overlappingSince(now), limit: 0 }
         if (filterUntil !== null) liveFilter.until = filterUntil
         const liveSub = relay.subscribe([liveFilter], {
           onevent: (event) => {
             // 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 (isDone || liveSubs.get(url) !== liveSub || attempt.closed || !liveEose) return
+            observeEvent(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 (attempt.closed || attempts.get(url) !== attempt) return
+            attempt.closed = true
+            clearTimeout(attempt.timer)
+            attempt.stop.abort()
             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))
-              else if (!liveEose) reportClosed(url)
-            }
             if (isDone) return
+            if (error !== undefined) reportFailure(url, asError(error))
+            else {
+              const interruption = Object.assign(categorizeRelayError(new Error('RELAY_LIVE_INTERRUPTED'), 'transport'), { code: 'RELAY_LIVE_INTERRUPTED' })
+              enqueue({ type: 'error', relay: url, error: interruption })
+              reportClosed(url, interruption)
+            }
             scheduleReconnect(url, reconnectDelay)
           },
           oneose: () => {
-            if (isDone || (liveSubs.has(url) && liveSubs.get(url) !== liveSub)) return
+            if (isDone || attempt.closed || attempts.get(url) !== attempt || liveEose) return
             liveEose = true
+            attempt.since = Math.max(sinceFloor, Math.floor(Date.now() / 1000))
             markInitialEose(url)
+            scheduleProgress(attempt)
           }
         })
-        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(() => {
+        if (recovering) {
+          const task = runReconnectGapFill(url, gapSince, now, slots, attempt).then(recovered => {
+            attempt.recovered = recovered
+            if (recovered && !attempt.closed && attempts.get(url) === attempt) pendingGaps.delete(url)
+          }).finally(() => {
             const buf = liveBuffer
             liveBuffer = null
             for (const event of buf) pushEvent(event, url, true)
             gapTasks.delete(task)
+            scheduleProgress(attempt)
             p.resolve()
           })
           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 +918,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 +938,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 +952,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 +961,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 +975,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, maxBufferedLiveEvents, maxBufferedLiveBytes })
       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()
     }
   }