libp2r2p 0.11.16 → 0.11.18

package/private-messenger/index.js

@@ -45,8 +45,10 @@
 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 { createSendRelayRouting, normalizeFallbackRelays } from './helpers/send-routing.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, normalizeFallbackDelay } from './helpers/send-routing.js'
 import { incompleteFetchError } from '../private-channel/helpers/fetch-error.js'
 import { recoveryRetryDelay, isPermanentRecoveryError } from './helpers/recovery-retry.js'
 import { normalizeRelayUrl } from '../url/index.js'
@@ -210,6 +212,7 @@ export class PrivateMessenger {
 
   constructor ({
     fallbackRelays = [],
+    fallbackDelayMs = null,
     offlineRecoverySeconds = DEFAULT_OFFLINE_RECOVERY_SECONDS,
     staleChannelSeconds = DEFAULT_STALE_CHANNEL_SECONDS,
     identityStorageRetentionSeconds = DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS,
@@ -231,6 +234,7 @@ export class PrivateMessenger {
     useContentKeys = true,
     onContentKeyChange,
     onMessageQueued,
+    onStateChanged,
     onDebug,
     onError = defaultOnError,
     _privateMessage = privateMessage,
@@ -239,6 +243,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,7 +253,9 @@ 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.fallbackDelayMs = normalizeFallbackDelay(fallbackDelayMs)
     this.offlineRecoverySeconds = normalizeOfflineRecoverySeconds(offlineRecoverySeconds)
     this.staleChannelSeconds = normalizeStaleChannelSeconds(staleChannelSeconds)
     this.identityStorageRetentionSeconds = normalizeIdentityStorageRetentionSeconds(identityStorageRetentionSeconds)
@@ -277,6 +285,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
@@ -288,6 +306,7 @@ export class PrivateMessenger {
     this._isOnline = _isOnline
     this.sendRelayExclusions = new Map()
     this.sendRoutingLifetime = new AbortController()
+    this.sendRoutingPause = new AbortController()
     this._setTimeout = _setTimeout
     this._clearTimeout = _clearTimeout
     this._setInterval = _setInterval
@@ -351,6 +370,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 +683,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 +704,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
 
@@ -818,6 +844,8 @@ export class PrivateMessenger {
       peers: fixed && !recipients.length ? [this.userPubkey] : recipients, relaysByPubkey, recoveryRelays, primaryRelays: fixed?.map(normalizeRelayUrl), primaryRelayToReceivers: relayToReceivers, fallbackRelays: this.fallbackRelays,
       signal: signal ? AbortSignal.any([this.sendRoutingLifetime.signal, signal]) : this.sendRoutingLifetime.signal,
       exclusions: this.sendRelayExclusions.get(key).exclusions,
+      fallbackDelayMs: this.fallbackDelayMs, pauseSignal: this.sendRoutingPause.signal,
+      setTimer: this._setTimeout, clearTimer: this._clearTimeout,
       pickRelays: this._pickRelaysForPubkeys,
       publish: this._privateChannel.publish || privateChannel.publish,
       publishNymEvent: this._privateChannel.publishNymEvent || privateChannel.publishNymEvent,
@@ -1118,31 +1146,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 +1232,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 +1672,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 +1682,111 @@ 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.sendRoutingPause.abort(this.pausedError())
+    this.notifyStatus()
     for (const extension of this.extensions) extension.pause?.()
     this.recordInterruption(this.desiredChannels)
     for (const controller of this.recoveryControllers) controller.abort()
@@ -1641,7 +1796,15 @@ 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)
+    if (!this.pauseReasons.size && this.sendRoutingPause.signal.aborted) this.sendRoutingPause = new AbortController()
+    this.notifyStatus()
     if (reason === 'capacity' && removed) {
       clearInterval(this.capacityTimer)
       this.capacityTimer = null
@@ -1664,7 +1827,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 +1843,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 +1956,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 +1980,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 +2415,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 +2541,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 +2886,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 +3043,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 +3103,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.
@@ -82,7 +110,7 @@ const session = createPrivateMessageSession({
 })
 ```
 
-Automatic sends try each recipient's NIP-65 read relays first, at most two per
+By default, automatic sends try each recipient's NIP-65 read relays first, at most two per
 recipient per attempt, then the configured fallbacks in pairs. Explicit
 per-call `relays`, channel `sendRelays`/`relays` and global `relays` remain primary
 and also support configured fallbacks, including fixed multi-recipient sends.
@@ -94,6 +122,19 @@ and encrypted recipient subsets, without consulting recipient NIP-65 lists.
 The session coordinator remains a DM API; multi-recipient channels use
 `createPrivateMessenger` directly.
 
+Optional `fallbackDelayMs` defaults to `null` (sequential primary exhaustion).
+A nonnegative integer up to 2147483647 opts automatic NIP-65 routing into early
+fallback; explicit relay lists/maps retain the sequential policy. With `3000`,
+start at most two eligible fallback relays after three seconds without complete
+acceptance, or immediately after primary exhaustion. The deadline belongs to
+one signed outer event; later batches do not renew it. Primary operations retain
+their deadlines and can still win. Failed fallback operations leave primary
+alternatives available; no relay is tried twice. Multiple recipients require
+accepted coverage of every encrypted recipient subset. No wrapper, ID, recipient
+tag or deletion capability is recreated. Confirmed connectivity, exclusions and
+connection cooldowns remain authoritative; a waiting primary is not penalized
+merely because fallback started. Late native failures may inform later sends.
+
 On `blocked`, `restricted`, `auth-required`, `pow`, `rate-limited`, or `error`
 rejections, or connection/transport/timeout failures, replacement requires
 `isOnline` to confirm connectivity. Invalid messages, local signer/authentication
@@ -113,7 +154,8 @@ publication report. A shared relay's first ACK covers all members assigned to
 that publication batch. If replacements use different relays for different
 members, every pending member must be covered before the outer event succeeds;
 a partial ACK cannot hide another member's failure. Remaining primary routes are
-exhausted before configured fallbacks. Redundant acknowledgements may update
+exhausted before configured fallbacks with the default null delay or explicit
+routes. Redundant acknowledgements may update
 future routing preferences without delaying a successfully covered send. Preferences are channel/recipient-scoped, in-memory,
 expire after five minutes, and never alter receive subscriptions. A fresh attempt
 can recheck an exhausted list. Additional fallback relays come only from the
@@ -131,3 +173,12 @@ relays. Validation/authorization failures are terminal without relay rotation.
 `broadcastRumor`/`broadcastEvent` accept a `signal` to stop further replacement
 publications; the session supplies it and aborts it on cancel/close. An already
 published event cannot be recalled by cancellation.
+
+`RelayPool.sendEvent(event, relays, { signal })` supports optional cancellation.
+It returns the existing result/report envelopes with the original abort reason
+for unfinished relays, preserving partial acceptance and avoiding synthetic
+timeouts. Cancellation releases publication waiters and deferred sends without
+closing shared sockets or cancelling another subscriber for the same event ID.
+Operations already transmitted cannot be recalled from relays. A messenger pause
+cancels its outstanding publication work and leaves the outbox pending; resume
+creates a fresh publication lifetime, without treating the pause as a user abort.