libp2r2p 0.11.12 → 0.11.14

package/README.md

@@ -877,9 +877,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
@@ -991,7 +1024,10 @@ messages, history and files while preserving automatic NIP-65 updates. Successfu
 latency, and short-lived channel/recipient preferences avoid recently refused
 relays without changing receive subscriptions. See the
 [session coordinator](private-messenger/session/README.md) for deferred offline
-attempts and final failure notifications.
+attempts and final failure notifications. Sends attempted while the messenger is
+paused or otherwise unavailable now stay pending in the outbox and retry on a
+bounded session backoff (1–30 seconds, 20% jitter) instead of surfacing a
+user-facing send error.
 
 
 ### Relay backpressure and bounded synchronization (0.11.7)
@@ -1030,10 +1066,12 @@ 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.
+backoff and 20% jitter, reset after a stable minute. Relay-pool capacity closes
+(1013, "relay pool capacity") use the same relay backoff instead of stopping
+until an explicit rebuild, because the launcher pool bucket budget is transient.
+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.

package/package.json

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

package/private-message/index.js

@@ -21,6 +21,18 @@ function uniq (values) {
   return [...new Set((values || []).filter(Boolean))]
 }
 
+// The launcher's shared relay pool closes anonymous members with 1013 when its
+// per-relay buckets are all busy. That is a transient pool condition, not a
+// permanent relay rejection, so the shared subscription must keep the normal
+// relay backoff instead of stopping until something else re-opens it.
+function isRelayPoolCapacity (error) {
+  for (let current = error, depth = 0; current && depth < 3; current = current.cause, depth++) {
+    if (current.closeCode === 1013 || current.code === 'RELAY_POOL_CAPACITY') return true
+    if (/relay pool capacity/i.test(current.message || '')) return true
+  }
+  return false
+}
+
 function normalizeDeletionPubkey (deletionPubkey) {
   if (deletionPubkey === undefined) return undefined
   if (typeof deletionPubkey !== 'string' || !HEX_PUBKEY.test(deletionPubkey)) {
@@ -360,8 +372,9 @@ export function createPrivateMessageSession ({ _setTimeout = setTimeout, _clearT
       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)) {
+    const permanent = /^(auth-required:|restricted:|blocked:|invalid:|pow:)/.test(error.message || '') || error.name === 'ValidationError'
+    const retryable = error.code === 'RELAY_LIVE_BUFFER_FULL' || isRelayPoolCapacity(error) || Boolean(previous)
+    if (permanent || !retryable) {
       cancelRelayRecovery(relay)
       notifyInterruption(relay, recovery).catch(error => reportSubscriptionError(entry.channels, error))
       return

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')
@@ -102,6 +94,11 @@ export function createSendRelayRouting ({ peer, peers = [peer], relaysByPubkey,
         errors: reports.flatMap(report => report.errors || [])
       }))
     })
+    // A lifecycle change (signer/pause) during a batch is not a user abort:
+    // every failure summary stays retryable so the session can re-attempt it.
+    const finished = result => current()
+      ? finish(result)
+      : { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: !signal?.aborted }
     let result = { success: false }
     while ((batch ||= next())) {
       signal?.throwIfAborted()
@@ -124,15 +121,15 @@ export function createSendRelayRouting ({ peer, peers = [peer], relaysByPubkey,
         const report = await settled
         const failed = rejected(report)
         errors.push(...(report?.errors || []))
-        if (!failed.length || errors.some(item => !isReplaceableRelayFailure(item.reason))) return finish(result)
-        if (!next()) { exclusions.clear(); return finish(result) }
-        if (!await online()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: current() }
+        if (!failed.length || errors.some(item => !isReplaceableRelayFailure(item.reason))) return finished(result)
+        if (!next()) { exclusions.clear(); return finished(result) }
+        if (!await online()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: !signal?.aborted }
         remember(failed)
       }
-      if (!current()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: false }
+      if (!current()) return finished(result)
       batch = null
     }
-    return finish(result)
+    return finished(result)
   }
 
   return {

package/private-messenger/session/README.md

@@ -40,6 +40,14 @@ or cancelled/closed sends. Apps own route visibility and user-intent filtering;
 automatic retries may also fail. Callbacks must not throw. Errors are not copied
 into persisted outbox records.
 
+Sends that only failed because the messenger was paused or otherwise
+unavailable (`PRIVATE_MESSENGER_PAUSED`, `CHAT_UNAVAILABLE`) stay pending
+without `onSendError`. The session re-pumps them on a bounded backoff
+(1–30 seconds with 20% jitter) in addition to availability/connectivity
+changes, so a paused messenger recovers without a manual retry. The backoff
+resets on a user `retry`, on `setAvailable(true)`, and once no retryable entry
+remains.
+
 `enqueue({ peer, event, context, requiredFiles, deletion })` preserves prepared
 identities. Local message commits and remote stages have independent checkpoints.
 It sends original/thumbnail chunks before announcements, yields for small messages,

package/private-messenger/session/index.js

@@ -18,8 +18,20 @@ export function wireEvent (value, owner) {
 }
 // Relay rejection text must not be interpreted as a local signer denial.
 const retryable = error => error?.code === 'MESSAGE_NOT_PUBLISHED' || !/DENIED|PERMISSION|REVOKED|READ_ONLY|INVALID|BLOCKED|EXPIRED|NOT_IN_PERSONA/i.test(`${error?.code || ''} ${error?.message || ''}`)
+const unavailableSend = /PRIVATE_MESSENGER_PAUSED|CHAT_UNAVAILABLE|MESSENGER_UNAVAILABLE/i
+const isUnavailableSend = error => unavailableSend.test(`${error?.code || ''} ${error?.message || ''}`)
+const SEND_RETRY_MIN_MS = 1000
+const SEND_RETRY_MAX_MS = 30000
+// A paused or unavailable messenger must keep the outbox entry retryable
+// instead of surfacing a send failure the user has to retry by hand.
+const unavailableError = (error, signal) => Object.assign(new Error(error?.message || 'CHAT_UNAVAILABLE'), {
+  code: error?.code,
+  cause: error,
+  retryWhenAvailable: !signal?.aborted,
+  retryWhenOnline: false
+})
 
-export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], useContentKeys = true, onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, _getIykcProofs = getIykcProofs, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], useContentKeys = true, onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, _getIykcProofs = getIykcProofs, _setTimeout = setTimeout, _clearTimeout = clearTimeout, _random = Math.random, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
   fallbackRelays = normalizeFallbackRelays(fallbackRelays)
   const reportedErrors = new WeakSet()
   const reportError = error => {
@@ -40,6 +52,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   const sendControllers = new Map()
   const offlineSends = new Set()
   let stopOnline
+  let sendRetryTimer
+  let sendRetryDelay = SEND_RETRY_MIN_MS
   let messenger
   let fileTransfers
   let downloads
@@ -60,6 +74,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   let lifecycle = 0
   let configuring = Promise.resolve()
   let sending
+  let repump
   let draining
   const idleWaiters = new Set()
   const settled = () => { if (!sending && !draining) { for (const resolve of idleWaiters) resolve(); idleWaiters.clear() } }
@@ -179,9 +194,15 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   }
   async function publish (peer, event, signal) {
     if (deniedPeers.has(peer)) throw new Error('PERMISSION_DENIED')
-    if (!available || !peers.has(peer) || !channels.has(peer)) throw new Error('CHAT_UNAVAILABLE')
+    if (!available || !peers.has(peer) || !channels.has(peer)) throw unavailableError(new Error('CHAT_UNAVAILABLE'), signal)
     const options = { channelPubkey: channels.get(peer)?.pubkey, receiverPubkeys: [peer], signal }
-    const report = event.sig ? await messenger.broadcastEvent({ ...options, event }) : await messenger.broadcastRumor({ ...options, rumor: event })
+    let report
+    try {
+      report = event.sig ? await messenger.broadcastEvent({ ...options, event }) : await messenger.broadcastRumor({ ...options, rumor: event })
+    } catch (error) {
+      if (isUnavailableSend(error)) throw unavailableError(error, signal)
+      throw error
+    }
     // Published is relay acceptance, never a peer receipt.
     await assertMessagePublished(report, event)
   }
