libp2r2p 0.11.3 → 0.11.5

package/README.md

@@ -914,3 +914,18 @@ local defaults, including a bounded streaming file cache. The optional
 [`private-messenger/session`](private-messenger/session/README.md) coordinator
 provides reusable DM inbox/outbox and attachment lifecycle without UI coupling,
 including an optional `onSendError` callback identifying the failed outbox message.
+
+Private messages, including multi-recipient channels, retry NIP-65 read relays
+in pairs per recipient when
+selected relays reject publication or become unreachable while connectivity is
+confirmed. The exact encrypted outer events are reused. Optional `fallbackRelays` on
+`createPrivateMessenger` and `createPrivateMessageSession` are tried after the
+primary destinations, including explicit per-call `relays`, channel `sendRelays`
+and channel/global `relays`, as well as explicit `relayToReceivers` maps.
+Retries preserve each encrypted recipient subset; success requires accepted
+publication covering every recipient in that subset. Receive routing adds them from the start for live
+messages, history and files while preserving automatic NIP-65 updates. Successful sends keep first-ACK
+latency, and short-lived channel/recipient preferences avoid recently refused
+relays without changing receive subscriptions. See the
+[session coordinator](private-messenger/session/README.md) for deferred offline
+attempts and final failure notifications.

package/package.json

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

package/private-channel/index.js

@@ -37,7 +37,7 @@ const encoder = new TextEncoder()
 const decoder = new TextDecoder()
 const NIP44_V3_SCOPE = ''
 
-const sendToRelays = (...args) => relayPool.sendEvent(...args)
+const sendToRelays = (event, relays) => relayPool.sendEvent(event, relays)
 const getEvents = (...args) => relayPool.getEvents(...args)
 const getLiveEventsGenerator = (...args) => relayPool.getLiveEventsGenerator(...args)
 const getEventsFeedGenerator = (...args) => relayPool.getEventsFeedGenerator(...args)
