libp2r2p 0.11.13 → 0.11.15

package/README.md

@@ -136,12 +136,39 @@ 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.
+Every involuntary live close emits an error. Recoverable failures permit 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.
 
+### Failure-aware live recovery (0.11.15)
+
+Live readers retry connection/transport/timeouts and structured `rate-limited:`
+or `error:` refusals. Policy refusals (`blocked:`, `restricted:`, `auth-required:`,
+`pow:`), local authentication/validation failures and unknown errors stop that
+relay for this iterator. Other relays continue. When every route has stopped,
+the iterator finishes after draining accepted events and original diagnostics;
+its readiness snapshot never claims a failed route sent EOSE. A new explicit
+reader starts a new operation; refusals do not blacklist a relay across readers.
+
+Retry delays are 1, 2, 4... seconds, capped at five minutes without an attempt
+limit. The next attempt waits until max(backoff deadline, relay retryAt). A
+confirmed offline failure spends no backoff step: it waits for the existing
+shared `onOnline` monitor, without holding read-admission slots. Connectivity
+checks are bounded and shared per pool; structured relay responses need no new
+internet probe unless the browser indicates offline. Cancelled readers release
+their own waits without cancelling another reader's recovery.
+
+Successful live EOSE and any required reconnect history reset the delay.
+Transient reconnect-history failures retry while retaining their original gap
+baseline; definitive failures stop that route without certifying its gap.
+Accepted history and buffered live remain deliverable. Local queue-full,
+queue-timeout and disconnect admission failures retain local recovery; impossible
+capacity is terminal. Caller cancellation is silent. Native timeout messages stay
+unchanged and now consistently carry category `timeout`. Constructor hooks
+`_isOnline`/`_onOnline` are internal test injections, not an app bridge API.
+
 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
@@ -161,7 +188,7 @@ 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.
+live streams retain recovery for eligible failures 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
@@ -877,9 +904,42 @@ the first pass routes through up to `maxPerPubkey` shared relays, and missing
 authors are retried on every remaining relay plus `fallbackRelays` (default:
 the first three `freeRelays`), excluding what was already queried. It accepts
 `relaysByPubkey` to reuse a previous discovery (only missing pubkeys are then
-discovered) and returns `{ events, byPubkey, relaysByPubkey }` so the merged
+discovered) and returns `{ events, byPubkey, relaysByPubkey, requests }` so the merged
 relay map can be passed back on later calls.
 
+
+Read diagnostics preserve native failures rather than treating an empty result
+as proof that every relay completed successfully. `requests` contains records
+`{ phase, authors, relays, errors?, error? }`: phase is `discovery`, `primary` or
+`fallback`; `relays` uses the pool's `{ relay, status, error? }` outcomes. An
+operation-wide exception is retained as `error`. Events remain in the existing
+result fields, never in diagnostic records. `onQueryResult(record)` receives each
+record as the underlying query settles, including before a later cancellation.
+
+Both discovery and latest-event queries accept `signal`. Cancelling one consumer
+of shared NIP-65 discovery releases only its interest; the underlying query is
+aborted when its last consumer leaves. Discovery's optional `onQueryResult`
+receives the same native report for every joining caller. Incomplete/failed
+lookups can use fallback relays for that call but never negatively cache a
+missing relay list for forty minutes. Actual lists and completely empty EOSE
+responses retain their normal cache behavior.
+
+`getLatestEventsByPubkey` accepts `excludeRelaysByPubkey` (object or Map) for both
+passes. `getRelaysByPubkey` accepts `excludeRelays` for seed discovery; pass it
+through `relayListOptions` when using the two-pass query. Different exclusion
+sets do not share in-flight discovery that could contact a refused relay.
+
+`isRetryableRelayFailure(error)` identifies connection/transport/timeouts and
+leading `rate-limited:`/`error:` relay failures. `isReplaceableRelayFailure(error)`
+also admits relay policy refusals (`blocked:`, `restricted:`, `auth-required:`,
+`pow:`) for routing to alternatives, preserving the messenger's existing policy.
+Local authentication denials, invalid events and unknown errors qualify for
+neither policy. Predicates classify individual native errors; callers decide
+how to handle mixed per-relay outcomes and application-specific aggregates.
+Existing rate-limit parsing preserves numeric positive `retry_after` seconds as
+`retryAfterMs` and absolute `retryAt`, bounded to five minutes. Schedulers must
+use the later of their backoff deadline and `retryAt`, not add the two delays.
+
 ## Binary encodings
 
 Base16, Base36, Base62, Base64/Base64URL, and Base93 helpers are available

package/package.json

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

package/private-messenger/helpers/send-routing.js

@@ -1,19 +1,11 @@
 import { normalizeRelayUrl } from '../../url/index.js'
 import { ValidationError } from '../../error/index.js'
