libp2r2p 0.11.7 → 0.11.8

package/README.md

@@ -985,3 +985,39 @@ publication failures retain the payload/index for retry. Outbound channel
 fragmentation streams from prepared encrypted rows, cleans partial writes and
 removes failed new keys from the temporary-storage registry. It does not raise
 the browser's Web Storage quota or delete unrelated application data.
+
+
+### Private subscription recovery (0.11.8)
+
+`privateChannel.subscribe()` returns `{ ready, done, close }`. `done` always
+resolves to `{ status: 'closed' | 'ended' | 'failed', error? }` after processing
+stops. Explicit cancellation is `closed`; a naturally exhausted stream is
+`ended`; a terminal error is `failed` and still reaches `onError`.
+
+`private-message.watch()` accepts an optional asynchronous
+`onSubscriptionState({ state, relay, since, until?, error? })` callback.
+`interrupted` identifies the conservative lower recovery boundary; after a
+buffer overflow, every affected channel must finish this callback before its
+shared relay subscription reopens. `ready` follows successful initial relay
+readiness on the replacement. Callbacks and completions are generation-fenced.
+Equal watch settings cannot keep a dead subscription registered as active.
+
+Overflow recovery keeps one timer per relay with exponential 1–30 second
+backoff and 20% jitter, reset after a stable minute. Other relays remain live.
+Removal, pause and close cancel pending work. Fragment storage stays scoped to
+the same session across replacement subscriptions. Permanent refusals remain
+reported and do not trigger this automatic retry loop.
+
+PrivateMessenger persists each interrupted interval before reopening, then
+uses paged `fetchHistory` to repair the gap while listening for new messages.
+Transient history failures retry with bounded backoff and honor `retryAt`;
+dense-page limits, permanent refusals and unknown failures stay pending without
+an automatic loop. Disabled historical recovery restores only live input.
+Existing persisted ranges, checkpoints, recovery windows and ack/nack semantics
+are unchanged; newer live arrivals cannot erase a pending interval.
+
+`RELAY_LIVE_BUFFER_FULL` retains `relay`, `phase`, `recoverySince` and a bounded
+`buffer` diagnostic: stage (`delivery`, `reconnect`, `history-wait`), queued
+count/bytes, incoming bytes, limits and oldest queued age. Queue bytes are UTF-8
+serialized volume, not heap use. Diagnostics never retain event contents or
+filters. Existing 1,000-item / 8-MiB live limits are unchanged.

package/package.json

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

package/private-channel/helpers/subscription-error.js

@@ -5,7 +5,7 @@ export function subscriptionError (reason, relay) {
   const error = reason instanceof AggregateError
     ? new AggregateError(reason.errors, message, { cause: reason })
     : new Error(message, { cause: reason })
-  for (const key of ['name', 'code', 'category', 'retryAfterMs', 'retryAt', 'closeCode', 'closeReason', 'wasClean']) {
+  for (const key of ['name', 'code', 'category', 'retryAfterMs', 'retryAt', 'closeCode', 'closeReason', 'wasClean', 'phase', 'buffer', 'recoverySince']) {
     if (reason?.[key] !== undefined) error[key] = reason[key]
   }
   error.operation = 'private-channel.subscribe'

package/private-channel/index.js

@@ -984,6 +984,7 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
     })
 
   async function consumeEvents () {
+    let result = { status: 'ended' }
     try {
       for await (const item of events) {
         if (controller.signal.aborted) continue
@@ -991,19 +992,26 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
         else if (item.type === 'event') await processOuterEvent(item.event)
       }
     } catch (error) {
-      if (!controller.signal.aborted && error?.message !== 'Aborted') onError?.(error)
+      if (!controller.signal.aborted) {
+        const diagnostic = subscriptionError(error, error?.relay)
+        result = { status: 'failed', error: diagnostic }
+        // Consumer error callbacks must not turn `done` into an unhandled rejection.
+        try { onError?.(diagnostic) } catch {}
+      }
     } finally {
       processOuterEvent.close()
     }
+    return controller.signal.aborted ? { status: 'closed' } : result
   }
 