@@ -245,7 +266,10 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       await storage.remove(entry.id)
       entries.delete(entry.id)
       emit()
-    } catch (error) {
+    } catch (cause) {
+      // Pauses can surface at any stage (text publication, file authorization
+      // or chunk delivery). Normalize all of them into the retryable path.
+      const error = cause?.retryWhenAvailable ? cause : (isUnavailableSend(cause) ? unavailableError(cause, controller.signal) : cause)
       if (cancelled.has(entry.id)) { await storage.remove(entry.id); entries.delete(entry.id) } else {
         entry.status = error.retryWhenAvailable ? 'pending' : 'error'; entry.failed = true; entry.retryable = retryable(error)
         await storage.put(entry, { existing: true }).catch(reportError)
@@ -253,12 +277,42 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
         // The failed wire event may be a quote or file chunk. Report the
         // owning outbox item separately, without mutating the native error.
         if (error.retryWhenOnline) offlineSends.add(entry.id)
+        if (error.retryWhenAvailable) scheduleSendRetry()
         if (!closed && !entry.deletion && !cancelled.has(entry.id) && !error.retryWhenAvailable) onSendError(error, { id: entry.id, peer: entry.peer })
       }
       emit()
     } finally { sendControllers.delete(entry.id) }
   }
   function stopOnlineRetry () { stopOnline?.(); stopOnline = undefined }