+import { isReplaceableRelayFailure } from '../../relay/helpers/failure.js'
 
-const REJECTION_PREFIXES = new Set(['blocked', 'restricted', 'auth-required', 'pow', 'rate-limited', 'error'])
-const TRANSPORT_CATEGORIES = new Set(['connection', 'transport', 'timeout'])
 const EXCLUSION_MS = 5 * 60 * 1000
 const normalized = relay => { try { return normalizeRelayUrl(relay) } catch { return '' } }
 
-// Only machine-readable relay policy/server failures qualify. Invalid events,
-// local signer denials and unknown prose must not rotate relays.
-export function isReplaceableRelayFailure (error) {
-  if (error?.name === 'Nip42AuthenticationError') return false
-  if (TRANSPORT_CATEGORIES.has(error?.category)) return true
-  if (error?.category && error.category !== 'relay') return false
-  return REJECTION_PREFIXES.has(/^([a-z-]+):/.exec(error?.message || '')?.[1])
-}
+export { isReplaceableRelayFailure }
 
 export function normalizeFallbackRelays (value = []) {
   if (!Array.isArray(value)) throw new ValidationError('INVALID_FALLBACK_RELAYS')

package/relay/helpers/failure.js

@@ -0,0 +1,15 @@
+const TRANSPORT_CATEGORIES = new Set(['connection', 'transport', 'timeout'])
+const RETRY_PREFIXES = new Set(['rate-limited', 'error'])
+const REPLACEMENT_PREFIXES = new Set(['blocked', 'restricted', 'auth-required', 'pow', ...RETRY_PREFIXES])
+
+// Retry and replacement are different policies: a refusal can justify another
+// relay without making the same operation retryable on the refusing relay.
+function matches (error, prefixes) {
+  if (error?.name === 'Nip42AuthenticationError') return false
+  if (TRANSPORT_CATEGORIES.has(error?.category)) return true
+  if (error?.category && error.category !== 'relay') return false
+  return prefixes.has(/^([a-z-]+):/.exec(error?.message || '')?.[1])
+}
+
+export const isRetryableRelayFailure = error => matches(error, RETRY_PREFIXES)
+export const isReplaceableRelayFailure = error => matches(error, REPLACEMENT_PREFIXES)

package/relay/helpers/read-admission.js

@@ -2,7 +2,7 @@ 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' })
+  return Object.assign(new Error(code), { code, relay, phase: 'admission', ...(code === 'RELAY_READ_QUEUE_TIMEOUT' ? { category: 'timeout' } : {}) })
 }
 
 // One FIFO per pooled connection. A feed reserves both REQs atomically; its

package/relay/helpers/read-retry.js