-  const consumePromise = consumeEvents()
+  const done = consumeEvents()
 
   return {
     ready: events.ready || Promise.resolve(),
+    done,
     close () {
       controller.abort()
-      return consumePromise
+      return done
     }
   }
 }

package/private-message/index.js

@@ -1,3 +1,4 @@
+import { normalizeRelayUrl } from '../url/index.js'
 import { isValidEvent } from '../event/index.js'
 import { ValidationError } from '../error/index.js'
 import { generateKeypair } from '../key/index.js'
@@ -144,9 +145,10 @@ async function ownPrivateChannelPubkey (signer) {
 
 // A session owns its callbacks and relay reads. Other consumers, including
 // the other side of the same shared channel, cannot overwrite or stop them.
-export function createPrivateMessageSession () {
+export function createPrivateMessageSession ({ _setTimeout = setTimeout, _clearTimeout = clearTimeout, _now = Date.now, _random = Math.random } = {}) {
   const watchesByChannel = new Map()
   const subsByRelay = new Map()
+  const relayRecoveries = new Map()
   let nextWatchRevision = 1
   let requestSequence = 0
   const watchRequests = new Map()
@@ -301,11 +303,113 @@ export function createPrivateMessageSession () {
     }
   }
 
-  function rebuildSubscriptions ({ _subscribe = privateChannel.subscribe, gracefulClose = true } = {}) {
+  function reportSubscriptionError (channels, error) {
+    try { watchCallbacks([...channels][0]).onError?.(error) } catch {}
+  }
+
+  function cancelRelayRecovery (relay) {
+    const recovery = relayRecoveries.get(relay)
+    if (recovery?.timer != null) _clearTimeout(recovery.timer)
+    relayRecoveries.delete(relay)
+  }
+
+  async function notifyInterruption (relay, recovery) {
+    const channels = desiredRelayState().get(relay) || []
+    // Each consumer must persist its gap before this shared subscription restarts.
+    // Keep acknowledgments on partial failure; new/replaced watches participate too.
+    const outcomes = await Promise.allSettled([...channels].map(async channel => {
+      const watch = watchesByChannel.get(channel)
+      if (recovery.notified.get(channel) === watch) return
+      await watch.callbacks.onSubscriptionState?.({ state: 'interrupted', relay, error: recovery.error, since: recovery.since })
+      recovery.notified.set(channel, watch)
+    }))
+    const failed = outcomes.find(result => result.status === 'rejected')
+    if (failed) throw failed.reason
+    if (relayRecoveries.get(relay) === recovery && [...(desiredRelayState().get(relay) || [])].some(channel => recovery.notified.get(channel) !== watchesByChannel.get(channel))) {
+      await notifyInterruption(relay, recovery)
+    }
+  }
+
+  function scheduleRelayRecovery (relay, recovery) {
+    if (relayRecoveries.get(relay) !== recovery || recovery.timer || !desiredRelayState().has(relay)) return
+    const delay = Math.min(30000, recovery.delay * (0.8 + _random() * 0.4))
+    recovery.delay = Math.min(30000, recovery.delay * 2)
+    recovery.timer = _setTimeout(async () => {
+      recovery.timer = null
+      try {
+        await notifyInterruption(relay, recovery)
+        if (relayRecoveries.get(relay) !== recovery || !desiredRelayState().has(relay)) return
+        await rebuildSubscriptions({ retryRelay: relay })
+      } catch (error) {
+        reportSubscriptionError(desiredRelayState().get(relay) || [], error)
+        scheduleRelayRecovery(relay, recovery)
+      }
+    }, delay)
+    recovery.timer?.unref?.()
+  }
+
+  function subscriptionEnded (relay, entry, result) {
+    if (subsByRelay.get(relay) !== entry) return
+    subsByRelay.delete(relay)
+    if (result.status === 'closed' || !desiredRelayState().has(relay)) return
+    const error = result.error || Object.assign(new Error('PRIVATE_CHANNEL_SUBSCRIPTION_ENDED'), { code: 'PRIVATE_CHANNEL_SUBSCRIPTION_ENDED', relay })
+    const previous = relayRecoveries.get(relay)
+    const recovery = {
+      error,
+      since: Math.min(entry.since, error.recoverySince ?? entry.since, previous?.since ?? Infinity),
+      delay: entry.readyAt !== undefined && _now() - entry.readyAt >= 60000 ? 1000 : (previous?.delay || entry.retryDelay || 1000),
+      notified: new Map(), timer: null
+    }
+    if (/^(auth-required:|restricted:|blocked:|invalid:|pow:)/.test(error.message || '') || error.name === 'ValidationError' ||
+        (error.code !== 'RELAY_LIVE_BUFFER_FULL' && !previous)) {
+      cancelRelayRecovery(relay)
+      notifyInterruption(relay, recovery).catch(error => reportSubscriptionError(entry.channels, error))
+      return
+    }
+    cancelRelayRecovery(relay)
+    relayRecoveries.set(relay, recovery)
+    // Start persistence immediately, without overlapping a later retry callback.
+    recovery.preparing = notifyInterruption(relay, recovery).catch(error => reportSubscriptionError(entry.channels, error))
+    recovery.preparing.finally(() => scheduleRelayRecovery(relay, recovery))
+  }
+
+  async function subscriptionReady (relay, entry, ready) {
+    if (subsByRelay.get(relay) !== entry) return
+    const recovery = relayRecoveries.get(relay)
+    if (!ready?.relays?.includes(relay)) {
+      if (recovery) {
+        const error = ready?.errors?.[0]?.reason || Object.assign(new Error('RELAY_LIVE_NOT_READY'), { code: 'RELAY_LIVE_NOT_READY', relay })
+        subscriptionEnded(relay, entry, { status: 'failed', error })
+        await entry.sub.close()
+      }
+      return
+    }
+    entry.readyAt = _now()
+    if (!recovery) return
+    try {
+      const until = Math.floor(_now() / 1000)
+      await Promise.all([...entry.channels].map(async channel => {
+        if (subsByRelay.get(relay) !== entry || !watchesByChannel.has(channel)) return
+        await watchCallbacks(channel).onSubscriptionState?.({ state: 'ready', relay, since: recovery.since, until })
+      }))
+      if (subsByRelay.get(relay) === entry && relayRecoveries.get(relay) === recovery) {
+        entry.retryDelay = recovery.delay
+        cancelRelayRecovery(relay)
+        await rebuildSubscriptions()
+      }
+    } catch (error) {
+      reportSubscriptionError(entry.channels, error)
+      subscriptionEnded(relay, entry, { status: 'failed', error })
+      await entry.sub.close()
+    }
+  }
+
+  function rebuildSubscriptions ({ _subscribe = privateChannel.subscribe, gracefulClose = true, retryRelay } = {}) {
     subscribe = _subscribe === privateChannel.subscribe ? subscribe : _subscribe
     _subscribe = subscribe
     const desired = desiredRelayState()
     const closing = []
+    for (const relay of relayRecoveries.keys()) if (!desired.has(relay)) cancelRelayRecovery(relay)
 
     for (const [relay, current] of subsByRelay) {
       const nextChannels = desired.get(relay)
@@ -321,6 +425,8 @@ export function createPrivateMessageSession () {
       const current = subsByRelay.get(relay)
       if (doesSubscriptionMatch(current, channels)) continue
 
+      if (relayRecoveries.has(relay) && retryRelay !== relay) continue
+      const since = nowSeconds()
       const channelList = [...channels]
       const firstWatch = watchesByChannel.get(channelList[0])
       const sub = _subscribe({
@@ -345,7 +451,7 @@ export function createPrivateMessageSession () {
         ignoredGroupTtlMs: maxWatchNumber(channelList, 'ignoredGroupTtlMs'),
         ignoredGroupMaxEntries: maxWatchNumber(channelList, 'ignoredGroupMaxEntries'),
         limit: 0,
-        since: nowSeconds(),
+        since,
         liveOnly: true,
         onChunk: handleChunk,
         onEvent: (event, outer, meta) => {
@@ -358,14 +464,24 @@ export function createPrivateMessageSession () {
           return dispatchSeedEvent(seed)
         },
         onContentKeyUsage: dispatchContentKeyUsage,
-        onError: err => firstWatch.callbacks.onError?.(err)
+        onError: err => reportSubscriptionError(channels, err)
       })
 
-      subsByRelay.set(relay, {
+      const entry = {
+        since,
         channels: new Set(channels),
         revisions: watchRevisionsForChannels(channelList),
         sub
-      })
+      }
+      subsByRelay.set(relay, entry)
+      if (sub.done) sub.done.then(result => subscriptionEnded(relay, entry, result)).catch(error => reportSubscriptionError(channels, error))
+      if (sub.ready) {
+        sub.ready.then(ready => subscriptionReady(relay, entry, ready)).catch(error => {
+          reportSubscriptionError(channels, error)
+          subscriptionEnded(relay, entry, { status: 'failed', error })
+          Promise.resolve(sub.close()).catch(() => {})
+        })
+      }
       if (current) {
         const close = closeSubscription(current.sub, gracefulClose)
         if (close) closing.push(close)
@@ -393,6 +509,7 @@ export function createPrivateMessageSession () {
     onSeed,
     onChunk,
     onContentKeyUsage,
+    onSubscriptionState,
     onError,
     receivedChunkTtlMs,
     receivedChunkMaxBytes,
@@ -403,6 +520,7 @@ export function createPrivateMessageSession () {
     _subscribe = privateChannel.subscribe
   }) {
     if (!relays?.length) throw new ValidationError('NO_RELAYS')
+    relays = uniq(relays.map(normalizeRelayUrl))
     const request = ++requestSequence
     const channelList = uniq(channels?.length ? channels : [await ownPrivateChannelPubkey(privateChannelSigner)])
     for (const channel of channelList) {
@@ -411,9 +529,8 @@ export function createPrivateMessageSession () {
     const ownPubkey = receiverPubkey || await receiverSigner?.getPublicKey?.()
     if (identity !== undefined && identity !== ownPubkey) throw new ValidationError('PRIVATE_MESSAGE_IDENTITY_MISMATCH')
     identity = ownPubkey
-    const callbacks = { onAsk, onReply, onTell, onYell, onNym, onMessage, onSeed, onChunk, onContentKeyUsage, onError }
+    const callbacks = { onAsk, onReply, onTell, onYell, onNym, onMessage, onSeed, onChunk, onContentKeyUsage, onSubscriptionState, onError }
 
-    let changed = false
     for (const channel of channelList) {
       if (watchRequests.get(channel) !== request) continue
       const next = {
@@ -457,10 +574,9 @@ export function createPrivateMessageSession () {
         continue
       }
       watchesByChannel.set(channel, next)
-      changed = true
     }
 
-    if (changed) await rebuildSubscriptions({ _subscribe })
+    await rebuildSubscriptions({ _subscribe })
     return () => {
       const owned = channelList.filter(channel => watchRequests.get(channel) === request)
       return unwatch(owned)

package/private-messenger/helpers/recovery-retry.js

@@ -0,0 +1,26 @@
+// Retry operational interruptions, never dense-page limits or permanent refusals.
+export function recoveryRetryDelay (errors, delay) {
+  let retry = false
+  let blocked = false
+  let retryAt = 0
+  const seen = new Set()
+  function visit (error) {
+    if (!error || seen.has(error)) return
+    seen.add(error)
+    if (error.code === 'PRIVATE_CHANNEL_HISTORY_PAGE_LIMIT' || error.name === 'ValidationError' ||
+        /^(auth-required:|restricted:|blocked:|invalid:|pow:)/.test(error.message || '')) blocked = true
+    if (['transport', 'timeout'].includes(error.category) ||
+        ['QuotaExceededError', 'InvalidStateError', 'UnknownError'].includes(error.name) ||
+        /^(rate-limited:|error:)/.test(error.message || '') ||
+        ['RELAY_LIVE_BUFFER_FULL', 'RELAY_LIVE_NOT_READY'].includes(error.code)) retry = true
+    if (Number.isFinite(error.retryAt)) retryAt = Math.max(retryAt, Math.min(Date.now() + 300000, error.retryAt))
+    for (const child of error.errors || []) visit(child)
+    for (const entry of error.relays || []) {
+      if (['timeout', 'cutoff', 'closed'].includes(entry.status)) retry = true
+      visit(entry.error)
+    }
+    visit(error.cause)
+  }
+  errors.forEach(visit)
+  return retry && !blocked ? Math.max(delay, retryAt - Date.now()) : null
+}

package/private-messenger/index.js

@@ -1,3 +1,4 @@
+import { recoveryRetryDelay } from './helpers/recovery-retry.js'
 // Expected use:
 // const messenger = await createPrivateMessenger({
 //   userSigner,
@@ -293,6 +294,8 @@ export class PrivateMessenger {
     this.capacityCheck = null
     this.capacityRequiredBytes = 0
     this.reloadGapTimers = new Map()
+    this.liveInterruptions = new Map()
+    this.liveRecoveryTimers = new Map()
     this.watchRevisionByChannel = new Map()
     this.presenceTimers = new Map()
     this.stopRelayListWatcher = null
@@ -1103,6 +1106,7 @@ export class PrivateMessenger {
         onContentKeyUsage: usage => this.handleContentKeyUsage(pubkey, usage),
         receivedChunkTtlMs: this.receivedChunkTtlMsFor(channel),
         receivedChunkIndexedDB: this._indexedDB,
+        onSubscriptionState: state => this.handleSubscriptionState(pubkey, state),
         onError: err => this.onError?.(err)
       })
       if (this.closePromise || this.pauseReasons.size || !this.desiredChannels.has(pubkey) || revision !== (this.watchRevisionByChannel.get(pubkey) || 0)) {
@@ -1136,6 +1140,76 @@ export class PrivateMessenger {
     return this
   }
 
+  async handleSubscriptionState (pubkey, { state, relay, since, until }) {
+    if (this.closePromise || this.pauseReasons.size || !this.desiredChannels.has(pubkey)) return
+    if (!this.offlineRecoverySecondsFor(pubkey)) return
+    let interrupted = this.liveInterruptions.get(pubkey)
+    if (state === 'interrupted') {
+      if (!interrupted) { interrupted = new Map(); this.liveInterruptions.set(pubkey, interrupted) }
+      const start = Math.min(interrupted.get(relay) ?? Infinity, since)
+      interrupted.set(relay, start)
+      this.cancelReloadGap(pubkey)
+      for (const controller of this.recoveryControllers) {
+        if (controller.channelPubkey === pubkey) { controller.liveInterrupted = true; controller.abort() }
+      }
+      this.recordInterruption([pubkey], start)
+      this.addOfflineRange(pubkey, Math.max(0, start - this.offlineSkewSeconds), nowSeconds())
+      // This rejection prevents the session from reopening the shared relay.
+      await this.flushStateWrites()
+    } else if (state === 'ready' && interrupted?.has(relay)) {
+      const start = interrupted.get(relay)
+      this.addOfflineRange(pubkey, Math.max(0, start - this.offlineSkewSeconds), until)
+      if (interrupted.size === 1) this.closeOpenOfflineRanges([pubkey])
+      await this.flushStateWrites()
+      if (this.closePromise || this.pauseReasons.size || !this.desiredChannels.has(pubkey) || this.liveInterruptions.get(pubkey) !== interrupted) return
+      interrupted.delete(relay)
+      if (!interrupted.size) this.liveInterruptions.delete(pubkey)
+      this.scheduleLiveRecovery(pubkey)
+    }
+  }
+
+  cancelLiveRecovery (pubkey) {
+    const work = this.liveRecoveryTimers.get(pubkey)
+    if (work?.timer != null) this._clearTimeout(work.timer)
+    this.liveRecoveryTimers.delete(pubkey)
+  }
+
+  scheduleLiveRecovery (pubkey) {
+    const current = this.liveRecoveryTimers.get(pubkey)
+    if (current) { current.again = true; return }
+    const work = { delay: 1000, timer: null, again: false }
+    this.liveRecoveryTimers.set(pubkey, work)
+    const isCurrent = () => this.liveRecoveryTimers.get(pubkey) === work && !this.closePromise &&
+      !this.pauseReasons.size && this.desiredChannels.has(pubkey)
+    const schedule = delay => {
+      work.timer = this._setTimeout(async () => {
+        work.timer = null
+        if (!isCurrent()) return
+        work.again = false
+        let errors
+        try {
+          // A ready notification may overtake cancellation of the previous scan.
+          // Let that scan retain its range, then start a fresh recovery attempt.
+          await this.recoveries.get(pubkey)
+          if (!isCurrent()) return
+          errors = await this.recoverOfflineRanges([pubkey])
+        } catch (error) {
+          this.onError?.(error)
+          errors = [error]
+        }
+        if (!isCurrent()) return
+        const pending = this.readState().channels[pubkey]?.offlineRanges?.length
+        const retry = pending ? recoveryRetryDelay(errors, Math.min(30000, work.delay * (0.8 + Math.random() * 0.4))) : null
+        if (work.again || retry !== null) {
+          schedule(work.again ? 0 : retry)
+          work.delay = Math.min(30000, work.delay * 2)
+        } else this.liveRecoveryTimers.delete(pubkey)
+      }, delay)
+      work.timer?.unref?.()
+    }
+    schedule(0)
+  }
+
   recordInterruption (channels, at = nowSeconds()) {
     const state = this.readState()
     for (const pubkey of channels) {
@@ -1152,6 +1226,8 @@ export class PrivateMessenger {
     const closing = []
     for (const pubkey of channels) {
       this.cancelReloadGap(pubkey)
+      this.cancelLiveRecovery(pubkey)
+      this.liveInterruptions.delete(pubkey)
       this.watchRevisionByChannel.set(pubkey, (this.watchRevisionByChannel.get(pubkey) || 0) + 1)
       const close = this.stopByChannel.get(pubkey)?.()
       if (close?.then) closing.push(close)
@@ -2063,6 +2139,7 @@ export class PrivateMessenger {
   }
 
   async recoverOfflineRanges (channels = [...this.stopByChannel.keys()]) {
+    const failures = []
     for (const pubkey of uniq(channels)) {
       if (this.pauseReasons.size || this.closePromise || !this.desiredChannels.has(pubkey)) continue
       let work = this.recoveries.get(pubkey)
@@ -2070,11 +2147,13 @@ export class PrivateMessenger {
         work = this.recoverChannelRanges([pubkey])
         this.recoveries.set(pubkey, work)
       }
-      try { await work } finally { if (this.recoveries.get(pubkey) === work) this.recoveries.delete(pubkey) }
+      try { failures.push(...await work) } finally { if (this.recoveries.get(pubkey) === work) this.recoveries.delete(pubkey) }
     }
+    return failures
   }
 
   async recoverChannelRanges (channels) {
+    const failures = []
     const state = this.readState()
     const now = nowSeconds()
 
@@ -2125,12 +2204,14 @@ export class PrivateMessenger {
           })
           controller.signal.throwIfAborted()
           const attempt = await this.#askSeedersForRelayLeftEdgeAttempt(pubkey, range, history.oldestCreatedAt)
-          const lifecycleChanged = this.closePromise || !this.channels.has(pubkey) || !this.stopByChannel.has(pubkey) ||
+          const lifecycleChanged = controller.signal.aborted || this.closePromise || !this.channels.has(pubkey) || !this.stopByChannel.has(pubkey) ||
             (this.watchRevisionByChannel.get(pubkey) || 0) !== watchRevision
+          failures.push(...attempt.failures.map(failure => failure.error))
           if (lifecycleChanged || attempt.failures.length) remaining.push(range)
           else recoveredThrough = Math.max(recoveredThrough, range.end)
         } catch (err) {
-          this.onError?.(err)
+          if (!(controller.liveInterrupted && err === controller.signal.reason)) this.onError?.(err)
+          failures.push(err)
           remaining.push(range)
         } finally { this.recoveryControllers.delete(controller) }
       }
@@ -2145,6 +2226,7 @@ export class PrivateMessenger {
       this.writeState(fresh)
       await this.flushStateWrites()
     }
+    return failures
   }
 
   async clearChannel (pubkey) {

package/relay/helpers/live-buffer-error.js

@@ -0,0 +1,15 @@
+// Bounded diagnostics only: never attach queued payloads or subscription filters.
+export function liveBufferError ({ relay, stage, queue, queuedBytes, incoming, incomingBytes, maxEvents, maxBytes, since }) {
+  const now = Date.now()
+  const boundaries = [since, incoming?.event?.created_at, ...queue.map(entry => entry.item?.event?.created_at)]
+    .filter(value => Number.isFinite(value) && value >= 0)
+  return Object.assign(new Error('RELAY_LIVE_BUFFER_FULL'), {
+    code: 'RELAY_LIVE_BUFFER_FULL', relay, phase: 'live-buffer',
+    recoverySince: Math.min(Math.floor(now / 1000), ...boundaries),
+    buffer: {
+      stage, queuedEvents: queue.length, queuedBytes, incomingBytes,
+      limits: { events: maxEvents, bytes: maxBytes },
+      oldestQueuedMs: queue.length ? Math.max(0, now - queue[0].receivedAt) : 0
+    }
+  })
+}

package/relay/services/relay-pool.js

@@ -1,3 +1,4 @@
+import { liveBufferError } from '../helpers/live-buffer-error.js'
 import { ValidationError } from '../../error/index.js'
 import { decodeHll, encodeHll, estimateHllCount, mergeHll } from '../helpers/hll.js'
 import { createPublishSettlements, firstFulfillment, publishSummary } from '../helpers/publish.js'
@@ -651,18 +652,23 @@ 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' })
+    const overflow = (item, bytes, stage = 'delivery', entries = queue, volume = queuedBytes) => {
+      if (isDone) return
+      failure = liveBufferError({
+        relay: item.relay, stage, queue: entries, queuedBytes: volume, incoming: item, incomingBytes: bytes,
+        maxEvents: maxBufferedLiveEvents, maxBytes: maxBufferedLiveBytes,
+        since: Math.min(sinceFloor, ...pendingGaps.values(), ...queue.map(entry => entry.item?.event?.created_at).filter(Number.isFinite))
+      })
       teardown()
     }
     const enqueue = item => {
       const bytes = encoder.encode(JSON.stringify(item)).byteLength
       if (queue.length >= maxBufferedLiveEvents || queuedBytes + bytes > maxBufferedLiveBytes) {
-        overflow(item.relay)
+        overflow(item, bytes)
         return
       }
       queuedBytes += bytes
-      queue.push({ item, bytes })
+      queue.push({ item, bytes, receivedAt: Date.now() })
       p.resolve()
       p = Promise.withResolvers()
     }
@@ -863,11 +869,11 @@ export class RelayPool {
             if (liveBuffer) {
               const bytes = encoder.encode(JSON.stringify(event)).byteLength
               if (liveBuffer.length >= maxBufferedLiveEvents || bufferedBytes + bytes > maxBufferedLiveBytes) {
-                overflow(url)
+                overflow({ event, relay: url }, bytes, 'reconnect', liveBuffer, bufferedBytes)
                 return
               }
               bufferedBytes += bytes
-              liveBuffer.push(event)
+              liveBuffer.push({ item: { event, relay: url }, receivedAt: Date.now() })
             } else pushEvent(event, url)
           },
           onclose: error => {
@@ -906,7 +912,7 @@ export class RelayPool {
           }).finally(() => {
             const buf = liveBuffer
             liveBuffer = null
-            for (const event of buf) pushEvent(event, url, true)
+            for (const entry of buf) pushEvent(entry.item.event, url, true)
             gapTasks.delete(task)
             scheduleProgress(attempt)
             p.resolve()
@@ -1052,9 +1058,9 @@ export class RelayPool {
           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' })
+              throw liveBufferError({ relay: item.relay, stage: 'history-wait', queue: liveBuffer, queuedBytes: bufferedBytes, incoming: item, incomingBytes: bytes, maxEvents: maxBufferedLiveEvents, maxBytes: maxBufferedLiveBytes, since: filter.since ?? 0 })
             }
-            liveBuffer.push({ item, bytes })
+            liveBuffer.push({ item, bytes, receivedAt: Date.now() })
             bufferedBytes += bytes
           }
           liveWake.resolve()