@@ -540,7 +540,7 @@ export async function publish ({ senderSigner, imkcSigner, privateChannelSigner
     try {
       for (const group of groups) {
         for await (const wrappedEvent of wrapPreparedEvents({ privateChannelSigner, receivers: group.receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey: normalizedDeletionPubkey, expirationSeconds, context })) {
-          results.push(await _publish(wrappedEvent, withRecoveryRelays(group.relays, recoveryRelays)))
+          results.push(await _publish(wrappedEvent, withRecoveryRelays(group.relays, recoveryRelays), { receiverPubkeys: receiverPubkeys(group.receivers), primaryRelays: group.relays }))
         }
       }
     } finally {
@@ -550,7 +550,7 @@ export async function publish ({ senderSigner, imkcSigner, privateChannelSigner
   }
 
   for await (const wrappedEvent of wrapEvents({ senderSigner, imkcSigner, privateChannelSigner, privateChannelReaderPubkey, receivers, receiverTag, fileChunkIndex, onPreparedSeed, deletionPubkey: normalizedDeletionPubkey, event, expirationSeconds, temporaryStorageArea, _getIykcProofs })) {
-    results.push(await _publish(wrappedEvent, withRecoveryRelays(relays, recoveryRelays)))
+    results.push(await _publish(wrappedEvent, withRecoveryRelays(relays, recoveryRelays), { receiverPubkeys: receiverPubkeys(receivers), primaryRelays: relays }))
   }
   return results
 }

package/private-messenger/file/README.md

@@ -21,8 +21,10 @@ append it to the thumbnail URL. This is not a group-key derivation scheme.
   The application calls it for an explicit share, using its persisted message
   timestamp (standalone 1063 uses its own timestamp). Registration, cache hits
   and incoming requests never grant access. Missing router `p` is not a wildcard.
-- `publishChunk(descriptor, event)` checks a 34601 proof and the descriptor,
+- `publishChunk(descriptor, event, { signal } = {})` checks a 34601 proof and the descriptor,
   captures ciphertext only in watchtower mode, and publishes to the recipient's relays.
+  It shares the parent channel's automatic relay fallback and full publication
+  diagnostics; `signal` stops further replacement attempts.
   Every wrapper must receive at least one relay acceptance. Yield between calls
   so text/control sends can run. Publish all file chunks before announcing 1063/9.
 - `download(descriptor, { manual, thumbnail, signal })` returns the verified,

package/private-messenger/file/index.js

@@ -3,6 +3,7 @@ import { chunkStream } from './helpers/stream.js'
 import { createFileCache } from './helpers/cache.js'
 export { createFileCache, DEFAULT_FILE_CACHE_BYTES } from './helpers/cache.js'
 import { createFileCatalog } from './helpers/catalog.js'
+import { assertMessagePublished } from '../helpers/publication.js'
 import { ValidationError } from '../../error/index.js'
 import { IRFS_CHUNK_BYTES, decodeIrfsChunk } from '../../irfs/index.js'
 import { createQueue } from '../../idb-queue/index.js'
@@ -48,11 +49,6 @@ function rangesFor (indices) {
   return ranges
 }
 
-function assertPublished (result) {
-  const reports = result?.delivery?.reports
-  if (!Array.isArray(reports) || !reports.length || !reports.every(report => report?.success === true)) throw Object.assign(new Error('FILE_NOT_PUBLISHED'), { code: 'MESSAGE_NOT_PUBLISHED' })
-}
-
 function waitForTransfer (promise, signal) {
   signal?.throwIfAborted()
   if (!signal) return promise
@@ -148,14 +144,14 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
     if (decoded.root !== file.root || (index !== undefined && decoded.index !== index) || (file.size !== undefined && (decoded.total !== Math.ceil(file.size / IRFS_CHUNK_BYTES) || (decoded.index === decoded.total - 1 && decoded.contentBytes.length !== file.size - decoded.index * IRFS_CHUNK_BYTES)))) throw new ValidationError('FILE_CHUNK_DESCRIPTOR_MISMATCH')
     return decoded
   }
-  async function routing (file, receiverPubkey) {
+  async function routing (file, receiverPubkey, signal) {
     const parent = messenger.requireWritableChannel(file.controlChannelPubkey)
-    return messenger.resolveSendRouting({ channel: parent, receiverPubkeys: [receiverPubkey] })
+    return messenger.resolveSendRouting({ channel: parent, receiverPubkeys: [receiverPubkey], signal })
   }
   function sendOptions (file, routes) {
     return { senderSigner: messenger.userSigner, imkcSigner: messenger.contentKeySigner, privateChannelSigner: file.signer, ...routes, temporaryStorageArea: messenger.temporaryStorageArea, expirationSeconds: messenger.eventExpirationSecondsFor(file.controlChannelPubkey), _getIykcProofs: messenger.contentKeyLookup() }
   }
-  async function publishChunk (descriptor, event) {
+  async function publishChunk (descriptor, event, { signal } = {}) {
     const file = await register(descriptor)
     usable(file)
     const decoded = checked(file, event)
@@ -166,9 +162,9 @@ export function createPrivateFileTransfer ({ messenger, resolveChannel, storage,
     }
     let result
     try {
-      const options = { ...sendOptions(file, await routing(file, file.peerPubkey)), receiverPubkeys: [file.peerPubkey], fileChunkIndex: decoded.index, ...(messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? { onPreparedSeed: seed => saveSeed(file, seed) } : {}) }
+      const options = { ...sendOptions(file, await routing(file, file.peerPubkey, signal)), receiverPubkeys: [file.peerPubkey], fileChunkIndex: decoded.index, ...(messenger.channels.get(file.controlChannelPubkey)?.mode === 'watchtower' ? { onPreparedSeed: seed => saveSeed(file, seed) } : {}) }
       result = event.sig ? await _messages.broadcastEvent({ ...options, event }) : await _messages.broadcastRumor({ ...options, rumor: event })
-      assertPublished(result)
+      await assertMessagePublished(result, result?.rumor || result?.event || { ...event, pubkey: event.pubkey || messenger.userPubkey })
     } catch (error) { await uploadLeases.get(file.root)?.(); uploadLeases.delete(file.root); throw error }
     if (decoded.index === decoded.total - 1) { await uploadLeases.get(file.root)?.(); uploadLeases.delete(file.root) }
     // A scheduler turn between chunks lets queued text/control publications run.

package/private-messenger/{session/helpers → helpers}/publication.js

@@ -1,7 +1,8 @@
-import { getEventHash } from '../../../event/index.js'
+import { getEventHash } from '../../event/index.js'
 
 // A report describes one outer event, not one relay. Each outer event needs
-// at least one relay acknowledgement. Keep the successful fast path immediate.
+// accepted publication covering its routed recipients. Keep the successful fast
+// path immediate; a partially covered multi-recipient report remains a failure.
 export async function assertMessagePublished (result, event) {
   const reports = result?.delivery?.reports
   const present = Array.isArray(reports) && reports.length > 0
@@ -17,6 +18,8 @@ export async function assertMessagePublished (result, event) {
       return {
         index,
         total: settled?.total ?? report?.total,
+        ...(report?.retryWhenAvailable ? { retryWhenAvailable: true } : {}),
+        ...(report?.retryWhenOnline ? { retryWhenOnline: true } : {}),
         fulfilled: settled?.fulfilled,
         errors: (settled?.errors || []).map(({ relay, reason }) => ({ relay, reason }))
       }
@@ -32,6 +35,7 @@ export async function assertMessagePublished (result, event) {
   })
   throw Object.assign(new Error(`MESSAGE_NOT_PUBLISHED: ${details.join(' | ') || reason}`), {
     code: 'MESSAGE_NOT_PUBLISHED',
+    ...(failures.length && failures.every(report => report.retryWhenAvailable) ? { retryWhenAvailable: true, ...(failures.some(report => report.retryWhenOnline) ? { retryWhenOnline: true } : {}) } : {}),
     reason,
     eventId: getEventHash(event),
     eventKind: event.kind,

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

@@ -0,0 +1,144 @@
+import { normalizeRelayUrl } from '../../url/index.js'
+import { ValidationError } from '../../error/index.js'
+
+const REJECTION_PREFIXES = new Set(['blocked', 'restricted', 'auth-required', 'pow', 'rate-limited', 'error'])
+const TRANSPORT_CATEGORIES = new Set(['connection', 'transport', 'timeout'])
+const EXCLUSION_MS = 5 * 60 * 1000
+const normalized = relay => { try { return normalizeRelayUrl(relay) } catch { return '' } }
+
+// Only machine-readable relay policy/server failures qualify. Invalid events,
+// local signer denials and unknown prose must not rotate relays.
+export function isReplaceableRelayFailure (error) {
+  if (error?.name === 'Nip42AuthenticationError') return false
+  if (TRANSPORT_CATEGORIES.has(error?.category)) return true
+  if (error?.category && error.category !== 'relay') return false
+  return REJECTION_PREFIXES.has(/^([a-z-]+):/.exec(error?.message || '')?.[1])
+}
+
+export function normalizeFallbackRelays (value = []) {
+  if (!Array.isArray(value)) throw new ValidationError('INVALID_FALLBACK_RELAYS')
+  return [...new Set(Array.from(value, normalizeRelayUrl))]
+}
+
+function routeEntries (routes) {
+  return routes instanceof Map ? [...routes] : Object.entries(routes || {})
+}
+
+function routeGroups (routes) {
+  const groups = new Map()
+  for (const [relay, receivers] of routes) {
+    const key = [...receivers].sort().join(',')
+    if (!groups.has(key)) groups.set(key, { receivers, relays: [] })
+    groups.get(key).relays.push(relay)
+  }
+  return [...groups.values()]
+}
+
+export function createSendRelayRouting ({ peer, peers = [peer], relaysByPubkey, primaryRelays, primaryRelayToReceivers, fallbackRelays = [], exclusions, pickRelays, recoveryRelays, publish, publishNymEvent, sendEvent, isOnline, isCurrent, signal, now = Date.now }) {
+  // Keep discovery's defaults when NIP-65 is unavailable. Explicit maps/lists
+  // retain their fanout; configured fallbacks are a separate last-resort stage.
+  const explicit = Boolean(primaryRelays || primaryRelayToReceivers)
+  const primaryRoutes = primaryRelayToReceivers || (primaryRelays
+    ? new Map(primaryRelays.map(relay => [relay, peers]))
+    : pickRelays(peers, relaysByPubkey, { relayType: 'read', maxPerPubkey: Infinity }))
+  const primaryByPeer = Object.fromEntries(peers.map(pubkey => [pubkey, { read: [] }]))
+  for (const [relay, receivers] of routeEntries(primaryRoutes)) {
+    for (const pubkey of Array.isArray(receivers) ? receivers : [receivers]) primaryByPeer[pubkey]?.read.push(normalizeRelayUrl(relay))
+  }
+  const candidates = [...new Set([...Object.values(primaryByPeer).flatMap(value => value.read), ...fallbackRelays])]
+  const candidateSet = new Set(candidates)
+  for (const [relay, expires] of exclusions) if (expires <= now() || !candidateSet.has(relay)) exclusions.delete(relay)
+  // A fresh attempt can recheck an exhausted list; each outer event still owns
+  // a tried set so concurrent sends/fragments cannot create a retry loop.
+  if (peers.some(pubkey => {
+    const available = [...primaryByPeer[pubkey].read, ...fallbackRelays]
+    return available.length && available.every(relay => exclusions.has(relay))
+  })) exclusions.clear()
+  const select = (receivers, excluded, staged = false) => {
+    const excludedRelays = [...excluded]
+    const excludeRelaysByPubkey = new Map(receivers.map(pubkey => [pubkey, excludedRelays]))
+    const options = { relayType: 'read', excludeRelaysByPubkey, emptyRelaysFallback: [] }
+    const routes = pickRelays(receivers, primaryByPeer, { ...options, ...(explicit ? { maxPerPubkey: Infinity } : {}) })
+    // For one ciphertext, exhaust the remaining members' primary routes before
+    // using a common fallback. Initial wrapping must nevertheless cover everyone.
+    if (staged && routes.size) return routes
+    const covered = new Set([...routes.values()].flat())
+    const missing = receivers.filter(pubkey => !covered.has(pubkey))
+    const fallback = pickRelays(missing, Object.fromEntries(missing.map(pubkey => [pubkey, { read: fallbackRelays }])), options)
+    for (const [relay, pubkeys] of fallback) routes.set(relay, [...new Set([...(routes.get(relay) || []), ...pubkeys])])
+    return routes
+  }
+  const relayToReceivers = primaryRelayToReceivers || select(peers, exclusions.keys())
+  const current = () => !signal?.aborted && isCurrent()
+  const rejected = report => (report?.errors || []).filter(item => candidateSet.has(normalized(item.relay)) && isReplaceableRelayFailure(item.reason))
+  const remember = errors => { for (const item of errors) exclusions.set(normalized(item.relay), now() + EXCLUSION_MS) }
+  const online = async () => {
+    if (!current()) return false
+    try { return await isOnline({ signal }) && current() } catch { return false }
+  }
+
+  async function send (event, initialRelays, context = {}) {
+    // This context describes the already encrypted recipient subset. It stays
+    // local: no recipient tags or routing metadata are added to the outer event.
+    const receivers = context.receiverPubkeys || peers
+    const pending = new Set(receivers)
+    const mirrors = initialRelays.filter(relay => !candidateSet.has(normalized(relay)))
+    const initialPrimary = context.primaryRelays || (primaryRelays || peers.length === 1 ? routeEntries(relayToReceivers).map(([relay]) => relay) : [])
+    const first = [...new Set(initialPrimary.map(normalizeRelayUrl))].filter(relay => !exclusions.has(relay))
+    let batch = first.length ? { receivers, relays: first } : null
+    const tried = new Set()
+    const errors = []
+    const summaries = []
+    const next = () => routeGroups(select([...pending], new Set([...exclusions.keys(), ...tried]), true))[0]
+    const finish = result => ({
+      ...result,
+      success: summaries.length > 0 && pending.size === 0,
+      total: tried.size,
+      promise: Promise.all(summaries).then(reports => ({
+        total: tried.size,
+        success: summaries.length > 0 && pending.size === 0,
+        fulfilled: reports.reduce((total, report) => total + (report.fulfilled || 0), 0),
+        succeededRelays: [...new Set(reports.flatMap(report => report.succeededRelays || []))],
+        errors: reports.flatMap(report => report.errors || [])
+      }))
+    })
+    let result = { success: false }
+    while ((batch ||= next())) {
+      signal?.throwIfAborted()
+      const relays = [...new Set([...batch.relays, ...(summaries.length ? [] : mirrors)])]
+      for (const relay of relays) tried.add(normalized(relay))
+      // Every relay in this batch serves the same pending recipient subset.
+      // One ACK covers that subset, never unrelated members of the ciphertext.
+      result = await sendEvent(event, relays)
+      const settled = Promise.resolve(result.promise)
+      summaries.push(settled)
+      if (result.success) {
+        for (const pubkey of batch.receivers) pending.delete(pubkey)
+        // Keep the first ACK immediate; learn about redundant failures later.
+        settled.then(async report => {
+          const failed = rejected(report)
+          if (failed.length && await online()) remember(failed)
+        }).catch(() => {})
+        if (!pending.size) return finish(result)
+      } else {
+        const report = await settled
+        const failed = rejected(report)
+        errors.push(...(report?.errors || []))
+        if (!failed.length || errors.some(item => !isReplaceableRelayFailure(item.reason))) return finish(result)
+        if (!next()) { exclusions.clear(); return finish(result) }
+        if (!await online()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: current() }
+        remember(failed)
+      }
+      if (!current()) return { ...finish(result), retryWhenAvailable: !signal?.aborted, retryWhenOnline: false }
+      batch = null
+    }
+    return finish(result)
+  }
+
+  return {
+    relayToReceivers,
+    // A recovery mirror must not reintroduce refused relays or promote a fallback.
+    recoveryRelays: recoveryRelays.filter(relay => !candidateSet.has(normalized(relay)) || !exclusions.has(normalized(relay))),
+    _publish: options => (options.nymSigner ? publishNymEvent : publish)({ ...options, _publish: send })
+  }
+}

package/private-messenger/index.js

@@ -43,10 +43,13 @@
 // - For other event-list replies, use createEventReplyPacker({ messenger, question, code }).update(event).
 
 import * as privateMessage from '../private-message/index.js'
+import { isOnline } from '../network/index.js'
+import { createSendRelayRouting, normalizeFallbackRelays } from './helpers/send-routing.js'
+import { normalizeRelayUrl } from '../url/index.js'
 import { deliveryInfo } from '../private-channel/helpers/rumor.js'
 import { bytesToBase64 } from '../base64/index.js'
 import { ValidationError } from '../error/index.js'
-import { getRelaysByPubkey, pickRelaysForPubkeys, subscribeRelayListUpdates } from '../relay/index.js'
+import { getRelaysByPubkey, pickRelaysForPubkeys, subscribeRelayListUpdates, relayPool } from '../relay/index.js'
 import * as privateChannel from '../private-channel/index.js'
 import { DEFAULT_RECEIVED_CHUNK_TTL_MS } from '../private-channel/services/received-chunks.js'
 import { createQueue } from '../idb-queue/index.js'
@@ -191,6 +194,7 @@ export class PrivateMessenger {
   }
 
   constructor ({
+    fallbackRelays = [],
     offlineRecoverySeconds = DEFAULT_OFFLINE_RECOVERY_SECONDS,
     staleChannelSeconds = DEFAULT_STALE_CHANNEL_SECONDS,
     identityStorageRetentionSeconds = DEFAULT_IDENTITY_STORAGE_RETENTION_SECONDS,
@@ -215,6 +219,7 @@ export class PrivateMessenger {
     _getRelaysByPubkey = getRelaysByPubkey,
     _pickRelaysForPubkeys = pickRelaysForPubkeys,
     _subscribeRelayListUpdates = subscribeRelayListUpdates,
+    _isOnline = isOnline,
     _setTimeout = globalThis.setTimeout.bind(globalThis),
     _clearTimeout = globalThis.clearTimeout.bind(globalThis),
     _setInterval = globalThis.setInterval.bind(globalThis),
@@ -223,6 +228,7 @@ export class PrivateMessenger {
     _storageClearInterval = globalThis.clearInterval.bind(globalThis),
     _BroadcastChannel = _indexedDB === globalThis.indexedDB ? globalThis.BroadcastChannel : undefined
   } = {}) {
+    this.fallbackRelays = normalizeFallbackRelays(fallbackRelays)
     this.offlineRecoverySeconds = normalizeOfflineRecoverySeconds(offlineRecoverySeconds)
     this.staleChannelSeconds = normalizeStaleChannelSeconds(staleChannelSeconds)
     this.identityStorageRetentionSeconds = normalizeIdentityStorageRetentionSeconds(identityStorageRetentionSeconds)
@@ -247,6 +253,9 @@ export class PrivateMessenger {
     this._getRelaysByPubkey = _getRelaysByPubkey
     this._pickRelaysForPubkeys = _pickRelaysForPubkeys
     this._subscribeRelayListUpdates = _subscribeRelayListUpdates
+    this._isOnline = _isOnline
+    this.sendRelayExclusions = new Map()
+    this.sendRoutingLifetime = new AbortController()
     this._setTimeout = _setTimeout
     this._clearTimeout = _clearTimeout
     this._setInterval = _setInterval
@@ -670,6 +679,7 @@ export class PrivateMessenger {
 
     await this.unwatch(removedPubkeys)
     for (const pubkey of removedPubkeys) this.channels.delete(pubkey)
+    for (const [key, value] of this.sendRelayExclusions) if (removedPubkeys.includes(value.channelPubkey)) this.sendRelayExclusions.delete(key)
     for (const channel of nextChannels) this.channels.set(channel.pubkey, channel)
 
     await this.cleanupStaleChannels({ storageSnapshot })
@@ -749,19 +759,38 @@ export class PrivateMessenger {
   }
 
   async resolveWatchRelays (channel) {
-    if (!channel.usesNip65WatchRelays && channel.relays.length) return channel.relays
-    return this.readRelaysForPubkey(this.userPubkey)
+    const primary = !channel.usesNip65WatchRelays && channel.relays.length ? channel.relays : await this.readRelaysForPubkey(this.userPubkey)
+    return uniq([...primary, ...this.fallbackRelays].map(normalizeRelayUrl))
   }
 
-  async resolveSendRouting ({ channel, receiverPubkeys, relays, relayToReceivers }) {
+  async resolveSendRouting ({ channel, receiverPubkeys, relays, relayToReceivers, signal }) {
     const recoveryRelays = await this.recoveryMirrorRelays(channel.pubkey)
-    if (relayToReceivers) return { relayToReceivers, recoveryRelays }
-    if (relays?.length) return { relays: uniq(relays), recoveryRelays }
-    if (channel.sendRelays.length) return { relays: channel.sendRelays, recoveryRelays }
-    if (channel.relays.length) return { relays: channel.relays, recoveryRelays }
-    const derived = await this.readRelayToReceivers(receiverPubkeys)
-    if (!relayMapRelays(derived).length) throw new ValidationError('NO_RELAYS')
-    return { relayToReceivers: derived, recoveryRelays }
+    if (relayToReceivers && !this.fallbackRelays.length) return { relayToReceivers, recoveryRelays }
+    const fixed = relayToReceivers ? null : relays?.length ? uniq(relays) : channel.sendRelays.length ? channel.sendRelays : channel.relays.length ? channel.relays : null
+    if (fixed && !this.fallbackRelays.length) return { relays: fixed, recoveryRelays }
+    const recipients = uniq(receiverPubkeys?.length ? receiverPubkeys : relayMapReceivers(relayToReceivers))
+    const relaysByPubkey = fixed || relayToReceivers ? undefined : await this._getRelaysByPubkey(recipients)
+    const key = `${channel.pubkey}:${[...recipients].sort().join(',')}`
+    if (!this.sendRelayExclusions.has(key)) {
+      if (this.sendRelayExclusions.size >= 256) this.sendRelayExclusions.delete(this.sendRelayExclusions.keys().next().value)
+      this.sendRelayExclusions.set(key, { channelPubkey: channel.pubkey, exclusions: new Map() })
+    }
+    const routing = createSendRelayRouting({
+      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,
+      pickRelays: this._pickRelaysForPubkeys,
+      publish: this._privateChannel.publish || privateChannel.publish,
+      publishNymEvent: this._privateChannel.publishNymEvent || privateChannel.publishNymEvent,
+      sendEvent: (...args) => relayPool.sendEvent(...args),
+      isOnline: this._isOnline,
+      isCurrent: () => !this.closePromise && !this.pauseReasons.size && this.channels.has(channel.pubkey)
+    })
+    if (!relayMapRelays(routing.relayToReceivers).length) throw new ValidationError('NO_RELAYS')
+    // Fixed lists address the original receiver set as a whole, preserving the
+    // existing encryption grouping instead of inventing per-recipient routes.
+    if (fixed) return { relays: fixed, recoveryRelays: routing.recoveryRelays, _publish: routing._publish }
+    return routing
   }
 
   readState () {
@@ -1600,9 +1629,9 @@ export class PrivateMessenger {
     })
   }
 
-  async broadcastRumor ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, rumor, deletionPubkey }) {
+  async broadcastRumor ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, rumor, deletionPubkey, signal }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
+    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers, signal })
     this.debugSend('broadcastRumor', channelPubkey, { receiverPubkeys })
     return this._privateMessage.broadcastRumor({
       senderSigner: this.userSigner,
@@ -1621,9 +1650,9 @@ export class PrivateMessenger {
     })
   }
 
-  async broadcastEvent ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, event, deletionPubkey }) {
+  async broadcastEvent ({ channelPubkey = this.defaultChannelPubkey(), receiverPubkeys, relays, relayToReceivers, event, deletionPubkey, signal }) {
     const channel = this.requireWritableChannel(channelPubkey)
-    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers })
+    const routing = await this.resolveSendRouting({ channel, receiverPubkeys, relays, relayToReceivers, signal })
     this.debugSend('broadcastEvent', channelPubkey, { receiverPubkeys })
     return this._privateMessage.broadcastEvent({
       senderSigner: this.userSigner,
@@ -2187,6 +2216,8 @@ export class PrivateMessenger {
   close () {
     if (this.closePromise) return this.closePromise
     const initSettledPromise = this.initSettledPromise
+    this.sendRoutingLifetime.abort()
+    this.sendRelayExclusions.clear()
     let unwatchPromise
     try {
       unwatchPromise = Promise.resolve(this.unwatch())
@@ -2298,6 +2329,12 @@ function oldestCreatedAt (events) {
   return oldest
 }
 
+function relayMapReceivers (relayToReceivers) {
+  if (!relayToReceivers) return []
+  const values = relayToReceivers instanceof Map ? [...relayToReceivers.values()] : Object.values(relayToReceivers)
+  return uniq(values.flat())
+}
+
 function relayMapRelays (relayToReceivers) {
   if (!relayToReceivers) return []
   const entries = relayToReceivers instanceof Map ? relayToReceivers.entries() : Object.entries(relayToReceivers)

package/private-messenger/session/README.md

@@ -45,3 +45,66 @@ passing their established factories, as Zillion does.
 External recovery factories are owned by their caller and must be closed after
 the session. Work storage opened by the session is closed by the session.
 This is a DM profile; group membership/key derivation is not implemented.
+
+## Relay fallback
+
+Both `createPrivateMessenger` and `createPrivateMessageSession` accept an optional
+`fallbackRelays` array (default `[]`) at construction. URLs are normalized,
+deduplicated and copied; invalid values throw `ValidationError`. For example:
+
+```js
+const session = createPrivateMessageSession({
+  owner, signer, eventStore,
+  fallbackRelays: ['wss://relay.44billion.net']
+})
+```
+
+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.
+Explicit lists retain their requested initial fanout; no recipient relay lookup
+is added. A relay present in both lists is attempted only once per outer event.
+Automatic multi-recipient sends and explicit `relayToReceivers` maps also support
+fallbacks. Explicit maps retain their precedence over fixed lists, initial fanout
+and encrypted recipient subsets, without consulting recipient NIP-65 lists.
+The session coordinator remains a DM API; multi-recipient channels use
+`createPrivateMessenger` directly.
+
+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
+failures and unknown error text retain their original diagnosis.
+
+Receive routing always adds the configured fallback relays to the effective
+primary list (explicit `relays` or the owner's NIP-65 read relays). Listen there
+from the start, even when primary relays are healthy: a sender may have used a
+fallback after publication was refused elsewhere. Live watches, historical
+recovery and file-channel reads share this policy. NIP-65 refreshes retain the
+fallbacks; outgoing exclusions never remove them from receive subscriptions.
+No public recipient tags or changes to a user's NIP-65 event are introduced.
+
+Each signed outer event is reused verbatim, including router/carrier fragments
+and deletion capabilities. Native errors from exhausted attempts remain in its
+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
+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
+caller configuration; absent NIP-65 lists retain the existing discovery defaults.
+
+When offline/interrupted with alternatives remaining, reports carry
+`retryWhenAvailable: true`. The outbox remains pending and emits no `onSendError`.
+Offline reports also carry `retryWhenOnline: true`: the session owns a temporary
+`onOnline` subscription to retry those entries after confirmed connectivity,
+including brief outages the app's existing monitor might have missed. Cancel,
+close and signer unavailability release the subscription. Account recovery still
+uses `setAvailable(true)`; network recovery never overrides signer availability.
+`onSendError` is emitted only after final failure, including exhausted eligible
+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.

package/private-messenger/session/index.js

@@ -3,10 +3,12 @@ import { createPrivateFileTransfer } from '../file/index.js'
 import { createPrivateMessenger } from '../index.js'
 import { getEventHash, isValidEvent, isSerializableEvent } from '../../event/index.js'
 import { decodeIrfsChunk, IRFS_CHUNK_BYTES } from '../../irfs/index.js'
+import { onOnline } from '../../network/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 { assertMessagePublished } from '../helpers/publication.js'
+import { normalizeFallbackRelays } from '../helpers/send-routing.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 }
@@ -16,7 +18,8 @@ export function wireEvent (value, owner) {
 // Relay rejection text must not be interpreted as a local signer denial.
 const retryable = error => error?.code === 'MESSAGE_NOT_PUBLISHED' || !/DENIED|PERMISSION|REVOKED|READ_ONLY|INVALID|BLOCKED|EXPIRED|NOT_IN_PERSONA/i.test(`${error?.code || ''} ${error?.message || ''}`)
 
-export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+  fallbackRelays = normalizeFallbackRelays(fallbackRelays)
   const userSigner = messengerSigner(signer)
   messageStorage ||= createEventStoreMessageStorage({ eventStore })
   chunkStorage ||= eventStore ? createEventStoreChunkStorage({ eventStore }) : undefined
@@ -25,6 +28,9 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   const deniedPeers = new Set()
   const entries = new Map()
   const cancelled = new Set()
+  const sendControllers = new Map()
+  const offlineSends = new Set()
+  let stopOnline
   let messenger
   let fileTransfers
   let downloads
@@ -70,7 +76,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       if (closed || !available || version !== lifecycle) return
       values.push(channel)
     }
-    if (!messenger) messenger = await Messenger({ seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys: false, onMessageQueued: () => drain(), onError })
+    if (!messenger) messenger = await Messenger({ fallbackRelays, seedStorage: recoveryStorage?.seeds, userSigner, channels: [], useContentKeys: false, onMessageQueued: () => drain(), onError })
     if (closed || !available || version !== lifecycle) { await messenger.pause('signer'); return }
     await messenger.update({ channels: values })
     await messenger.resume('signer')
@@ -140,16 +146,18 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       }
     } finally { await Promise.all(deferred.map(nack => nack())); draining = false; settled() }
   }
-  async function publish (peer, event) {
+  async function publish (peer, event, signal) {
     if (deniedPeers.has(peer)) throw new Error('PERMISSION_DENIED')
     if (!available || !peers.has(peer) || !channels.has(peer)) throw new Error('CHAT_UNAVAILABLE')
-    const options = { channelPubkey: channels.get(peer)?.pubkey, receiverPubkeys: [peer] }
+    const options = { channelPubkey: channels.get(peer)?.pubkey, receiverPubkeys: [peer], signal }
     const report = event.sig ? await messenger.broadcastEvent({ ...options, event }) : await messenger.broadcastRumor({ ...options, rumor: event })
     // Published is relay acceptance, never a peer receipt.
     await assertMessagePublished(report, event)
   }
   async function sendEntry (entry) {
     entry.status = 'pending'; emit()
+    const controller = new AbortController()
+    sendControllers.set(entry.id, controller)
     try {
       const active = async () => {
         if (storage.has && !await storage.has(entry.id)) cancelled.add(entry.id)
@@ -180,7 +188,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
           const chunk = chunkStorage ? await chunkStorage.read(file.root, entry.chunkIndex, file) : await fileTransfers.readChunk(file.root, entry.chunkIndex)
           if (!chunk || decodeIrfsChunk(chunk).root !== file.root) { if (file.optional) break; throw new Error('FILE_UNAVAILABLE') }
           if (!fileTransfers) throw new Error('FILE_TRANSFER_UNAVAILABLE')
-          await fileTransfers.publishChunk({ controlChannelPubkey: channels.get(entry.peer).pubkey, peerPubkey: entry.peer, root: file.root, size: file.size }, wireEvent(chunk, owner))
+          await fileTransfers.publishChunk({ controlChannelPubkey: channels.get(entry.peer).pubkey, peerPubkey: entry.peer, root: file.root, size: file.size }, wireEvent(chunk, owner), { signal: controller.signal })
           const completed = entry.files.slice(0, entry.fileIndex).reduce((sum, value) => sum + value.size, 0) + Math.min(file.size, (entry.chunkIndex + 1) * IRFS_CHUNK_BYTES)
           entry.uploadProgress = { completed, total: entry.files.reduce((sum, value) => sum + value.size, 0) }
           emit()
@@ -199,7 +207,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       for (; entry.index < entry.events.length; entry.index++) {
         await active()
         const event = entry.events[entry.index]
-        if (entry.peer !== owner) await publish(entry.peer, event)
+        if (entry.peer !== owner) await publish(entry.peer, event, controller.signal)
         await active()
         await storage.put({ ...entry, index: entry.index + 1 }, { existing: true })
       }
@@ -208,15 +216,33 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       emit()
     } catch (error) {
       if (cancelled.has(entry.id)) { await storage.remove(entry.id); entries.delete(entry.id) } else {
-        entry.status = 'error'; entry.failed = true; entry.retryable = retryable(error)
+        entry.status = error.retryWhenAvailable ? 'pending' : 'error'; entry.failed = true; entry.retryable = retryable(error)
         await storage.put(entry, { existing: true }).catch(onError)
         onError(error)
         // The failed wire event may be a quote or file chunk. Report the
         // owning outbox item separately, without mutating the native error.
-        if (!closed && !entry.deletion && !cancelled.has(entry.id)) onSendError(error, { id: entry.id, peer: entry.peer })
+        if (error.retryWhenOnline) offlineSends.add(entry.id)
+        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 }
+  function watchOfflineSends () {
+    if (closed || !available || !offlineSends.size) { stopOnlineRetry(); return }
+    if (stopOnline) return
+    // A fresh listener receives confirmed connectivity even when a brief outage
+    // occurred between the app's long-lived monitor checks.
+    stopOnline = _onOnline(() => {
+      stopOnlineRetry()
+      if (closed || !available) return
+      for (const id of offlineSends) {
+        const entry = entries.get(id)
+        if (entry?.retryable) entry.failed = false
+      }
+      offlineSends.clear()
+      return schedule()
+    })
   }
   async function pump () {
     if (sending || !available || closed || !messenger || !storage) return
@@ -227,7 +253,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
         if ((entry.peer !== owner && !peers.has(entry.peer)) || entry.failed || cancelled.has(entry.id)) continue
         await sendEntry(entry)
       }
-    } finally { sending = false; settled() }
+    } finally { sending = false; watchOfflineSends(); settled() }
   }
   const intentId = file => getEventHash({ kind: 0, pubkey: owner, created_at: 0, tags: [], content: `${file.peer}:${file.root}` })
   async function download (file, options = {}) {
@@ -266,6 +292,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     },
     async setAvailable (value) {
       available = value === true
+      stopOnlineRetry(); offlineSends.clear()
       lifecycle++
       if (!available) { await messenger?.pause('signer'); return }
       await ready()
@@ -286,12 +313,15 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       return id
     },
     async retry (id) {
+      offlineSends.delete(id); watchOfflineSends()
       await ready()
       const entry = entries.get(id)
       if (entry) { entry.failed = false; if (deniedPeers.delete(entry.peer)) await schedule(); return pump() }
     },
     async cancel (id) {
       cancelled.add(id)
+      sendControllers.get(id)?.abort()
+      offlineSends.delete(id); watchOfflineSends()
       await ready()
       entries.delete(id)
       await storage.remove(id)
@@ -299,6 +329,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     },
     async close () {
       closed = true; available = false; lifecycle++
+      stopOnlineRetry(); offlineSends.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))