@@ -0,0 +1,106 @@
+import { isOnline, onOnline } from '../../network/index.js'
+import { isRetryableRelayFailure } from './failure.js'
+import { maybeUnref } from './timer.js'
+
+const LOCAL_RETRY_CODES = new Set(['RELAY_READ_QUEUE_FULL', 'RELAY_READ_QUEUE_TIMEOUT', 'RELAY_DISCONNECTED'])
+
+export function isRetryableReadFailure (error) {
+  if (error?.name === 'ValidationError' || error?.name === 'Nip42AuthenticationError') return false
+  if (error?.phase === 'admission') return LOCAL_RETRY_CODES.has(error.code)
+  return isRetryableRelayFailure(error)
+}
+
+export function needsConnectivityCheck (error) {
+  return globalThis.navigator?.onLine === false || (error?.phase !== 'admission' && ['connection', 'transport', 'timeout'].includes(error?.category))
+}
+
+export function waitUntil (deadline, signal) {
+  signal.throwIfAborted()
+  if (deadline <= Date.now()) return Promise.resolve()
+  return new Promise((resolve, reject) => {
+    const finish = () => { clearTimeout(timer); signal.removeEventListener('abort', abort); resolve() }
+    const abort = () => { clearTimeout(timer); signal.removeEventListener('abort', abort); reject(signal.reason) }
+    const timer = maybeUnref(setTimeout(finish, Math.max(0, deadline - Date.now())))
+    signal.addEventListener('abort', abort, { once: true })
+  })
+}
+
+function waitFor (promise, signal) {
+  signal.throwIfAborted()
+  return new Promise((resolve, reject) => {
+    const abort = () => { signal.removeEventListener('abort', abort); reject(signal.reason) }
+    signal.addEventListener('abort', abort, { once: true })
+    promise.then(value => { signal.removeEventListener('abort', abort); resolve(value) }, error => {
+      signal.removeEventListener('abort', abort); reject(error)
+    })
+  })
+}
+
+// One connectivity check/online subscription per pool, with independent waits.
+// Ending one reader must never cancel recovery still needed by another reader.
+export class ReadRetry {
+  #checkOnline
+  #watchOnline
+  #probe
+  #monitor
+  #waiters = new Set()
+
+  constructor ({ checkOnline = isOnline, watchOnline = onOnline } = {}) {
+    this.#checkOnline = checkOnline
+    this.#watchOnline = watchOnline
+  }
+
+  async confirmOnline (signal) {
+    signal.throwIfAborted()
+    if (globalThis.navigator?.onLine === false) return false
+    if (!this.#probe || this.#probe.controller.signal.aborted) {
+      const controller = new AbortController()
+      const record = { controller, users: 0, finished: false }
+      const stopped = new Promise(resolve => controller.signal.addEventListener('abort', () => resolve(false), { once: true }))
+      const timer = maybeUnref(setTimeout(() => controller.abort(), 6000))
+      record.promise = Promise.race([
+        Promise.resolve().then(() => this.#checkOnline({ signal: controller.signal })).catch(() => false), stopped
+      ]).then(value => value === true).finally(() => {
+        record.finished = true
+        clearTimeout(timer)
+        controller.abort()
+        if (this.#probe === record) this.#probe = null
+      })
+      this.#probe = record
+    }
+    const record = this.#probe
+    record.users++
+    try { return await waitFor(record.promise, signal) } finally {
+      if (--record.users === 0 && !record.finished) record.controller.abort()
+    }
+  }
+
+  waitUntilOnline (signal) {
+    signal.throwIfAborted()
+    const ready = Promise.withResolvers()
+    this.#waiters.add(ready)
+    if (!this.#monitor) {
+      const monitor = { stop: () => {}, ended: false }
+      this.#monitor = monitor
+      monitor.stop = this.#watchOnline(() => {
+        if (this.#monitor !== monitor) return
+        for (const waiter of this.#waiters) waiter.resolve()
+        this.#waiters.clear()
+        this.#stopIfIdle()
+      })
+      if (monitor.ended) monitor.stop()
+    }
+    return waitFor(ready.promise, signal).finally(() => {
+      this.#waiters.delete(ready)
+      this.#stopIfIdle()
+    })
+  }
+
+  #stopIfIdle () {
+    if (this.#waiters.size || !this.#monitor) return
+    const monitor = this.#monitor
+    this.#monitor = null
+    monitor.ended = true
+    monitor.stop()
+  }
+}

package/relay/index.js

@@ -1,4 +1,5 @@
 export { freeRelays, nappRelays, seedRelays } from './constants/index.js'
+export { isRetryableRelayFailure, isReplaceableRelayFailure } from './helpers/failure.js'
 export { pickRelaysForPubkeys } from './helpers/routing.js'
 export { RelayPool, relayPool } from './services/relay-pool.js'
 export { getLatestEventsByPubkey } from './services/events.js'

package/relay/services/events.js

@@ -45,7 +45,7 @@ function getSelectedRelaysByPubkey (pubkeys, relayToAuthors) {
 }
 
 // Fetches batched events and keeps the newest event per address.
-async function fetchLatestEventsByRelay (relayToAuthors, { kinds, dTagsByPubkey, getEvents }) {
+async function fetchLatestEventsByRelay (relayToAuthors, { kinds, dTagsByPubkey, getEvents, report, phase, signal }) {
   const requests = []
   for (const [relay, authors] of relayToAuthors) {
     const authorsByD = new Map()
@@ -57,8 +57,17 @@ async function fetchLatestEventsByRelay (relayToAuthors, { kinds, dTagsByPubkey,
     for (const [d, dAuthors] of authorsByD) {
       const filter = { kinds, authors: dAuthors }
       if (d) filter['#d'] = [d]
-      requests.push(getEvents(filter, [relay])
-        .then(response => ({ requested: new Set(dAuthors), events: (response.result || []).map(({ event }) => event) })))
+      requests.push(Promise.resolve().then(async () => {
+        signal?.throwIfAborted()
+        try {
+          const response = await getEvents(filter, [relay], signal ? { signal } : {})
+          report({ phase, authors: dAuthors, relays: response.relays || [], errors: response.errors || [] })
+          return { requested: new Set(dAuthors), events: (response.result || []).map(({ event }) => event) }
+        } catch (error) {
+          report({ phase, authors: dAuthors, relays: [{ relay, status: 'error', error }], error })
+          throw error
+        }
+      }))
     }
   }
 
@@ -95,11 +104,20 @@ export async function getLatestEventsByPubkey (pubkeys, {
   fallbackRelays = freeRelays.slice(0, DEFAULT_FALLBACK_RELAY_COUNT),
   relaysByPubkey,
   relayListOptions,
+  excludeRelaysByPubkey,
+  signal,
+  onQueryResult,
   _getRelaysByPubkey = getRelaysByPubkey,
   _getEvents = getEvents
 } = {}) {
+  signal?.throwIfAborted()
+  const requests = []
+  const report = request => { requests.push(request); onQueryResult?.(request) }
+  const excluded = pubkey => excludeRelaysByPubkey instanceof Map
+    ? excludeRelaysByPubkey.get(pubkey) || []
+    : excludeRelaysByPubkey?.[pubkey] || []
   const authors = [...new Set(pubkeys || [])].filter(Boolean)
-  if (!authors.length) return { events: [], byPubkey: {}, relaysByPubkey: {} }
+  if (!authors.length) return { events: [], byPubkey: {}, relaysByPubkey: {}, requests }
   if (!Array.isArray(kinds) || kinds.length === 0) {
     throw new ValidationError('MISSING_EVENT_KINDS', { message: 'Missing kinds' })
   }
@@ -110,9 +128,16 @@ export async function getLatestEventsByPubkey (pubkeys, {
   if (missingRelayAuthors.length) {
     let discovered
     try {
-      discovered = await _getRelaysByPubkey(missingRelayAuthors, relayListOptions)
+      discovered = await _getRelaysByPubkey(missingRelayAuthors, {
+        ...relayListOptions,
+        ...(signal ? { signal } : {}),
+        onQueryResult: request => { report({ ...request, phase: 'discovery' }); relayListOptions?.onQueryResult?.(request) }
+      })
     } catch (error) {
-      console.error('Failed to discover publisher relays:', error)
+      signal?.throwIfAborted()
+      if (!requests.some(request => request.phase === 'discovery' && request.error === error)) {
+        report({ phase: 'discovery', authors: missingRelayAuthors, relays: [], error })
+      }
       discovered = Object.fromEntries(missingRelayAuthors.map(pubkey => [pubkey, { read: [], write: [] }]))
     }
     for (const pubkey of missingRelayAuthors) {
@@ -120,14 +145,17 @@ export async function getLatestEventsByPubkey (pubkeys, {
     }
   }
 
+  signal?.throwIfAborted()
   const primaryAuthors = authors.filter(pubkey => relaysByAuthor[pubkey]?.[type]?.length)
-  const primaryRoutes = pickRelaysForPubkeys(primaryAuthors, relaysByAuthor, { maxPerPubkey, relayType })
+  const primaryRoutes = pickRelaysForPubkeys(primaryAuthors, relaysByAuthor, { maxPerPubkey, relayType, excludeRelaysByPubkey, emptyRelaysFallback: [] })
   const selectedRelays = getSelectedRelaysByPubkey(authors, primaryRoutes)
+  for (const pubkey of authors) for (const relay of excluded(pubkey)) selectedRelays[pubkey].add(relay)
   const latestByAddress = await fetchLatestEventsByRelay(primaryRoutes, {
     kinds,
     dTagsByPubkey,
-    getEvents: _getEvents
+    getEvents: _getEvents, report, phase: 'primary', signal
   })
+  signal?.throwIfAborted()
   const foundPubkeys = new Set(Object.values(latestByAddress).map(event => event.pubkey))
   const missingAuthors = authors.filter(pubkey => !foundPubkeys.has(pubkey))
 
@@ -145,13 +173,14 @@ export async function getLatestEventsByPubkey (pubkeys, {
       await fetchLatestEventsByRelay(fallbackRoutes, {
         kinds,
         dTagsByPubkey,
-        getEvents: _getEvents
+        getEvents: _getEvents, report, phase: 'fallback', signal
       })
     ))
   }
 
+  signal?.throwIfAborted()
   const events = Object.values(latestByAddress)
   const byPubkey = {}
   for (const event of events) byPubkey[event.pubkey] = event
-  return { events, byPubkey, relaysByPubkey: relaysByAuthor }
+  return { events, byPubkey, relaysByPubkey: relaysByAuthor, requests }
 }

package/relay/services/query.js

@@ -224,28 +224,27 @@ export function subscribeRelayListUpdates (pubkeys, {
 }
 
 async function loadMissingRelays (missingPubkeys, {
-  getEvents,
-  cacheMs,
-  timeout = RELAY_LIST_QUERY_TIMEOUT_MS,
-  timeoutAfterFirstEose = RELAY_LIST_QUERY_TIMEOUT_AFTER_FIRST_EOSE_MS,
-  relayUrlPolicy,
-  emptyRelaysFallback = freeRelays.slice(0, 2)
+  getEvents, cacheMs, timeout, timeoutAfterFirstEose, relayUrlPolicy,
+  emptyRelaysFallback, excludeRelays, signal
 }) {
-  const { result: events } = await getEvents({
-    kinds: [10002],
-    authors: missingPubkeys,
-    limit: missingPubkeys.length
-  }, seedRelays, {
-    timeout,
-    timeoutAfterFirstEose
-  })
-
+  let response
+  try {
+    response = await getEvents({ kinds: [10002], authors: missingPubkeys, limit: missingPubkeys.length },
+      seedRelays.filter(relay => !excludeRelays.includes(relay)), { timeout, timeoutAfterFirstEose, signal })
+    signal.throwIfAborted()
+  } catch (error) {
+    return { entries: {}, report: { authors: missingPubkeys, relays: [], error } }
+  }
+  const report = { authors: missingPubkeys, relays: response.relays || [], errors: response.errors || [] }
+  const complete = response.relays
+    ? response.relays.length > 0 && response.relays.every(item => item.status === 'eose')
+    : !response.errors?.length
   const latestByPubkey = {}
-  for (const { event } of events || []) {
+  for (const { event } of response.result || []) {
     if (!missingPubkeys.includes(event.pubkey)) continue
     if (isNewerRelayListEvent(event, latestByPubkey[event.pubkey])) latestByPubkey[event.pubkey] = event
   }
-
+  const entries = {}
   for (const pubkey of missingPubkeys) {
     const fetchedEvent = latestByPubkey[pubkey]
     const cachedEvent = relayCacheEventByPubkey[pubkey] || null
@@ -253,9 +252,29 @@ async function loadMissingRelays (missingPubkeys, {
     const relays = event
       ? parseRelayListEvent(event, relayUrlPolicy)
       : { read: [...emptyRelaysFallback], write: [...emptyRelaysFallback] }
-    setCachedRelays(pubkey, relays, event, cacheMs)
+    entries[pubkey] = { ...relays, event }
+    // A failed/incomplete lookup may use fallbacks for this call, but must not
+    // turn that failure into a forty-minute negative discovery cache entry.
+    if (fetchedEvent || complete) setCachedRelays(pubkey, relays, event, cacheMs)
   }
   pruneRelayCache()
+  return { entries, report }
+}
+
+// Each caller owns its wait, not another caller's shared discovery request.
+function waitForDiscovery (record, signal) {
+  signal?.throwIfAborted()
+  record.users++
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason)
+    signal?.addEventListener('abort', abort, { once: true })
+    record.promise.then(resolve, reject).finally(() => signal?.removeEventListener('abort', abort))
+  }).finally(() => {
+    if (--record.users === 0 && !record.finished) {
+      record.controller.abort()
+      record.remove()
+    }
+  })
 }
 
 export async function getRelaysByPubkey (pubkeys, {
@@ -266,40 +285,48 @@ export async function getRelaysByPubkey (pubkeys, {
   timeout = RELAY_LIST_QUERY_TIMEOUT_MS,
   timeoutAfterFirstEose = RELAY_LIST_QUERY_TIMEOUT_AFTER_FIRST_EOSE_MS,
   relayUrlPolicy,
-  emptyRelaysFallback = freeRelays.slice(0, 2)
+  emptyRelaysFallback = freeRelays.slice(0, 2),
+  excludeRelays = [],
+  signal,
+  onQueryResult
 } = {}) {
+  signal?.throwIfAborted()
   const pubkeyList = uniquePubkeys(pubkeys, { requireHex: _getEvents === getEvents })
   if (!pubkeyList.length) return {}
-
-  const loadPubkeys = forceRefresh
-    ? pubkeyList
-    : pubkeyList.filter(pubkey => !hasCachedKey(relaysByPubkey, pubkey))
-  const pubkeysToLoad = loadPubkeys.filter(pubkey => !relayRequestsByPubkey.has(pubkey))
+  // Different exclusions cannot share a request that contacts a refused relay.
+  const scope = JSON.stringify([...new Set(excludeRelays)].sort())
+  const key = pubkey => `${pubkey}:${scope}`
+  const loadPubkeys = forceRefresh ? pubkeyList : pubkeyList.filter(pubkey => !hasCachedKey(relaysByPubkey, pubkey))
+  const pubkeysToLoad = loadPubkeys.filter(pubkey => !relayRequestsByPubkey.has(key(pubkey)))
   if (pubkeysToLoad.length) {
-    const request = loadMissingRelays(pubkeysToLoad, {
-      getEvents: _getEvents,
-      cacheMs,
-      timeout,
-      timeoutAfterFirstEose,
-      relayUrlPolicy,
-      emptyRelaysFallback
-    }).finally(() => {
+    const record = { controller: new AbortController(), users: 0, finished: false }
+    record.remove = () => {
       for (const pubkey of pubkeysToLoad) {
-        if (relayRequestsByPubkey.get(pubkey) === request) relayRequestsByPubkey.delete(pubkey)
+        if (relayRequestsByPubkey.get(key(pubkey)) === record) relayRequestsByPubkey.delete(key(pubkey))
       }
-    })
-    for (const pubkey of pubkeysToLoad) relayRequestsByPubkey.set(pubkey, request)
+    }
+    record.promise = loadMissingRelays(pubkeysToLoad, {
+      getEvents: _getEvents, cacheMs, timeout, timeoutAfterFirstEose, relayUrlPolicy,
+      emptyRelaysFallback, excludeRelays, signal: record.controller.signal
+    }).finally(() => { record.finished = true; record.remove() })
+    for (const pubkey of pubkeysToLoad) relayRequestsByPubkey.set(key(pubkey), record)
   }
-
-  await Promise.all([...new Set(
-    loadPubkeys.map(pubkey => relayRequestsByPubkey.get(pubkey)).filter(Boolean)
-  )])
-
-  return Object.fromEntries(pubkeyList
-    .filter(pubkey => hasCachedKey(relaysByPubkey, pubkey))
-    .map(pubkey => {
-      const entry = cloneRelays(relaysByPubkey[pubkey])
-      if (includeEvents) entry.event = cloneRelayListEvent(relayCacheEventByPubkey[pubkey])
-      return [pubkey, entry]
-    }))
+  const entries = {}
+  const records = [...new Set(loadPubkeys.map(pubkey => relayRequestsByPubkey.get(key(pubkey))).filter(Boolean))]
+  await Promise.all(records.map(async record => {
+    const result = await waitForDiscovery(record, signal)
+    signal?.throwIfAborted()
+    // Deliver the same native diagnostics to every interested caller, including
+    // callers that joined an already running query.
+    onQueryResult?.(result.report)
+    if (result.report.error) throw result.report.error
+    Object.assign(entries, result.entries)
+  }))
+  signal?.throwIfAborted()
+  return Object.fromEntries(pubkeyList.map(pubkey => {
+    const source = hasCachedKey(relaysByPubkey, pubkey) ? relaysByPubkey[pubkey] : entries[pubkey]
+    const entry = cloneRelays(source || { read: emptyRelaysFallback, write: emptyRelaysFallback })
+    if (includeEvents) entry.event = cloneRelayListEvent(relayCacheEventByPubkey[pubkey] || entries[pubkey]?.event)
+    return [pubkey, entry]
+  }))
 }

package/relay/services/relay-pool.js

@@ -5,7 +5,8 @@ import { createPublishSettlements, firstFulfillment, publishSummary } from '../h
 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'
+import { categorizeRelayError, relayTimeoutError } from '../helpers/error.js'
+import { ReadRetry, isRetryableReadFailure, needsConnectivityCheck, waitUntil } from '../helpers/read-retry.js'
 import { normalizeRelayUrl } from '../../url/index.js'
 import { RelayConnection } from './relay-connection.js'
 
@@ -76,11 +77,11 @@ function countResponseError () {
 }
 
 function countTimeoutError () {
-  return new Error('COUNT_TIMEOUT')
+  return relayTimeoutError('COUNT_TIMEOUT')
 }
 
 function getEventsTimeoutError () {
-  return new Error('GET_EVENTS_TIMEOUT')
+  return relayTimeoutError('GET_EVENTS_TIMEOUT')
 }
 
 function asError (error) {
@@ -138,11 +139,13 @@ export class RelayPool {
   #createRelay
   #WebSocket
   #admission
+  #readRetry
 
-  constructor ({ _createRelay, WebSocket: WebSocketImpl, ...capacity } = {}) {
+  constructor ({ _createRelay, _isOnline, _onOnline, WebSocket: WebSocketImpl, ...capacity } = {}) {
     this.#WebSocket = WebSocketImpl
     this.#createRelay = _createRelay ?? (url => new RelayConnection(url, this.#WebSocket ? { WebSocket: this.#WebSocket } : undefined))
     this.#admission = new ReadAdmission(capacity)
+    this.#readRetry = new ReadRetry({ checkOnline: _isOnline, watchOnline: _onOnline })
   }
 
   // Injects the WebSocket implementation used by new pooled connections (e.g.
@@ -600,6 +603,9 @@ export class RelayPool {
     const gapTasks = new Set()
     const liveSubs = new Map() // url → live sub
     const retryTimers = new Map()
+    const retryDelays = new Map()
+    const stoppedRelays = new Set()
+    const retainedRelays = new Set()
     const initialPending = new Set(urls)
     const initialOutcomes = new Map()
     const readyTimeouts = new Map()
@@ -708,7 +714,7 @@ export class RelayPool {
         clearTimeout(attempt.timer)
         attempt.stop.abort()
       }
-      for (const timer of retryTimers.values()) clearTimeout(timer)
+      for (const retry of retryTimers.values()) retry.abort()
       retryTimers.clear()
       liveSubs.forEach(sub => sub.close())
       liveSubs.clear()
@@ -768,14 +774,61 @@ export class RelayPool {
       }
     }
 
-    const scheduleReconnect = (url, reconnectDelay) => {
-      if (isDone || retryTimers.has(url)) return
-      const nextDelay = Math.min(reconnectDelay * 2, 5 * 60_000)
-      const timer = maybeUnref(setTimeout(() => {
-        retryTimers.delete(url)
-        subscribeToRelay(url, pendingGaps.get(url) ?? lastSeenAt.get(url) ?? openedAt.get(url) ?? null, nextDelay)
-      }, reconnectDelay))
-      retryTimers.set(url, timer)
+    const releaseRelay = url => {
+      if (retainedRelays.delete(url)) this.#decrementLiveSub(url)
+    }
+    const closeAttempt = (url, attempt) => {
+      if (!attempt || attempt.closed) return
+      attempt.closed = true
+      clearTimeout(attempt.timer)
+      attempt.stop.abort()
+      const sub = liveSubs.get(url)
+      liveSubs.delete(url)
+      sub?.close()
+      liveLeases.get(url)?.release()
+      liveLeases.delete(url)
+      readyRelays.delete(url)
+    }
+    const stopRelay = url => {
+      stoppedRelays.add(url)
+      retryTimers.get(url)?.abort()
+      retryTimers.delete(url)
+      closeAttempt(url, attempts.get(url))
+      releaseRelay(url)
+      if (stoppedRelays.size === urls.length) { finishReady(); teardown(true) }
+    }
+    const scheduleReconnect = (url, error) => {
+      if (isDone || stoppedRelays.has(url) || retryTimers.has(url)) return
+      if (!isRetryableReadFailure(error)) { stopRelay(url); return }
+      const retry = new AbortController()
+      const retrySignal = AbortSignal.any([gapAc.signal, retry.signal])
+      const failedAt = Date.now()
+      const delay = retryDelays.get(url) ?? 1000
+      const retryAt = Number.isFinite(error?.retryAt)
+        ? error.retryAt
+        : Number.isFinite(error?.retryAfterMs) && error.retryAfterMs > 0 ? failedAt + Math.min(error.retryAfterMs, 300000) : 0
+      retryTimers.set(url, retry)
+      ;(async () => {
+        const online = !needsConnectivityCheck(error) || await this.#readRetry.confirmOnline(retrySignal)
+        retrySignal.throwIfAborted()
+        const deadline = Math.max(failedAt + (online ? delay : 0), retryAt)
+        if (online) retryDelays.set(url, Math.min(delay * 2, 300000))
+        else await this.#readRetry.waitUntilOnline(retrySignal)
+        while (!retrySignal.aborted) {
+          await waitUntil(deadline, retrySignal)
+          if (needsConnectivityCheck(error) && !await this.#readRetry.confirmOnline(retrySignal)) {
+            await this.#readRetry.waitUntilOnline(retrySignal)
+            continue
+          }
+          retrySignal.throwIfAborted()
+          if (isDone || stoppedRelays.has(url) || retryTimers.get(url) !== retry) return
+          retryTimers.delete(url)
+          subscribeToRelay(url, pendingGaps.get(url) ?? lastSeenAt.get(url) ?? openedAt.get(url) ?? null)
+          return
+        }
+      })().catch(failure => {
+        if (!retrySignal.aborted && !isDone) { reportFailure(url, asError(failure)); stopRelay(url) }
+      })
     }
 
     // Schedule teardown when the wall clock reaches filter.until
@@ -799,26 +852,36 @@ export class RelayPool {
       })
       return (async () => {
         let completed = false
-        let failed = false
+        let error
         for await (const item of gapGen) {
           if (item?.type === 'event') {
             observeEvent(item.event, url)
             pushEvent(item.event, url, true)
           } else if (item?.type === 'error') {
-            failed = true
+            if (!error || !isRetryableReadFailure(item.error)) error = item.error
             if (!isDone) enqueue(item)
           } else if (item?.type === 'eose') {
             completed = item.relays?.length === 1 && ['eose', 'satisfied'].includes(item.relays[0].status)
+            if (!completed && !error) {
+              error = item.relays?.[0]?.error || categorizeRelayError(new Error('RELAY_RECONNECT_GAP_INCOMPLETE'), 'timeout')
+              if (!isDone) enqueue({ type: 'error', relay: url, error })
+            }
           }
         }
-        return completed && !failed
+        if (!completed && !error && !attempt.stop.signal.aborted && !isDone) {
+          error = new Error('RELAY_RECONNECT_GAP_INCOMPLETE')
+          reportFailure(url, error)
+        }
+        return { recovered: completed && !error, error }
       })().catch(err => {
-        reportFailure(url, asError(err))
-        return false
+        const error = asError(err)
+        if (!attempt.stop.signal.aborted) reportFailure(url, error)
+        return { recovered: false, error }
       }).finally(() => slots.history.release())
     }
 
-    const subscribeToRelay = (url, gapSince, reconnectDelay = 1000) => {
+    const subscribeToRelay = (url, gapSince) => {
+      if (isDone || stoppedRelays.has(url)) return
       let now = Math.floor(Date.now() / 1000)
       // Don't reconnect if we're past the until boundary
       if (filterUntil !== null && now >= filterUntil) return
@@ -829,10 +892,10 @@ export class RelayPool {
       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 => {
+      Promise.resolve(reservation || this.#admission.acquire(normalizeRelayUrl(url), { live: true, history: recovering, signal: AbortSignal.any([gapAc.signal, attempt.stop.signal]), queueTimeout })).then(async slots => {
         const lease = slots.live
         recoveryLease = recovering ? slots.history : null
-        if (isDone) { lease.release(); recoveryLease?.release(); return }
+        if (isDone || attempt.closed) { lease.release(); recoveryLease?.release(); return }
         liveLeases.set(url, lease)
         if (timeout !== null && initialPending.has(url)) {
           readyTimeouts.set(url, maybeUnref(setTimeout(() => {
@@ -844,7 +907,7 @@ export class RelayPool {
           }, timeout)))
         }
         const relay = await this.#getRelay(url)
-        if (isDone) { recoveryLease?.release(); return }
+        if (isDone || attempt.closed) { lease.release(); recoveryLease?.release(); return }
         now = Math.floor(Date.now() / 1000)
         if (filterUntil !== null && now >= filterUntil) { lease.release(); recoveryLease?.release(); return }
 
@@ -878,37 +941,39 @@ export class RelayPool {
           },
           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)
-            lease.release()
-            if (liveLeases.get(url) === lease) liveLeases.delete(url)
-            readyRelays.delete(url)
+            closeAttempt(url, attempt)
             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)
+            if (error !== undefined) { error = asError(error); reportFailure(url, error) } else {
+              error = Object.assign(categorizeRelayError(new Error('RELAY_LIVE_INTERRUPTED'), 'transport'), { code: 'RELAY_LIVE_INTERRUPTED' })
+              enqueue({ type: 'error', relay: url, error })
+              reportClosed(url, error)
             }
-            scheduleReconnect(url, reconnectDelay)
+            scheduleReconnect(url, error)
           },
           oneose: () => {
             if (isDone || attempt.closed || attempts.get(url) !== attempt || liveEose) return
             liveEose = true
             attempt.since = Math.max(sinceFloor, Math.floor(Date.now() / 1000))
             markInitialEose(url)
+            if (attempt.recovered) retryDelays.delete(url)
             scheduleProgress(attempt)
           }
         })
-        if (isDone) { liveSub.close(); recoveryLease?.release(); return }
+        if (isDone || attempt.closed) { liveSub.close(); lease.release(); recoveryLease?.release(); return }
         liveSubs.set(url, liveSub)
 
         if (recovering) {
-          const task = runReconnectGapFill(url, gapSince, now, slots, attempt).then(recovered => {
+          const task = runReconnectGapFill(url, gapSince, now, slots, attempt).then(({ recovered, error }) => {
             attempt.recovered = recovered
-            if (recovered && !attempt.closed && attempts.get(url) === attempt) pendingGaps.delete(url)
+            if (!attempt.closed && attempts.get(url) === attempt) {
+              if (recovered) {
+                pendingGaps.delete(url)
+                if (liveEose) retryDelays.delete(url)
+              } else if (error && !isDone) {
+                closeAttempt(url, attempt)
+                scheduleReconnect(url, error)
+              }
+            }
           }).finally(() => {
             const buf = liveBuffer
             liveBuffer = null
@@ -925,9 +990,10 @@ export class RelayPool {
         liveLeases.delete(url)
         readyRelays.delete(url)
         const reason = err instanceof Error ? err : new Error(String(err))
+        if (isDone || attempt.closed) return
+        closeAttempt(url, attempt)
         reportFailure(url, reason)
-        if (isDone) return
-        scheduleReconnect(url, reconnectDelay)
+        scheduleReconnect(url, reason)
       })
     }
 
@@ -946,6 +1012,7 @@ export class RelayPool {
 
     for (const url of urls) {
       this.#incrementLiveSub(url)
+      retainedRelays.add(url)
       subscribeToRelay(url, null) // no initial gap fill — that's getEventsFeedGenerator's job
     }
 
@@ -960,7 +1027,7 @@ export class RelayPool {
     } finally {
       signal?.removeEventListener('abort', abort)
       _stopSignal?.removeEventListener('abort', stop)
-      for (const url of urls) this.#decrementLiveSub(url)
+      for (const url of [...retainedRelays]) releaseRelay(url)
       teardown()
     }
   }