libp2r2p 0.10.11 → 0.10.13

package/README.md

@@ -12,6 +12,35 @@ For remote-work scheduling, see [`libp2r2p/network`](network/README.md):
 `isOnline` probes connectivity and `onOnline` shares recovery monitoring,
 including retries when the browser omits its native `online` event.
 
+## Relay feed lifecycle
+
+`RelayPool.getEventsFeedGenerator(filter, relays, options)` yields events directly,
+including the existing `event.meta.relay` field. By default it combines an initial
+historical query with a live subscription. `live: false` selects history only;
+`filter.limit: 0` selects live only. `getLiveEventsGenerator` exposes the same
+lifecycle controls along with its existing `ready` and `readyRelays` properties.
+
+The returned iterator has a synchronous, idempotent `stopAndDrain()` method. It
+closes subscription input and cancels reconnections and outstanding historical
+queries, while retaining events already accepted by the library's receive
+callbacks. Continue consuming the iterator to obtain those events and observe
+completion. This includes initial history, buffered live events, and both history
+and live buffers from reconnect recovery. Calling it before the first `next()`
+prevents subscriptions from opening. No reception timestamp or new event metadata
+is added. Events rejected by ordinary filtering/deduplication remain excluded.
+
+Aborting `options.signal`, calling `return()` (including a `for await` break), or
+calling `throw()` cancels input and pending delivery instead. An event already
+delivered to the caller cannot be recalled. These operations also interrupt a
+drain. `stopAndDrain()` does not consume the iterator or return a completion
+promise: completion is the iterator's `{ done: true }` result.
+
+```js
+const stream = relayPool.getEventsFeedGenerator({ authors: [pubkey] }, [relay], { signal })
+// When this relay is removed, call stream.stopAndDrain() from the list handler.
+for await (const event of stream) await store(event)
+```
+
 ## Private Messenger
 
 The main API is `createPrivateMessenger` from `libp2r2p/private-messenger`.
@@ -364,6 +393,26 @@ Low-level relay sockets, subscriptions, message parsing, and serialization are
 internal implementation details; use `RelayPool` or the `relayPool` singleton
 from `libp2r2p/relay`.
 
+`getEvents` and `getEventsGenerator` accept `deduplicateAcrossRelays` (boolean,
+default `true`). With `false`, a matching event is delivered once per relay,
+while repeated IDs from the same relay remain suppressed. Each occurrence owns
+its `meta.relay`; callbacks still run immediately and deadlines, EOSE handling,
+and per-relay filter limits are unchanged. The callback/generator item remains
+`{ type: 'event', event, relay }`, and the completed query remains
+`{ result, errors, success }`. The option does not extend to the live or feed
+generators. Callers that need replication coverage can aggregate the returned
+copies by event ID; missing responses do not prove absence from a relay.
+
+Publication errors retain their existing `reason` objects and may expose
+`category`: `connection` (WebSocket establishment), `transport` (socket send or
+close), `relay` (an explicit negative `OK`), or `timeout` (missing confirmation).
+Native messages, codes, nested causes and aggregate errors remain available;
+WebSocket closure details use `closeCode`, `closeReason`, and `wasClean` rather
+than overwriting a native `code`. A timeout can retain a preceding socket error
+as its cause without claiming that the relay rejected the event. Authentication
+wrappers preserve this context. Local failures can remain uncategorized.
+Event metadata is internal and is removed by `sendEvent` before serialization.
+
 The same public subpath exports `getRelaysByPubkey(pubkeys)`, which discovers
 the latest NIP-65 relay list for every requested pubkey through `seedRelays`,
 normalizes and deduplicates its public relay URLs, and falls back to the first

package/package.json

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

package/relay/constants/index.js

