libp2r2p 0.11.15 → 0.11.17

package/README.md

@@ -936,9 +936,22 @@ also admits relay policy refusals (`blocked:`, `restricted:`, `auth-required:`,
 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.
+`parseRelayRetryAdvice(reason, extra, { now = Date.now() })`, exported by
+`libp2r2p/relay`, returns `{ retryAt, retryAfterMs? }` or `null`. It only interprets
+leading `rate-limited:` refusals. Optional `retry_at` is a Unix timestamp in
+seconds (fractions allowed), converted to milliseconds. Finite positive absolute
+advice takes precedence over `retry_after`, including when already expired;
+expired advice does not restart a relative wait. Future waits are capped at five
+minutes from processing. Missing/invalid absolute advice falls back to finite
+positive relative seconds, capped at 300. A valid relative value is retained as
+`retryAfterMs` even when the absolute deadline wins. Schedulers wait until
+max(local backoff deadline, retryAt), never sum the two or renew the deadline on
+online notifications.
+
+The optional Nostr extension works with older relays that only send
+`retry_after` and older consumers that ignore `retry_at`. Neither field supplies
+provenance or retry eligibility: `local`, `origin`, `retryable`, category and code
+claims in extras are ignored. Native messages, causes and codes remain intact.
 
 ## Binary encodings
 
@@ -1059,7 +1072,7 @@ user-facing send error.
 
 ### Relay backpressure and bounded synchronization (0.11.7)
 
-Optional numeric `retry_after` seconds on relay `CLOSED` and rejected `OK`
+Optional `retry_at` Unix seconds or numeric `retry_after` seconds on relay `CLOSED` and rejected `OK`
 responses are preserved as `retryAfterMs` and `retryAt` on native relay errors.
 Only `rate-limited:` responses apply this advice; invalid values are ignored
 and delays are capped at five minutes. New operations on that connection wait
@@ -1113,3 +1126,10 @@ are unchanged; newer live arrivals cannot erase a pending interval.
 count/bytes, incoming bytes, limits and oldest queued age. Queue bytes are UTF-8
 serialized volume, not heap use. Diagnostics never retain event contents or
 filters. Existing 1,000-item / 8-MiB live limits are unchanged.
+
+Private messenger status (`readStatus`, `onStateChanged`) exposes pause reasons
+without events or credentials. Sessions recover owned network/storage failures
+and wake pending sends on release rather than repeatedly publishing while paused.
+Custom session factories must expose `readStatus()` and deliver the initial and
+subsequent `onStateChanged` snapshots; missing observation is rejected instead of
+using polling compatibility. See [session lifecycle](private-messenger/session/README.md).

package/package.json

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

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

@@ -0,0 +1,80 @@
+// Local persistence is not a relay failure. Retry operational storage failures,
+// but leave validation/permission failures to their owner or an explicit retry.
+export const isRecoverableStorageFailure = error => error != null && typeof error === 'object' && error?.name !== 'ValidationError' && error?.category !== 'validation' &&
+  !['SecurityError', 'NotAllowedError', 'TypeError', 'RangeError', 'SyntaxError', 'DataError', 'DataCloneError'].includes(error?.name) &&
+  !/DENIED|PERMISSION|REVOKED|READ_ONLY|INVALID|NOT_IN_PERSONA/.test(`${error?.code || ''} ${error?.name || ''} ${error?.message || ''}`)
+
+// One cancellable job per cause. Waiting offline does not spend a backoff step.
+export function createPauseRecovery ({ attempt, online, onOnline, retryable, onError, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout, random = Math.random }) {
+  let current
+  function stop () {
+    const job = current
+    current = null
+    if (!job) return
+    job.controller.abort()
+    if (job.timer != null) clearTimer(job.timer)
+    job.stopOnline?.()
+  }
+  function start ({ immediate = false, retryAt = 0 } = {}) {
+    const advice = Number.isFinite(retryAt) && retryAt > 0 ? retryAt : 0
+    if (current) {
+      if (advice > current.retryAt) { current.retryAt = advice; current.wake?.() }
+      return immediate ? current.retry?.() : current.work
+    }
+    const job = { controller: new AbortController(), delay: 1000, retryAt: advice, timer: null, nextAt: 0, wake: null, retry: null, stopOnline: null, work: null }
+    current = job
+    const active = () => current === job && !job.controller.signal.aborted
+    const schedule = delay => {
+      if (!active()) return
+      job.nextAt = Math.max(now() + delay, job.retryAt)
+      job.timer = setTimer(() => { job.timer = null; return run() }, Math.max(job.nextAt - now(), 0))
+      job.timer?.unref?.()
+    }
+    const run = () => {
+      if (!active() || job.work) return job.work
+      const work = (async () => {
+        if (online && !await online({ signal: job.controller.signal })) {
+          if (!active()) return
+          job.stopOnline = onOnline(() => {
+            if (!active()) return
+            job.stopOnline?.(); job.stopOnline = null
+            schedule(0)
+          })
+          return
+        }
+        if (!active()) return
+        try {
+          await attempt(job.controller.signal)
+          if (active()) stop()
+        } catch (error) {
+          if (!active()) return
+          onError(error)
+          if (!retryable(error)) { stop(); return }
+          job.retryAt = Math.max(job.retryAt, Number.isFinite(error?.retryAt) ? error.retryAt : 0)
+          schedule(Math.min(30000, job.delay * (0.8 + random() * 0.4)))
+          job.delay = Math.min(30000, job.delay * 2)
+        }
+      })().catch(error => { if (active()) { onError(error); stop() } }).finally(() => { if (job.work === work) job.work = null })
+      job.work = work
+      return work
+    }
+    job.wake = () => {
+      if (!active() || job.work) return job.work
+      if (job.timer != null) clearTimer(job.timer)
+      job.timer = null
+      if (job.nextAt > now()) { schedule(job.nextAt - now()); return }
+      return run()
+    }
+    job.retry = () => {
+      if (!active() || job.work) return job.work
+      if (job.timer != null) clearTimer(job.timer)
+      job.timer = null
+      if (job.retryAt > now()) { schedule(job.retryAt - now()); return }
+      return run()
+    }
+    if (immediate) return run()
+    schedule(1000)
+    job.delay = 2000
+  }
+  return { start, stop, wake: () => current?.wake?.() }
+}

package/private-messenger/index.js

@@ -45,7 +45,9 @@
 import { createAbortableSemaphore } from '../helpers/abortable-semaphore.js'
 import { mergeRanges, subtractRanges, intersectRanges } from '../helpers/ranges.js'
 import * as privateMessage from '../private-message/index.js'
-import { isOnline } from '../network/index.js'
+import { isOnline, onOnline } from '../network/index.js'
+import { isRetryableRelayFailure, isReplaceableRelayFailure } from '../relay/index.js'
+import { createPauseRecovery, isRecoverableStorageFailure } from './helpers/pause-recovery.js'
 import { createSendRelayRouting, normalizeFallbackRelays } from './helpers/send-routing.js'
 import { incompleteFetchError } from '../private-channel/helpers/fetch-error.js'
 import { recoveryRetryDelay, isPermanentRecoveryError } from './helpers/recovery-retry.js'
@@ -231,6 +233,7 @@ export class PrivateMessenger {
     useContentKeys = true,
     onContentKeyChange,
     onMessageQueued,
+    onStateChanged,
     onDebug,
     onError = defaultOnError,
     _privateMessage = privateMessage,
@@ -239,6 +242,8 @@ export class PrivateMessenger {
     _pickRelaysForPubkeys = pickRelaysForPubkeys,
     _subscribeRelayListUpdates = subscribeRelayListUpdates,
     _isOnline = isOnline,
+    _onOnline = onOnline,
+    _random = Math.random,
     _setTimeout = globalThis.setTimeout.bind(globalThis),
     _clearTimeout = globalThis.clearTimeout.bind(globalThis),
     _setInterval = globalThis.setInterval.bind(globalThis),
@@ -247,6 +252,7 @@ export class PrivateMessenger {
     _storageClearInterval = globalThis.clearInterval.bind(globalThis),
     _BroadcastChannel = _indexedDB === globalThis.indexedDB ? globalThis.BroadcastChannel : undefined
   } = {}) {
+    if (onStateChanged != null && typeof onStateChanged !== 'function') throw new ValidationError('INVALID_ON_STATE_CHANGED')
     this.fallbackRelays = normalizeFallbackRelays(fallbackRelays)
     this.offlineRecoverySeconds = normalizeOfflineRecoverySeconds(offlineRecoverySeconds)
     this.staleChannelSeconds = normalizeStaleChannelSeconds(staleChannelSeconds)
@@ -277,6 +283,16 @@ export class PrivateMessenger {
     this._indexedDB = _indexedDB
     this.useContentKeys = useContentKeys
     this.onContentKeyChange = onContentKeyChange
+    this.onStateChanged = onStateChanged
+    this.statusFingerprint = null
+    this.automaticPauses = new Set()
+    this.pendingStorageWrites = new Map()
+    this.pauseRecoveries = new Map()
+    this.watchRecoveries = new Map()
+    this.pauseOnlineWork = null
+    this.pauseOnlineController = null
+    this._onOnline = _onOnline
+    this._random = _random
     this.onMessageQueued = onMessageQueued
     this.onDebug = onDebug
     this.onError = onError
@@ -351,6 +367,7 @@ export class PrivateMessenger {
     this.closePromise = null
     this.initSettledPromise = null
     this.initialized = false
+    this.notifyStatus()
   }
 
   async init ({ userSigner, contentKeySigner, nymSigner, channels = [], relays = [], mode = 'leecher' }) {
@@ -663,6 +680,7 @@ export class PrivateMessenger {
       relays = [],
       mode = 'leecher'
     } = options
+    const readerIdentityChanged = userSigner !== this.userSigner || contentKeySigner !== this.contentKeySigner || nymSigner !== this.nymSigner
     const updatesStalePolicy = Object.hasOwn(options, 'staleChannelSeconds')
     const updatesIdentityPolicy = Object.hasOwn(options, 'identityStorageRetentionSeconds')
     let nextStaleChannelSeconds = updatesStalePolicy
@@ -683,7 +701,12 @@ export class PrivateMessenger {
     const nextChannels = await this.normalizeChannels(channels, { relays, mode })
     this.assertOpen()
     const nextPubkeys = new Set(nextChannels.map(channel => channel.pubkey))
-    const watchPubkeys = [...nextPubkeys].filter(pubkey => !this.channels.has(pubkey) || this.desiredChannels.has(pubkey))
+    const changedChannel = channel => {
+      const previous = this.channels.get(channel.pubkey)
+      return !previous || ['signer', 'readerSigner', 'readerPubkey', 'nymSigner', 'mode', 'usesNip65WatchRelays', 'offlineRecoverySeconds', 'autoDeletionCapability'].some(key => previous[key] !== channel[key]) ||
+        ['relays', 'sendRelays', 'seeders'].some(key => JSON.stringify(previous[key]) !== JSON.stringify(channel[key]))
+    }
+    const watchPubkeys = nextChannels.filter(channel => !this.channels.has(channel.pubkey) || (this.desiredChannels.has(channel.pubkey) && (readerIdentityChanged || Object.hasOwn(options, 'staleChannelSeconds') || Object.hasOwn(options, 'identityStorageRetentionSeconds') || changedChannel(channel) || !this.stopByChannel.has(channel.pubkey)))).map(channel => channel.pubkey)
     const removedPubkeys = [...this.channels.keys()].filter(pubkey => !nextPubkeys.has(pubkey))
     const updatesStoragePolicy = updatesStalePolicy || updatesIdentityPolicy
 
@@ -1118,31 +1141,53 @@ export class PrivateMessenger {
       // Neither a crash nor a newly received message may erase the initial scan.
       this.recordRecoveryWindow(pubkey)
       await this.flushStateWrites()
-      const watchRelays = await this.resolveWatchRelays(channel)
-      this.assertOpen()
-      if (this.pauseReasons.size || !this.desiredChannels.has(pubkey) || revision !== (this.watchRevisionByChannel.get(pubkey) || 0)) continue
-      const stop = await this._privateMessage.watch({
-        channels: [pubkey],
-        relays: watchRelays,
-        receiverSigner: this.userSigner,
-        iykcSigner: this.contentKeySigner,
-        privateChannelSigner: channel.signer,
-        privateChannelReaderSigner: channel.readerSigner,
-        privateChannelReaderPubkey: channel.readerPubkey,
-        mode: channel.mode,
-        onAsk: message => this.receive(pubkey, () => this.handleAsk(pubkey, message), message),
-        onReply: message => this.receive(pubkey, () => this.handleReply(pubkey, message), message),
-        onTell: message => this.receive(pubkey, () => this.handleTell(pubkey, message), message),
-        onYell: message => this.receive(pubkey, () => this.handleYell(pubkey, message), message),
-        onNym: message => this.receive(pubkey, () => this.handleNym(pubkey, message), message),
-        onMessage: message => this.receive(pubkey, () => this.handleMessage(pubkey, message), message),
-        onSeed: seed => this.receive(pubkey, () => this.enqueueSeed(pubkey, seed), seed),
-        onContentKeyUsage: usage => this.handleContentKeyUsage(pubkey, usage),
-        receivedChunkTtlMs: this.receivedChunkTtlMsFor(channel),
-        receivedChunkIndexedDB: this._indexedDB,
-        onSubscriptionState: state => this.handleSubscriptionState(pubkey, state),
-        onError: err => this.onError?.(err)
-      })
+      let stop; let watchRelays
+      try {
+        watchRelays = await this.resolveWatchRelays(channel)
+        this.assertOpen()
+        if (this.pauseReasons.size || !this.desiredChannels.has(pubkey) || revision !== (this.watchRevisionByChannel.get(pubkey) || 0)) continue
+        stop = await this._privateMessage.watch({
+          channels: [pubkey],
+          relays: watchRelays,
+          receiverSigner: this.userSigner,
+          iykcSigner: this.contentKeySigner,
+          privateChannelSigner: channel.signer,
+          privateChannelReaderSigner: channel.readerSigner,
+          privateChannelReaderPubkey: channel.readerPubkey,
+          mode: channel.mode,
+          onAsk: message => this.receive(pubkey, () => this.handleAsk(pubkey, message), message),
+          onReply: message => this.receive(pubkey, () => this.handleReply(pubkey, message), message),
+          onTell: message => this.receive(pubkey, () => this.handleTell(pubkey, message), message),
+          onYell: message => this.receive(pubkey, () => this.handleYell(pubkey, message), message),
+          onNym: message => this.receive(pubkey, () => this.handleNym(pubkey, message), message),
+          onMessage: message => this.receive(pubkey, () => this.handleMessage(pubkey, message), message),
+          onSeed: seed => this.receive(pubkey, () => this.enqueueSeed(pubkey, seed), seed),
+          onContentKeyUsage: usage => this.handleContentKeyUsage(pubkey, usage),
+          receivedChunkTtlMs: this.receivedChunkTtlMsFor(channel),
+          receivedChunkIndexedDB: this._indexedDB,
+          onSubscriptionState: state => this.handleSubscriptionState(pubkey, state),
+          onError: err => this.onError?.(err)
+        })
+      } catch (error) {
+        const transient = isRetryableRelayFailure(error)
+        const remote = error?.name !== 'Nip42AuthenticationError' && (error?.category === 'relay' || isReplaceableRelayFailure(error))
+        if (!transient && !remote) throw error
+        this.onError?.(error)
+        if (!transient) continue
+        if (!this.watchRecoveries.has(pubkey)) {
+          const task = this.recoveryTask(async signal => {
+            signal.throwIfAborted()
+            if (this.closePromise || this.pauseReasons.size || !this.desiredChannels.has(pubkey)) return
+            await this.watch([pubkey])
+            if (!this.stopByChannel.has(pubkey)) throw error
+          }, { network: true, retryable: isRetryableRelayFailure })
+          this.watchRecoveries.set(pubkey, task)
+        }
+        this.watchRecoveries.get(pubkey).start({ retryAt: error.retryAt })
+        continue
+      }
+      this.watchRecoveries.get(pubkey)?.stop()
+      this.watchRecoveries.delete(pubkey)
       if (this.closePromise || this.pauseReasons.size || !this.desiredChannels.has(pubkey) || revision !== (this.watchRevisionByChannel.get(pubkey) || 0)) {
         await stop?.()
         this.assertOpen()
@@ -1182,6 +1227,8 @@ export class PrivateMessenger {
       if (!interrupted) { interrupted = new Map(); this.liveInterruptions.set(pubkey, interrupted) }
       const start = Math.min(interrupted.get(relay) ?? Infinity, since)
       interrupted.set(relay, start)
+      this.watchRecoveries.get(pubkey)?.stop()
+      this.watchRecoveries.delete(pubkey)
       this.cancelReloadGap(pubkey)
       for (const controller of this.recoveryControllers) {
         if (controller.channelPubkey === pubkey) { controller.liveInterrupted = true; controller.abort() }
@@ -1620,6 +1667,8 @@ export class PrivateMessenger {
     const pubkeys = channels ? uniq(Array.isArray(channels) ? channels : [channels]) : [...this.desiredChannels]
     for (const extension of this.extensions) extension.unwatch?.(pubkeys)
     for (const pubkey of pubkeys) this.desiredChannels.delete(pubkey)
+    for (const [key, pending] of this.pendingStorageWrites) if (pubkeys.includes(pending.record.channelPubkey)) this.pendingStorageWrites.delete(key)
+    this.syncPauseRecovery()
     for (const pubkey of pubkeys) this.dropRecoveryState(pubkey)
     this.recordInterruption(pubkeys)
     for (const controller of this.recoveryControllers) {
@@ -1628,10 +1677,110 @@ export class PrivateMessenger {
     return Promise.all([this.stopWatches(pubkeys), this.flushStateWrites()])
   }
 
+  readStatus () {
+    return { closed: Boolean(this.closePromise), paused: this.pauseReasons.size > 0, pauseReasons: [...this.pauseReasons].sort() }
+  }
+
+  notifyStatus () {
+    const status = this.readStatus()
+    const fingerprint = JSON.stringify(status)
+    if (fingerprint !== this.statusFingerprint) {
+      this.statusFingerprint = fingerprint
+      try { this.onStateChanged?.(status) } catch (error) { this.onError?.(error) }
+    }
+    this.syncPauseRecovery()
+  }
+
+  pausedError () {
+    return Object.assign(new Error('PRIVATE_MESSENGER_PAUSED'), { pauseReasons: this.readStatus().pauseReasons })
+  }
+
+  recoveryTask (attempt, { network = false, retryable = isRecoverableStorageFailure } = {}) {
+    return createPauseRecovery({
+      attempt, retryable, onError: error => this.onError?.(error),
+      ...(network ? { online: () => this.checkPauseOnline(), onOnline: this._onOnline } : {}),
+      setTimer: this._setTimeout, clearTimer: this._clearTimeout, random: this._random
+    })
+  }
+
+  checkPauseOnline () {
+    if (!this.pauseOnlineWork) {
+      const controller = new AbortController()
+      this.pauseOnlineController = controller
+      const work = Promise.resolve().then(() => this._isOnline({ signal: controller.signal })).finally(() => {
+        if (this.pauseOnlineWork === work) { this.pauseOnlineWork = null; this.pauseOnlineController = null }
+      })
+      this.pauseOnlineWork = work
+    }
+    return this.pauseOnlineWork
+  }
+
+  syncPauseRecovery () {
+    if (!this.pauseRecoveries) return
+    const blocked = this.closePromise || !this.desiredChannels.size ||
+      [...this.pauseReasons].some(reason => !['network', 'storage', 'capacity', 'session-storage'].includes(reason))
+    for (const [reason, task] of this.pauseRecoveries) {
+      if (blocked || !this.automaticPauses.has(reason) || !this.pauseReasons.has(reason)) task.stop()
+    }
+    if (blocked) {
+      this.pauseOnlineController?.abort()
+      this.pauseOnlineWork = null; this.pauseOnlineController = null
+      return
+    }
+    for (const reason of this.automaticPauses) {
+      if (!this.pauseReasons.has(reason)) continue
+      let task = this.pauseRecoveries.get(reason)
+      if (!task) {
+        task = this.recoveryTask(async signal => {
+          if (reason === 'storage') await this.retryStorageWrites(signal)
+          await this.flushStateWrites()
+          signal.throwIfAborted()
+          await this.resume(reason)
+        }, {
+          network: reason === 'network', retryable: error => {
+            const retry = reason === 'network' ? isRetryableRelayFailure(error) : isRecoverableStorageFailure(error)
+            if (!retry) this.automaticPauses.delete(reason)
+            return retry
+          }
+        })
+        this.pauseRecoveries.set(reason, task)
+      }
+      task.start()
+    }
+  }
+
+  async retryStorageWrites (signal) {
+    for (const [key, pending] of this.pendingStorageWrites) {
+      signal.throwIfAborted()
+      const pubkey = pending.record.channelPubkey
+      if (!this.channels.has(pubkey) || !this.desiredChannels.has(pubkey)) { this.pendingStorageWrites.delete(key); continue }
+      try {
+        if (!pending.dedupeKey || !await this.queue.someBy('byChannelTypeEventId', pending.dedupeKey)) await this.queue.enqueue(pending.record)
+      } catch (error) { if (error?.name !== 'ConstraintError') throw error }
+      signal.throwIfAborted()
+      this.pendingStorageWrites.delete(key)
+      this.markSeen(pubkey, pending.at || nowSeconds())
+      this.wakeDeliveries()
+      this.onMessageQueued?.()
+    }
+  }
+
+  pauseInternally (reason) {
+    if (!this.pauseReasons.has(reason) || this.automaticPauses.has(reason)) this.automaticPauses.add(reason)
+    return this.applyPause(reason)
+  }
+
   pause (reason) {
+    // An explicit caller takes ownership, even if this cause already exists.
+    this.automaticPauses.delete(reason)
+    return this.applyPause(reason)
+  }
+
+  applyPause (reason) {
     if (typeof reason !== 'string' || !reason.trim()) throw new ValidationError('PAUSE_REASON_REQUIRED')
     this.assertOpen()
     this.pauseReasons.add(reason)
+    this.notifyStatus()
     for (const extension of this.extensions) extension.pause?.()
     this.recordInterruption(this.desiredChannels)
     for (const controller of this.recoveryControllers) controller.abort()
@@ -1641,7 +1790,14 @@ export class PrivateMessenger {
   async resume (reason) {
     if (typeof reason !== 'string' || !reason.trim()) throw new ValidationError('PAUSE_REASON_REQUIRED')
     this.assertOpen()
+    // Repair durable state before announcing that publication can resume.
+    if (reason === 'storage' && this.pendingStorageWrites.size) await this.retryStorageWrites(this.sendRoutingLifetime.signal)
+    await this.flushStateWrites()
+    this.assertOpen()
+    const wasAutomatic = this.automaticPauses.has(reason)
     const removed = this.pauseReasons.delete(reason)
+    this.automaticPauses.delete(reason)
+    this.notifyStatus()
     if (reason === 'capacity' && removed) {
       clearInterval(this.capacityTimer)
       this.capacityTimer = null
@@ -1664,7 +1820,10 @@ export class PrivateMessenger {
     })()
     this.resumeWork = work
     try { await work } catch (err) {
-      if (!this.closePromise) await this.pause(reason)
+      if (!this.closePromise) {
+        if (wasAutomatic && (reason === 'network' ? isRetryableRelayFailure(err) : isRecoverableStorageFailure(err))) this.automaticPauses.add(reason)
+        await this.applyPause(reason)
+      }
       throw err
     } finally { if (this.resumeWork === work) this.resumeWork = null }
   }
@@ -1677,7 +1836,7 @@ export class PrivateMessenger {
     return this.queueIncoming(async () => {
       if (this.pauseReasons.size || !this.desiredChannels.has(pubkey)) {
         this.recordInterruption([pubkey], messageTime(message))
-        throw new Error('PRIVATE_MESSENGER_PAUSED')
+        throw this.pausedError()
       }
       return operation()
     })
@@ -1790,19 +1949,20 @@ export class PrivateMessenger {
       this.debug('dedupe', debugMessageInfo(type, channelPubkey, message))
       return
     }
+    const record = {
+      type,
+      channelPubkey,
+      receivedAt: nowSeconds(),
+      event: message.event,
+      ...info,
+      payload: message.payload,
+      question: message.question || null,
+      questionId: message.questionId || null,
+      outer: message.outer || null,
+      meta: message.meta || null
+    }
     try {
-      await this.queue.enqueue({
-        type,
-        channelPubkey,
-        receivedAt: nowSeconds(),
-        event: message.event,
-        ...info,
-        payload: message.payload,
-        question: message.question || null,
-        questionId: message.questionId || null,
-        outer: message.outer || null,
-        meta: message.meta || null
-      })
+      await this.queue.enqueue(record)
     } catch (err) {
       // The unique index closes the small cross-instance race after `someBy`.
       if (dedupeKey && err?.name === 'ConstraintError') {
@@ -1813,7 +1973,8 @@ export class PrivateMessenger {
       this.recordInterruption([channelPubkey], message.outer?.created_at || message.event?.created_at || nowSeconds())
       // Do not await stop from inside its own transport callback.
       const atCapacity = err.message === 'QUEUE_CAPACITY_EXCEEDED'
-      this.pause(atCapacity ? 'capacity' : 'storage').catch(error => this.onError?.(error))
+      if (!atCapacity && isRecoverableStorageFailure(err)) this.pendingStorageWrites.set(JSON.stringify(dedupeKey || [channelPubkey, type]), { record, dedupeKey, at: message.outer?.created_at || message.event?.created_at })
+      ;(atCapacity ? this.pause('capacity') : isRecoverableStorageFailure(err) ? this.pauseInternally('storage') : this.pause('storage')).catch(error => this.onError?.(error))
       if (atCapacity) {
         this.capacityRequiredBytes = Math.max(this.capacityRequiredBytes, err.requiredBytes || 0)
         if (!this.capacityTimer) {
@@ -2247,7 +2408,7 @@ export class PrivateMessenger {
 
   requireWritableChannel (pubkey) {
     this.assertOpen()
-    if (this.pauseReasons.size) throw new Error('PRIVATE_MESSENGER_PAUSED')
+    if (this.pauseReasons.size) throw this.pausedError()
     const channel = this.requireChannel(pubkey)
     if (!channel.signer) throw new ValidationError('PRIVATE_CHANNEL_WRITER_REQUIRED')
     return channel
@@ -2373,12 +2534,12 @@ export class PrivateMessenger {
   ensureNetworkWatchers () {
     if (typeof window === 'undefined') return
     if (!this.stopOffline) {
-      const offline = () => { this.pause('network').catch(err => this.onError?.(err)) }
+      const offline = () => { this.pauseInternally('network').catch(err => this.onError?.(err)) }
       window.addEventListener('offline', offline)
       this.stopOffline = () => window.removeEventListener('offline', offline)
     }
     if (!this.stopOnline) {
-      const online = () => { this.resume('network').catch(err => this.onError?.(err)) }
+      const online = () => { this.syncPauseRecovery(); this.pauseRecoveries.get('network')?.wake() }
       window.addEventListener('online', online)
       this.stopOnline = () => window.removeEventListener('online', online)
     }
@@ -2718,7 +2879,7 @@ export class PrivateMessenger {
         controller.channelPubkey = pubkey
         this.recoveryControllers.add(controller)
         try {
-          if (this.pauseReasons.size || this.closePromise || !this.desiredChannels.has(pubkey)) throw new Error('PRIVATE_MESSENGER_PAUSED')
+          if (this.pauseReasons.size || this.closePromise || !this.desiredChannels.has(pubkey)) throw this.pausedError()
           const fetchRelays = await this.resolveWatchRelays(channel)
           controller.signal.throwIfAborted()
           const record = this.recoveryRangeRecord(pubkey, range)
@@ -2875,6 +3036,9 @@ export class PrivateMessenger {
     const initSettledPromise = this.initSettledPromise
     this.sendRoutingLifetime.abort()
     this.sendRelayExclusions.clear()
+    this.pendingStorageWrites.clear()
+    for (const task of this.pauseRecoveries.values()) task.stop()
+    for (const task of this.watchRecoveries.values()) task.stop()
     let unwatchPromise
     try {
       unwatchPromise = Promise.resolve(this.unwatch())
@@ -2932,6 +3096,7 @@ export class PrivateMessenger {
       this.recoveryPriority.clear()
       if (unwatchError) throw unwatchError
     })()
+    this.notifyStatus()
     return this.closePromise
   }
 }

package/private-messenger/session/README.md

@@ -40,13 +40,41 @@ 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.
+Sends that only failed because the messenger was paused stay pending without
+`onSendError`. `PrivateMessenger.readStatus()` and optional `onStateChanged`
+provide isolated `{ closed, paused, pauseReasons }` snapshots, initially and on
+actual transitions. Paused errors retain their `pauseReasons` and native cause.
+The session parks remote sends and wakes them immediately on release; local
+personal copies and self-chat remain writable.
+
+A custom `Messenger(options)` factory must provide synchronous `readStatus()`
+and honor `options.onStateChanged`: deliver an initial snapshot before the factory
+resolves and notify each effective state change. Snapshots contain boolean
+`closed`/`paused` and a `pauseReasons` string array; `paused` reflects whether that
+array is nonempty. The session copies snapshots and rejects missing observation
+with `MESSENGER_STATE_CONTRACT_REQUIRED`, or malformed state with
+`INVALID_MESSENGER_STATUS` (`ValidationError`). Rejected instances are closed and
+obsolete callbacks are ignored. Wrappers can forward the complete options to
+`createPrivateMessenger(options)` unchanged.
+
+Observed pauses never fall back to polling sends. Other transient availability
+failures without an active pause retain bounded 1..30s send retries; a pause
+superseding such a retry parks it until the state notification releases it.
+
+Network pauses observed internally use shared `isOnline`/`onOnline` monitoring,
+including recovery when no second native online event arrives. Offline waiting
+spends no backoff. Retryable watch failures recover by channel without globally
+pausing publication. Background historical recovery does not gate text sends.
+Internal storage pauses repair pending state writes before release; explicit
+external pauses remain owned by their caller. Operational recovery retries use
+1, 2, 4... seconds, capped at 30 seconds with 20% jitter; permanent relay and
+local validation/auth/permission failures await explicit recovery.
+
+A failed session inbox save uses the separate `session-storage` reason. The
+session retries the actual reserved record and releases only after save and ACK.
+No message eviction or false historical coverage is introduced. Account
+unavailability stops its recovery timers; availability or explicit retry can
+reevaluate a local failure without clearing another owner's storage pause.
 
 `enqueue({ peer, event, context, requiredFiles, deletion })` preserves prepared
 identities. Local message commits and remote stages have independent checkpoints.

package/private-messenger/session/index.js

@@ -5,11 +5,13 @@ import { getEventHash, isValidEvent, isSerializableEvent } from '../../event/ind
 import { decodeIrfsChunk, IRFS_CHUNK_BYTES } from '../../irfs/index.js'
 import { getIykcProofs } from '../../content-key/index.js'
 import { onOnline } from '../../network/index.js'
+import { ValidationError } from '../../error/index.js'
 import { decodeFileMetadata } from '../../nip94/index.js'
 import { createChatOutbox } from './helpers/work-storage.js'
 import { messengerSigner } from './helpers/signer.js'
 import { assertMessagePublished } from '../helpers/publication.js'
 import { normalizeFallbackRelays } from '../helpers/send-routing.js'
+import { createPauseRecovery, isRecoverableStorageFailure } from '../helpers/pause-recovery.js'
 
 export function wireEvent (value, owner) {
   const event = { kind: value.kind, created_at: value.created_at, tags: structuredClone(value.tags), content: value.content, pubkey: value.pubkey || owner }
@@ -27,10 +29,18 @@ const SEND_RETRY_MAX_MS = 30000
 const unavailableError = (error, signal) => Object.assign(new Error(error?.message || 'CHAT_UNAVAILABLE'), {
   code: error?.code,
   cause: error,
+  ...(Array.isArray(error?.pauseReasons) ? { pauseReasons: [...error.pauseReasons] } : {}),
   retryWhenAvailable: !signal?.aborted,
   retryWhenOnline: false
 })
 
+function messengerStatusSnapshot (value) {
+  if (!value || typeof value.closed !== 'boolean' || typeof value.paused !== 'boolean' ||
+      !Array.isArray(value.pauseReasons) || value.pauseReasons.some(reason => typeof reason !== 'string' || !reason.trim()) ||
+      value.paused !== Boolean(value.pauseReasons.length)) throw new ValidationError('INVALID_MESSENGER_STATUS')
+  return { closed: value.closed, paused: value.paused, pauseReasons: [...value.pauseReasons] }
+}
+
 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()
@@ -51,6 +61,33 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   const cancelled = new Set()
   const sendControllers = new Map()
   const offlineSends = new Set()
+  const pausedSends = new Set()
+  let messengerStatus
+  let messengerBinding
+  let storageBlocked = false
+  const inboxRecovery = createPauseRecovery({
+    attempt: async signal => { signal.throwIfAborted(); await drain(); if (storageBlocked) throw inboxError },
+    retryable: isRecoverableStorageFailure, onError: reportError,
+    setTimer: _setTimeout, clearTimer: _clearTimeout, random: _random
+  })
+  let inboxError
+  const stateChanged = state => {
+    if (closed) return
+    messengerStatus = messengerStatusSnapshot(state)
+    if (!available || state.closed) return
+    if (state.paused) {
+      for (const entry of entries.values()) {
+        if (entry.peer !== owner && entry.failed && entry.status === 'pending') pausedSends.add(entry.id)
+      }
+      if (![...entries.values()].some(entry => pendingRetryable(entry) && !pausedSends.has(entry.id))) clearSendRetry()
+      return
+    }
+    clearSendRetry()
+    for (const id of pausedSends) { const entry = entries.get(id); if (entry) entry.failed = false }
+    pausedSends.clear()
+    // The callback can run inside construction/resume, before configure settles.
+    queueMicrotask(() => pump())
+  }
   let stopOnline
   let sendRetryTimer
   let sendRetryDelay = SEND_RETRY_MIN_MS
@@ -70,12 +107,15 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   let storage
   let initialized
   let closed = false
+  let closeWork
   let available = false
   let lifecycle = 0
   let configuring = Promise.resolve()
+  let configurationFailed = false
   let sending
   let repump
   let draining
+  let redrain = false
   const idleWaiters = new Set()
   const settled = () => { if (!sending && !draining) { for (const resolve of idleWaiters) resolve(); idleWaiters.clear() } }
   const emit = () => onOutbox([...entries.values()].filter(entry => !entry.deletion))
@@ -84,6 +124,35 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     for (const entry of await storage.list()) entries.set(entry.id, entry)
     emit()
   })().catch(async error => { await storage?.close(); storage = null; initialized = null; throw error }))
+  async function createMessenger () {
+    const binding = {}
+    messengerBinding = binding
+    let notified = false
+    let candidate
+    try {
+      candidate = await Messenger({
+        fallbackRelays, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys,
+        onMessageQueued: () => { if (messengerBinding === binding) return drain() },
+        onStateChanged: state => {
+          if (closed || messengerBinding !== binding) return
+          stateChanged(state)
+          notified = true
+        },
+        onError: reportError
+      })
+      if (closed) { messengerBinding = null; await candidate?.close?.(); return }
+      if (typeof candidate?.readStatus !== 'function' || !notified) throw new ValidationError('MESSENGER_STATE_CONTRACT_REQUIRED')
+      const status = messengerStatusSnapshot(candidate.readStatus())
+      messenger = candidate
+      stateChanged(status)
+    } catch (error) {
+      messengerBinding = null
+      messengerStatus = undefined
+      try { await candidate?.close?.() } catch (cleanupError) { reportError(cleanupError) }
+      throw error
+    }
+  }
+
   async function configure () {
     if (closed || !available) return
     await ready()
@@ -102,7 +171,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       if (closed || !available || version !== lifecycle) return
       values.push(channel)
     }
-    if (!messenger) messenger = await Messenger({ fallbackRelays, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys, onMessageQueued: () => drain(), onError: reportError })
+    if (!messenger) await createMessenger()
+    if (!messenger) return
     if (closed || !available || version !== lifecycle) { await messenger.pause('signer'); return }
     await messenger.update({ channels: values })
     if (pendingPriorityRanges.size && typeof messenger.prioritizeRange === 'function') {
@@ -116,6 +186,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       }
     }
     await messenger.resume('signer')
+    if (storageBlocked) inboxRecovery.start({ immediate: true })
     if (!fileTransfers) {
       fileTransfers = FileTransfer({
         messenger, onError: reportError,
@@ -153,13 +224,16 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   function schedule () {
     const work = configuring.catch(() => {}).then(configure)
     configuring = work
-    work.catch(reportError)
+    work.then(() => { if (configuring === work) configurationFailed = false }, error => { if (configuring === work) configurationFailed = true; reportError(error) })
     return work
   }
   async function drain () {
-    if (draining || closed || !available || !messenger) return
+    if (draining) { redrain = true; return }
+    if (closed || !available || !messenger) return
     draining = true
     const deferred = []
+    let persisted = false
+    let passFailed = false
     try {
       while (true) {
         if (closed || !available) break
@@ -181,16 +255,33 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           if (!available || closed) { await nack(); break }
           const saved = await messageStorage.save(event, { peerPubkey: peer, hearsay: message.provenance === 'hearsay' })
           if (!saved?.result?.ok && !['blocked', 'expired'].includes(saved?.result?.code)) throw Object.assign(new Error('INBOX_STORAGE_FAILED'), { code: saved?.result?.code?.toUpperCase() })
-          await ack()
+          if (!available || closed) { await nack(); break }
+          if (await ack() === false) throw new Error('INBOX_ACK_FAILED')
+          persisted = true
         } catch (error) {
           await nack()
           reportError(error)
           // Retain the failed record and suspend network ingestion until recovery.
-          await messenger.pause('storage')
+          passFailed = true
+          storageBlocked = true
+          inboxError = error
+          await messenger.pause('session-storage')
+          if (isRecoverableStorageFailure(error)) inboxRecovery.start()
           break
         }
       }
-    } finally { await Promise.all(deferred.map(nack => nack())); draining = false; settled() }
+      if (storageBlocked && persisted && !passFailed) {
+        // A retry can save one record and fail the next. Only release after the
+        // whole currently admissible pass completes without another failure.
+        storageBlocked = false; inboxError = null
+        await messenger.resume('session-storage')
+      }
+    } finally {
+      await Promise.all(deferred.map(nack => nack()))
+      draining = false; settled()
+      const again = redrain; redrain = false
+      if (again && !storageBlocked && !closed && available) queueMicrotask(() => drain())
+    }
   }
   async function publish (peer, event, signal) {
     if (deniedPeers.has(peer)) throw new Error('PERMISSION_DENIED')
@@ -229,6 +320,9 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           await storage.put(entry, { existing: true })
         }
       }
+      if (entry.peer !== owner && messengerStatus?.paused) {
+        throw unavailableError(Object.assign(new Error('PRIVATE_MESSENGER_PAUSED'), { pauseReasons: [...messengerStatus.pauseReasons] }), controller.signal)
+      }
       // Read/publish one chunk at a time. Progress is durable after each
       // accepted chunk; replay after interruption keeps its original identity.
       for (; entry.peer !== owner && entry.fileIndex < entry.files.length; entry.fileIndex++, entry.chunkIndex = 0) {
@@ -273,20 +367,20 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       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)
+        if (entry.peer !== owner && error.retryWhenAvailable && messenger.readStatus().paused) pausedSends.add(entry.id)
         reportError(error)
         // 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 (error.retryWhenAvailable && !pausedSends.has(entry.id)) 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.
+  // Transient availability failures without an active messenger pause retain
+  // bounded retries. Observed pauses wait exclusively for their release.
   function clearSendRetry () {
     if (sendRetryTimer) _clearTimeout(sendRetryTimer)
     sendRetryTimer = undefined
@@ -305,7 +399,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       if (closed || !available) return
       let retried = false
       for (const entry of entries.values()) {
-        if (!pendingRetryable(entry)) continue
+        if (!pendingRetryable(entry) || pausedSends.has(entry.id)) continue
         entry.failed = false
         retried = true
       }
@@ -341,9 +435,10 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
         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
+          if (entry.peer !== owner && entry.files.length && !fileTransfers) continue
           await sendEntry(entry)
         }
-      } while (repump && !closed && available)
+      } while (repump)
     } finally {
       sending = false
       watchOfflineSends()
@@ -416,21 +511,26 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       return true
     },
     async setPeers (values) {
-      peers.clear(); for (const peer of values) if (peer !== owner) peers.add(peer)
+      const next = new Set([...values].filter(peer => peer !== owner))
+      if (next.size === peers.size && [...next].every(peer => peers.has(peer))) return configuring
+      peers.clear(); for (const peer of next) peers.add(peer)
       for (const peer of deniedPeers) if (!peers.has(peer)) deniedPeers.delete(peer)
       lifecycle++
       return schedule()
     },
     async setAvailable (value) {
+      const changed = available !== (value === true)
       available = value === true
+      if (!changed && !available) return
       stopOnlineRetry(); offlineSends.clear()
       if (available) resetSendRetry()
       else clearSendRetry()
-      lifecycle++
-      if (!available) { await messenger?.pause('signer'); return }
+      if (changed) lifecycle++
+      if (!available) { inboxRecovery.stop(); await messenger?.pause('signer'); return }
       await ready()
       for (const entry of entries.values()) if (pendingRetryable(entry)) entry.failed = false
-      await messenger?.resume('storage')
+      if (storageBlocked) inboxRecovery.start({ immediate: true })
+      if (!changed && messenger && !configurationFailed) return pump()
       return schedule()
     },
     async enqueue ({ peer, event, context = [], requiredFiles = [], deletion = false }) {
@@ -446,7 +546,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       return id
     },
     async retry (id) {
-      offlineSends.delete(id); watchOfflineSends()
+      offlineSends.delete(id); pausedSends.delete(id); watchOfflineSends()
+      if (storageBlocked) inboxRecovery.start({ immediate: true })
       await ready()
       const entry = entries.get(id)
       if (entry) { entry.failed = false; resetSendRetry(); if (deniedPeers.delete(entry.peer)) await schedule(); return pump() }
@@ -454,24 +555,26 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     async cancel (id) {
       cancelled.add(id)
       sendControllers.get(id)?.abort()
-      offlineSends.delete(id); watchOfflineSends()
+      offlineSends.delete(id); pausedSends.delete(id); watchOfflineSends()
       await ready()
       entries.delete(id)
       await storage.remove(id)
       emit()
     },
-    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')
-      if (sending || draining) await new Promise(resolve => idleWaiters.add(resolve))
-      await messenger?.close()
-      await storage?.close()
-      await downloadWriteTail.catch(reportError)
-      await downloads?.close()
+    close () {
+      return (closeWork ??= (async () => {
+        closed = true; available = false; lifecycle++
+        stopOnlineRetry(); offlineSends.clear(); activeDownloads.clear(); pendingPriorityRanges.clear()
+        clearSendRetry(); inboxRecovery.stop(); pausedSends.clear()
+        for (const controller of sendControllers.values()) controller.abort()
+        await Promise.allSettled([configuring, initialized])
+        await messenger?.pause('closed')
+        if (sending || draining) await new Promise(resolve => idleWaiters.add(resolve))
+        await messenger?.close()
+        await storage?.close()
+        await downloadWriteTail.catch(reportError)
+        await downloads?.close()
+      })())
     }
   }
 }

package/relay/helpers/error.js

@@ -1,3 +1,5 @@
+import { parseRelayRetryAdvice } from './retry-advice.js'
+
 // 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))
@@ -29,14 +31,10 @@ export function relayCloseError (event, category, cause) {
   return categorizeRelayError(error, category)
 }
 
-// retry_after is an optional relay extension, in seconds. Bound remote advice
-// to five minutes; invalid metadata must not stall unrelated operations.
+// Keep native diagnostics and attach only bounded timing advice. An absolute
+// deadline survives delayed delivery through a launcher-owned relay bridge.
 export function relayRejectionError (reason, extra, fallback) {
   const error = categorizeRelayError(reason, 'relay', fallback)
-  const seconds = extra?.retry_after
-  if (error.message.startsWith('rate-limited:') && typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0) {
-    error.retryAfterMs = Math.min(seconds, 300) * 1000
-    error.retryAt = Date.now() + error.retryAfterMs
-  }
+  Object.assign(error, parseRelayRetryAdvice(error.message, extra))
   return error
 }

package/relay/helpers/retry-advice.js

@@ -0,0 +1,18 @@
+// Nostr transport extensions, in seconds. Timing advice is bounded and never
+// supplies an error category, provenance or a routing/retry policy.
+export function parseRelayRetryAdvice (reason, extra, { now = Date.now() } = {}) {
+  if (typeof reason !== 'string' || !reason.startsWith('rate-limited:') ||
+      !extra || typeof extra !== 'object' || Array.isArray(extra) || !Number.isFinite(now)) return null
+
+  const after = extra.retry_after
+  const retryAfterMs = typeof after === 'number' && Number.isFinite(after) && after > 0
+    ? Math.min(after, 300) * 1000
+    : undefined
+  const at = extra.retry_at
+  const absolute = typeof at === 'number' && Number.isFinite(at) && at > 0 && Number.isFinite(at * 1000)
+    ? Math.min(at * 1000, now + 300000)
+    : undefined
+  const retryAt = absolute ?? (retryAfterMs === undefined ? undefined : now + retryAfterMs)
+  if (retryAt === undefined) return null
+  return { ...(retryAfterMs === undefined ? {} : { retryAfterMs }), retryAt }
+}

package/relay/index.js

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