+  // Entries that failed only because the messenger was paused/unavailable do
+  // not receive a connectivity transition, so they own a bounded backoff timer
+  // instead of waiting for the next account-state change.
+  function clearSendRetry () {
+    if (sendRetryTimer) _clearTimeout(sendRetryTimer)
+    sendRetryTimer = undefined
+  }
+  function resetSendRetry () {
+    clearSendRetry()
+    sendRetryDelay = SEND_RETRY_MIN_MS
+  }
+  const pendingRetryable = entry => Boolean(entry.failed && !cancelled.has(entry.id) && (entry.retryable || entry.status === 'pending'))
+  function scheduleSendRetry () {
+    if (closed || !available || sendRetryTimer) return
+    const delay = Math.min(SEND_RETRY_MAX_MS, sendRetryDelay * (0.8 + _random() * 0.4))
+    sendRetryDelay = Math.min(SEND_RETRY_MAX_MS, sendRetryDelay * 2)
+    sendRetryTimer = _setTimeout(() => {
+      sendRetryTimer = undefined
+      if (closed || !available) return
+      let retried = false
+      for (const entry of entries.values()) {
+        if (!pendingRetryable(entry)) continue
+        entry.failed = false
+        retried = true
+      }
+      if (retried) pump()
+    }, delay)
+    sendRetryTimer.unref?.()
+  }
   function watchOfflineSends () {
     if (closed || !available || !offlineSends.size) { stopOnlineRetry(); return }
     if (stopOnline) return
@@ -276,15 +330,26 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     })
   }
   async function pump () {
-    if (sending || !available || closed || !messenger || !storage) return
+    if (!available || closed || !messenger || !storage) return
+    // A retry that lands while a pump is already running must not be skipped
+    // just because that pass already walked past the entry.
+    if (sending) { repump = true; return }
     sending = true
     try {
-      for (const entry of entries.values()) {
-        if (closed || !available) break
-        if ((entry.peer !== owner && !peers.has(entry.peer)) || entry.failed || cancelled.has(entry.id)) continue
-        await sendEntry(entry)
-      }
-    } finally { sending = false; watchOfflineSends(); settled() }
+      do {
+        repump = false
+        for (const entry of entries.values()) {
+          if (closed || !available) break
+          if ((entry.peer !== owner && !peers.has(entry.peer)) || entry.failed || cancelled.has(entry.id)) continue
+          await sendEntry(entry)
+        }
+      } while (repump && !closed && available)
+    } finally {
+      sending = false
+      watchOfflineSends()
+      if (![...entries.values()].some(pendingRetryable)) resetSendRetry()
+      settled()
+    }
   }
   const intentId = file => getEventHash({ kind: 0, pubkey: owner, created_at: 0, tags: [], content: `${file.peer}:${file.root}` })
   async function download (file, options = {}) {
@@ -359,10 +424,12 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     async setAvailable (value) {
       available = value === true
       stopOnlineRetry(); offlineSends.clear()
+      if (available) resetSendRetry()
+      else clearSendRetry()
       lifecycle++
       if (!available) { await messenger?.pause('signer'); return }
       await ready()
-      for (const entry of entries.values()) if (entry.retryable) entry.failed = false
+      for (const entry of entries.values()) if (pendingRetryable(entry)) entry.failed = false
       await messenger?.resume('storage')
       return schedule()
     },
@@ -382,7 +449,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       offlineSends.delete(id); watchOfflineSends()
       await ready()
       const entry = entries.get(id)
-      if (entry) { entry.failed = false; if (deniedPeers.delete(entry.peer)) await schedule(); return pump() }
+      if (entry) { entry.failed = false; resetSendRetry(); if (deniedPeers.delete(entry.peer)) await schedule(); return pump() }
     },
     async cancel (id) {
       cancelled.add(id)
@@ -396,6 +463,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     async close () {
       closed = true; available = false; lifecycle++
       stopOnlineRetry(); offlineSends.clear(); activeDownloads.clear(); pendingPriorityRanges.clear()
+      clearSendRetry()
       for (const controller of sendControllers.values()) controller.abort()
       await Promise.allSettled([configuring, initialized])
       await messenger?.pause('closed')

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/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]
+  }))
 }