@@ -1,7 +1,8 @@
 // Used only to discover users' NIP-65 relay lists (kind:10002).
 export const seedRelays = [
   'wss://relay.44billion.net',
-  'wss://purplepag.es',
+  // Disabled 2026-09-08: offline for some days
+  // 'wss://purplepag.es',
   'wss://user.kindpag.es',
   'wss://relay.nos.social',
   // Disabled 2026-08-05: accepted kind:10002 with OK but did not broadcast it
@@ -15,6 +16,7 @@ export const seedRelays = [
 export const freeRelays = [
   'wss://relay.44billion.net',
   'wss://nos.lol',
+  'wss://relay.dreamith.to',
   'wss://relay.primal.net'
 ]
 

package/relay/helpers/drainable-stream.js

@@ -0,0 +1,17 @@
+// Stopping closes network input but keeps accepted events available to next().
+// Returning/throwing, or aborting the caller signal, cancels consumption as well.
+export function drainableStream (create, options = {}) {
+  const cancel = new AbortController()
+  const stop = new AbortController()
+  const signal = options.signal ? AbortSignal.any([options.signal, cancel.signal]) : cancel.signal
+  const stopSignal = options._stopSignal ? AbortSignal.any([options._stopSignal, stop.signal]) : stop.signal
+  const stream = create({ ...options, signal, _stopSignal: stopSignal })
+  const returnStream = stream.return.bind(stream)
+  const throwStream = stream.throw.bind(stream)
+  Object.defineProperties(stream, {
+    stopAndDrain: { value: () => stop.abort() },
+    return: { value: value => { cancel.abort(); return returnStream(value) } },
+    throw: { value: error => { cancel.abort(); return throwStream(error) } }
+  })
+  return stream
+}

package/relay/helpers/error.js

@@ -0,0 +1,30 @@
+// Adds transport context without replacing native messages, codes or causes.
+export function categorizeRelayError (reason, category, fallback = 'RELAY_OPERATION_FAILED') {
+  const error = reason instanceof Error ? reason : new Error(String(reason || fallback))
+  try {
+    Object.defineProperty(error, 'category', { value: category, enumerable: true, configurable: true })
+    return error
+  } catch {
+    const wrapped = error instanceof AggregateError
+      ? new AggregateError(error.errors, error.message, { cause: error })
+      : new Error(error.message, { cause: error })
+    wrapped.name = error.name
+    if (error.code !== undefined) wrapped.code = error.code
+    wrapped.category = category
+    return wrapped
+  }
+}
+
+// A timeout indicates missing confirmation, even when a socket error preceded it.
+export function relayTimeoutError (message, cause) {
+  return categorizeRelayError(new Error(message, cause ? { cause } : undefined), 'timeout')
+}
+
+// WebSocket close codes are distinct from native system error codes.
+export function relayCloseError (event, category, cause) {
+  const error = new Error(event?.reason || 'CONNECTION_CLOSED', cause ? { cause } : undefined)
+  if (event?.code !== undefined) error.closeCode = event.code
+  if (event?.reason !== undefined) error.closeReason = event.reason
+  if (event?.wasClean !== undefined) error.wasClean = event.wasClean
+  return categorizeRelayError(error, category)
+}

package/relay/helpers/publish.js

@@ -1,7 +1,8 @@
 import { maybeUnref } from './timer.js'
+import { relayTimeoutError } from './error.js'
 
 function publishTimeoutError () {
-  return new Error('PUBLISH_TIMEOUT')
+  return relayTimeoutError('PUBLISH_TIMEOUT')
 }
 
 // Resolves once any relay accepts the event, all relays reject, an optional

package/relay/services/relay-connection.js

@@ -1,6 +1,7 @@
 import { isValidEvent } from '../../event/index.js'
 import { ValidationError } from '../../error/index.js'
 import { maybeUnref } from '../helpers/timer.js'
+import { categorizeRelayError, relayCloseError, relayTimeoutError } from '../helpers/error.js'
 
 const DEFAULT_CONNECT_TIMEOUT = 3000
 const DEFAULT_OPERATION_TIMEOUT = 30000
@@ -44,6 +45,7 @@ export class RelayConnection {
   #connectPromise = null
   #challenge = null
   #serial = 0
+  #lastTransportError = null
   #subscriptions = new Map()
   #publishes = new Map()
   #authentications = new Map()
@@ -60,14 +62,22 @@ export class RelayConnection {
     this.onauth = null
   }
 
+  // Exposes socket context to the pool's operation-wide publication deadline.
+  get lastTransportError () { return this.#lastTransportError }
+
   async connect ({ timeout = DEFAULT_CONNECT_TIMEOUT, signal } = {}) {
     if (this.ws?.readyState === 1) return
     if (this.#connectPromise) return await this.#connectPromise
     if (signal?.aborted) throw new Error('CONNECT_ABORTED')
-    if (typeof this.#WebSocket !== 'function') throw new Error('WEBSOCKET_UNAVAILABLE')
+    if (typeof this.#WebSocket !== 'function') throw categorizeRelayError(new Error('WEBSOCKET_UNAVAILABLE'), 'connection')
 
+    this.#lastTransportError = null
     this.#connectPromise = new Promise((resolve, reject) => {
-      const socket = new this.#WebSocket(this.url)
+      let socket
+      try { socket = new this.#WebSocket(this.url) } catch (error) {
+        reject(categorizeRelayError(error, 'connection'))
+        return
+      }
       this.ws = socket
       let settled = false
       const finish = (reason) => {
@@ -81,18 +91,21 @@ export class RelayConnection {
         } else resolve()
       }
       const onAbort = () => finish(new Error('CONNECT_ABORTED'))
-      const timer = timeout === null ? null : maybeUnref(setTimeout(() => finish(new Error('CONNECT_TIMEOUT')), timeout))
+      const timer = timeout === null ? null : maybeUnref(setTimeout(() => finish(relayTimeoutError('CONNECT_TIMEOUT')), timeout))
       signal?.addEventListener('abort', onAbort, { once: true })
 
       socket.onopen = () => finish()
       socket.onerror = event => {
-        const reason = errorFrom(event?.error, 'CONNECTION_ERROR')
+        const reason = categorizeRelayError(event?.error, settled ? 'transport' : 'connection', 'CONNECTION_ERROR')
         if (!settled) finish(reason)
-        else this.onerror?.(reason)
+        else {
+          this.#lastTransportError = reason
+          this.onerror?.(reason)
+        }
       }
       socket.onmessage = event => { this.#handleMessage(event).catch(reason => this.onerror?.(reason)) }
       socket.onclose = event => {
-        if (!settled) finish(new Error('CONNECTION_CLOSED'))
+        if (!settled) finish(relayCloseError(event, 'connection'))
         if (this.ws === socket) this.ws = null
         this.#handleClose(event)
       }
@@ -101,8 +114,11 @@ export class RelayConnection {
   }
 
   send (message) {
-    if (this.ws?.readyState !== 1) throw new Error('CONNECTION_CLOSED')
-    this.ws.send(message)
+    if (this.ws?.readyState !== 1) throw relayCloseError(null, 'transport', this.#lastTransportError)
+    try { this.ws.send(message) } catch (error) {
+      this.#lastTransportError = categorizeRelayError(error, 'transport')
+      throw this.#lastTransportError
+    }
   }
 
   subscribe (filters, handlers = {}) {
@@ -141,7 +157,7 @@ export class RelayConnection {
   #sendEventOperation (type, event, map, timeoutCode) {
     if (map.has(event.id)) return map.get(event.id).promise
     const deferred = Promise.withResolvers()
-    const timer = maybeUnref(setTimeout(() => this.#settleEvent(map, event.id, new Error(timeoutCode)), this.publishTimeout))
+    const timer = maybeUnref(setTimeout(() => this.#settleEvent(map, event.id, relayTimeoutError(timeoutCode, this.#lastTransportError)), this.publishTimeout))
     map.set(event.id, { ...deferred, timer, promise: deferred.promise })
     try { this.send(JSON.stringify([type, event])) } catch (error) {
       this.#settleEvent(map, event.id, error)
@@ -210,7 +226,7 @@ export class RelayConnection {
       return
     }
     if (data[0] === 'OK') {
-      const reason = data[2] === true ? null : errorFrom(data[3], 'EVENT_REJECTED')
+      const reason = data[2] === true ? null : categorizeRelayError(data[3], 'relay', 'EVENT_REJECTED')
       this.#settleEvent(this.#publishes, data[1], reason, data[3])
       this.#settleEvent(this.#authentications, data[1], reason, data[3])
       return
@@ -229,7 +245,7 @@ export class RelayConnection {
 
   #handleClose (event) {
     this.#challenge = null
-    const reason = errorFrom(event?.reason, 'CONNECTION_CLOSED')
+    const reason = relayCloseError(event, 'transport', this.#lastTransportError)
     for (const [id, subscription] of this.#subscriptions) {
       this.#subscriptions.delete(id)
       subscription.handlers.onclose?.(reason)
@@ -244,7 +260,7 @@ export class RelayConnection {
     const socket = this.ws
     this.ws = null
     this.#challenge = null
-    const reason = new Error('CONNECTION_CLOSED')
+    const reason = relayCloseError(null, 'transport', this.#lastTransportError)
     for (const [id, subscription] of this.#subscriptions) {
       this.#subscriptions.delete(id)
       subscription.handlers.onclose?.()

package/relay/services/relay-pool.js

@@ -1,7 +1,9 @@
 import { ValidationError } from '../../error/index.js'
 import { decodeHll, encodeHll, estimateHllCount, mergeHll } from '../helpers/hll.js'
 import { createPublishSettlements, firstFulfillment, publishSummary } from '../helpers/publish.js'
+import { drainableStream } from '../helpers/drainable-stream.js'
 import { maybeUnref } from '../helpers/timer.js'
+import { categorizeRelayError } from '../helpers/error.js'
 import { normalizeRelayUrl } from '../../url/index.js'
 import { RelayConnection } from './relay-connection.js'
 
@@ -102,6 +104,8 @@ class Nip42AuthenticationError extends Error {
   constructor (reason) {
     super(reason.message, { cause: reason })
     this.name = 'Nip42AuthenticationError'
+    if (reason.category) this.category = reason.category
+    if (reason.code !== undefined) this.code = reason.code
   }
 }
 
@@ -143,7 +147,7 @@ export class RelayPool {
       try {
         await relay.close()
       } catch {}
-      throw error
+      throw categorizeRelayError(error, error?.category ?? 'connection')
     }
 
     // Only reset idle timeout when no live subscriptions are holding this relay open.
@@ -335,8 +339,10 @@ export class RelayPool {
 
   // Collects a one-shot relay read. The first EOSE with events opens a short
   // grace window; null disables that window so callers wait for every relay or
-  // the operation deadline. Event ids are deduplicated across relay responses.
-  async getEvents (filter, relays, { timeout = 5000, timeoutAfterFirstEose = 500, callback, signal } = {}) {
+  // the operation deadline. Disabling cross-relay deduplication still suppresses
+  // repeated ids from the same relay; callbacks remain immediate in both modes.
+  async getEvents (filter, relays, { timeout = 5000, timeoutAfterFirstEose = 500, callback, signal, deduplicateAcrossRelays = true } = {}) {
+    if (typeof deduplicateAcrossRelays !== 'boolean') throw new ValidationError('INVALID_DEDUPLICATE_ACROSS_RELAYS')
     const urls = normalizedRelayUrls(relays)
     if (!urls.length) return { result: [], errors: [], success: false }
     if (signal?.aborted) throw new Error('Aborted')
@@ -346,7 +352,7 @@ export class RelayPool {
     const normalCloseUrls = new Set()
     const errors = []
     const events = []
-    const eventIds = new Set()
+    const eventIds = deduplicateAcrossRelays ? new Set() : null
     let completed = 0
     let isResolved = false
     let eoseTimer = null
@@ -411,6 +417,7 @@ export class RelayPool {
       if (timeout !== null) timeoutTimer = maybeUnref(setTimeout(timeoutPending, timeout))
 
       for (const url of urls) {
+        const seenIds = eventIds ?? new Set()
         this.#getRelay(url).then(relay => {
           if (isResolved || !pending.has(url)) return
           let hasEvents = false
@@ -432,10 +439,8 @@ export class RelayPool {
             onevent: (event) => {
               if (isResolved || !pending.has(url)) return
               hasEvents = true
-              // Keep filter-limit accounting per relay, but only expose one copy of
-              // a matching event when several relays return the same id.
-              if (!event?.id || !eventIds.has(event.id)) {
-                if (event?.id) eventIds.add(event.id)
+              if (!event?.id || !seenIds.has(event.id)) {
+                if (event?.id) seenIds.add(event.id)
                 event.meta = { relay: url }
                 events.push(event)
                 if (callback) callback({ type: 'event', event, relay: url })
@@ -476,7 +481,11 @@ export class RelayPool {
       p = Promise.withResolvers()
     }
 
-    const methodPromise = this.getEvents(filter, relays, { ...options, callback })
+    // A drain stops receive callbacks without aborting consumption of this queue.
+    const networkSignal = options._stopSignal
+      ? AbortSignal.any([options._stopSignal, ...(options.signal ? [options.signal] : [])])
+      : options.signal
+    const methodPromise = this.getEvents(filter, relays, { ...options, signal: networkSignal, callback })
       .catch(err => { if (err?.message !== 'Aborted') console.error('Error in getEvents:', err) })
       .finally(() => {
         isDone = true
@@ -485,6 +494,7 @@ export class RelayPool {
 
     // eslint-disable-next-line no-unmodified-loop-condition
     while (!isDone || queue.length > 0) {
+      if (options.signal?.aborted) break
       if (queue.length > 0) yield queue.shift()
       else await p.promise
     }
@@ -497,7 +507,7 @@ export class RelayPool {
   getLiveEventsGenerator (filter, relays, options = {}) {
     const ready = Promise.withResolvers()
     const readyRelays = new Set()
-    const stream = this.#getLiveEventsGenerator(filter, relays, options, { ready, readyRelays })
+    const stream = drainableStream(options => this.#getLiveEventsGenerator(filter, relays, options, { ready, readyRelays }), options)
 
     Object.defineProperties(stream, {
       ready: {
@@ -517,6 +527,7 @@ export class RelayPool {
   // suppressing already-live events from another relay.
   async * #getLiveEventsGenerator (filter, relays, {
     signal,
+    _stopSignal,
     timeoutAfterFirstEose = 500,
     timeoutForReconnectGap = 5000,
     timeoutAfterFirstReconnectGapEose = 500,
@@ -526,6 +537,8 @@ export class RelayPool {
     const queue = []
     let p = Promise.withResolvers()
     let isDone = false
+    let draining = false
+    const gapTasks = new Set()
     const liveSubs = new Map() // url → live sub
     const retryTimers = new Map()
     const initialPending = new Set(urls)
@@ -533,7 +546,7 @@ export class RelayPool {
     let readyTimer = null
     let isReady = false
 
-    // Internal abort controller to cancel any in-flight reconnect gap fills on teardown
+    // Stop recovery input on teardown, preserving its accepted history for a drain.
     const gapAc = new AbortController()
 
     // Strip time-range fields — we manage them internally
@@ -561,9 +574,11 @@ export class RelayPool {
       }))
     }
 
-    const teardown = () => {
-      if (isDone) return
+    const teardown = (drain = false) => {
+      if (isDone && (drain || !draining)) return
+      draining = drain
       isDone = true
+      if (!drain) queue.length = 0
       clearTimeout(untilTimer)
       finishReady()
       gapAc.abort()
@@ -574,8 +589,9 @@ export class RelayPool {
       p.resolve()
     }
 
-    const pushEvent = (event, url) => {
-      if (isDone || (event.id && seenIds.has(event.id))) return
+    const pushEvent = (event, url, accepted = false) => {
+      // Recovery queues accepted these events before input was stopped.
+      if ((isDone && !(draining && accepted)) || (event.id && seenIds.has(event.id))) return
       if (event.id) {
         if (seenIds.size >= 500) seenIds.delete(seenIds.values().next().value) // evict oldest
         seenIds.add(event.id)
@@ -587,11 +603,14 @@ export class RelayPool {
       p = Promise.withResolvers()
     }
 
-    if (signal?.aborted) {
+    if (signal?.aborted || _stopSignal?.aborted) {
       finishReady()
       return
     }
-    signal?.addEventListener('abort', teardown, { once: true })
+    const abort = () => teardown()
+    const stop = () => teardown(true)
+    signal?.addEventListener('abort', abort, { once: true })
+    _stopSignal?.addEventListener('abort', stop, { once: true })
 
     const maybeFinishInitialReady = () => {
       if (initialPending.size === 0) finishReady()
@@ -626,7 +645,7 @@ export class RelayPool {
     // Schedule teardown when the wall clock reaches filter.until
     if (filterUntil !== null) {
       const msUntil = filterUntil * 1000 - Date.now()
-      untilTimer = maybeUnref(setTimeout(teardown, Math.max(0, msUntil)))
+      untilTimer = maybeUnref(setTimeout(() => teardown(true), Math.max(0, msUntil)))
     }
 
     // Runs a reconnect gap fill for a single relay and returns a promise that resolves
@@ -637,11 +656,12 @@ export class RelayPool {
       const gapGen = _gapEventsGenerator(gapFilter, [url], {
         timeout: timeoutForReconnectGap,
         timeoutAfterFirstEose: timeoutAfterFirstReconnectGapEose,
-        signal: gapAc.signal
+        signal,
+        _stopSignal: gapAc.signal
       })
       return (async () => {
         for await (const item of gapGen) {
-          if (item?.type === 'event') pushEvent(item.event, url)
+          if (item?.type === 'event') pushEvent(item.event, url, true)
         }
       })().catch(err => {
         if (!isDone) console.error(`Reconnect gap fill error for ${url}:`, err)
@@ -669,7 +689,7 @@ export class RelayPool {
           onevent: (event) => {
             // A limit:0 relay may still send retained events before EOSE. Do not
             // expose them from a strictly-live stream.
-            if (!liveEose) return
+            if (isDone || liveSubs.get(url) !== liveSub || !liveEose) return
             if (liveBuffer) liveBuffer.push(event)
             else pushEvent(event, url)
           },
@@ -696,12 +716,14 @@ export class RelayPool {
         liveSubs.set(url, liveSub)
 
         if (gapSince !== null && gapSince > 0) {
-          runReconnectGapFill(url, gapSince, now).then(() => {
-            if (isDone) return
+          const task = runReconnectGapFill(url, gapSince, now).finally(() => {
             const buf = liveBuffer
             liveBuffer = null
-            for (const event of buf) pushEvent(event, url)
+            for (const event of buf) pushEvent(event, url, true)
+            gapTasks.delete(task)
+            p.resolve()
           })
+          gapTasks.add(task)
         }
       }).catch(err => {
         readyRelays.delete(url)
@@ -725,12 +747,14 @@ export class RelayPool {
 
     try {
       // eslint-disable-next-line no-unmodified-loop-condition
-      while (!isDone || queue.length > 0) {
+      while (!isDone || (draining && gapTasks.size > 0) || queue.length > 0) {
+        if (signal?.aborted) break
         if (queue.length > 0) yield queue.shift()
-        else await p.promise
+        else { await p.promise; p = Promise.withResolvers() }
       }
     } finally {
-      signal?.removeEventListener('abort', teardown)
+      signal?.removeEventListener('abort', abort)
+      _stopSignal?.removeEventListener('abort', stop)
       for (const url of urls) this.#decrementLiveSub(url)
       teardown()
     }
@@ -748,17 +772,24 @@ export class RelayPool {
   //   relays when null.
   //
   // All underlying generators are injectable for testing.
-  async * getEventsFeedGenerator (filter, relays, {
+  getEventsFeedGenerator (filter, relays, options = {}) {
+    return drainableStream(options => this.#getEventsFeedGenerator(filter, relays, options), options)
+  }
+
+  async * #getEventsFeedGenerator (filter, relays, {
     signal,
+    _stopSignal,
     live = true,
     timeout = 5000,
     timeoutAfterFirstEose = 500,
     _liveGenerator = (...args) => this.getLiveEventsGenerator(...args),
     _eventsGenerator = (...args) => this.getEventsGenerator(...args)
   } = {}) {
+    if (signal.aborted || _stopSignal.aborted) return
     if (!live) {
-      const gen = _eventsGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal })
+      const gen = _eventsGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal, _stopSignal })
       for await (const item of gen) {
+        if (signal.aborted) return
         if (item?.type === 'event') yield item.event
       }
       return
@@ -766,7 +797,8 @@ export class RelayPool {
 
     // limit:0 means "no stored events, live only" — skip the initial fetch.
     if (filter.limit === 0) {
-      for await (const event of _liveGenerator(filter, relays, { signal })) {
+      for await (const event of _liveGenerator(filter, relays, { signal, _stopSignal })) {
+        if (signal.aborted) return
         yield event
       }
       return
@@ -776,7 +808,7 @@ export class RelayPool {
     // buffering incoming events before we query stored ones.
     // Relays always send stored matching events before EOSE (unless limit:0),
     // so the initial fetch + buffering is always needed.
-    const liveGen = _liveGenerator(filter, relays, { signal })
+    const liveGen = _liveGenerator(filter, relays, { signal, _stopSignal })
     const liveBuffer = []
     let liveDone = false
     let liveWake = Promise.withResolvers()
@@ -784,6 +816,7 @@ export class RelayPool {
     const bgLoop = (async () => {
       try {
         for await (const event of liveGen) {
+          if (signal.aborted) break
           liveBuffer.push(event)
           liveWake.resolve()
           liveWake = Promise.withResolvers()
@@ -796,10 +829,11 @@ export class RelayPool {
 
     try {
       // Yield stored events from the initial one-shot fetch
-      const fetchGen = _eventsGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal })
+      const fetchGen = _eventsGenerator(filter, relays, { timeout, timeoutAfterFirstEose, signal, _stopSignal })
 
       const seenIds = new Set()
       for await (const item of fetchGen) {
+        if (signal.aborted) return
         if (item?.type === 'event' && !seenIds.has(item.event.id)) {
           seenIds.add(item.event.id)
           yield item.event
@@ -809,6 +843,7 @@ export class RelayPool {
       // Flush buffered live events that arrived during the initial fetch, deduping
       // against stored ones (overlap is possible around the fetch's until boundary)
       while (liveBuffer.length > 0) {
+        if (signal.aborted) return
         const event = liveBuffer.shift()
         if (!seenIds.has(event.id)) {
           seenIds.add(event.id)
@@ -819,11 +854,14 @@ export class RelayPool {
       // Yield subsequent live events directly — no more overlap with stored events
       // eslint-disable-next-line no-unmodified-loop-condition
       while (!liveDone || liveBuffer.length > 0) {
-        while (liveBuffer.length > 0) yield liveBuffer.shift()
+        while (liveBuffer.length > 0) {
+          if (signal.aborted) return
+          yield liveBuffer.shift()
+        }
         if (!liveDone) await liveWake.promise
       }
     } finally {
-      liveGen.return()
+      await liveGen.return()
       await bgLoop
     }
   }
@@ -859,6 +897,10 @@ export class RelayPool {
     // Starts before connection work so every relay shares one real deadline.
     const settlement = createPublishSettlements(sendPromises, timeout, {
       onSettled: (settlement, index) => {
+        if (settlement.reason?.category === 'timeout' && !settlement.reason.cause) {
+          const relay = this.#relays.get(normalizeRelayUrl(urls[index]))
+          if (relay?.lastTransportError) settlement.reason.cause = relay.lastTransportError
+        }
         notifyRelayResult(onRelayResult, relayResultForSettlement(urls[index], settlement))
       }
     })