libp2r2p 0.11.17 → 0.11.19

package/README.md

@@ -535,7 +535,8 @@ new channels are watched unless paused. Applications may explicitly watch again.
 
 Pauses, unwatch and close record the start of the gap, even for channels that
 have never received a message. Rewatch/resume uses live delivery plus historical
-recovery with overlap. A failed resume remains retryable under its pause reason.
+recovery with overlap. Remote recovery failures never restore the caller's pause
+reason: signer availability belongs exclusively to the account owner.
 Before opening a watch, the messenger persists a pending recovery interval.
 A first watch scans the configured recovery window (seven days by default),
 including messages sent before this identity first opened the channel. Successful
@@ -546,6 +547,24 @@ This also covers abrupt termination without `close()` and channels with no
 messages. Applications still supply signers and desired channels on reopening;
 storage is scoped by origin and user pubkey, not the transient session ID.
 Failed ingestion or incomplete relay fetch reports never complete the gap.
+
+`init()` and `createPrivateMessenger()` resolve after local preparation. Likewise,
+`update(options, { waitForBackground = false })` and
+`resume(reason, { waitForBackground = false })` wait for valid local channel
+configuration and mandatory durable writes, allowing sends independently of
+subscriptions, presence and history. Set `waitForBackground: true` to also await
+the initial background tasks associated with that call, not every future retry.
+Both modes share tasks; unchanged configuration does not recreate subscriptions.
+Later errors reach `onError` with the original error as `cause` and
+`operation: 'private-messenger.background'` plus a `phase`. Cancelled or obsolete
+tasks cannot deliver into a new channel generation. Mandatory persistence still
+owns its storage pause; incomplete history remains a pending recovery interval.
+Subscription setup is bounded separately from presence, so a slow announcement
+does not hold the other channels' readers. Sessions prioritize user persistence
+and publication before the next background presence signer call. Signing an outer
+envelope can overlap recovery-seed persistence, but no envelope is yielded for
+publication unless both succeed; only one outer is prepared at a time.
+
 `private-channel.fetch` reports incomplete reads as an `AggregateError` with
 stable `code: 'PRIVATE_CHANNEL_FETCH_INCOMPLETE'`. Its message names relays,
 completion statuses and native failure messages, including status-only failures.
@@ -1056,7 +1075,7 @@ 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`
+primary destinations by default, 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
@@ -1133,3 +1152,10 @@ 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).
+
+Private messenger/session constructors accept optional `fallbackDelayMs` (`null`
+by default). Automatic NIP-65 sends can start configured fallback relays after
+the chosen delay while primary publications retain their deadlines. Explicit
+routes keep sequential fallback; every encrypted recipient must be covered.
+`RelayPool.sendEvent` accepts a consumer `signal` without closing shared sockets.
+See [fallback and cancellation](private-messenger/session/README.md#relay-fallback).

package/helpers/abortable-semaphore.js

@@ -1,6 +1,6 @@
 // A bounded FIFO for asynchronous work. Acquired leases release explicitly;
 // queued cancellations never consume capacity or keep idle keyed gates alive.
-export function createAbortableSemaphore (capacity, onIdle = () => {}) {
+export function createAbortableSemaphore (capacity, onIdle = () => {}, { maxQueued = 256 } = {}) {
   const queue = []
   let active = 0
   const drain = () => {
@@ -21,7 +21,7 @@ export function createAbortableSemaphore (capacity, onIdle = () => {}) {
   return {
     acquire (signal) {
       signal?.throwIfAborted()
-      if (queue.length >= 256) return Promise.reject(Object.assign(new Error('PRIVATE_CHANNEL_HISTORY_QUEUE_FULL'), { code: 'PRIVATE_CHANNEL_HISTORY_QUEUE_FULL' }))
+      if (queue.length >= maxQueued) return Promise.reject(Object.assign(new Error('PRIVATE_CHANNEL_HISTORY_QUEUE_FULL'), { code: 'PRIVATE_CHANNEL_HISTORY_QUEUE_FULL' }))
       return new Promise((resolve, reject) => {
         const job = {
           signal, resolve, abort: () => {

package/package.json

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

package/private-channel/index.js

@@ -158,7 +158,8 @@ async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiver
   const routerReceiverTag = receiverTag ?? (receiverPubkeyList.length === 1 ? receiverPubkeyList[0] : '')
   const rowIndexes = preparedRowIndexesForReceivers(context.preparedRows, receivers)
   const total = preparedChunkCount(context.preparedRows, rowIndexes)
-  if (onPreparedSeed) {
+  const persistSeeds = async () => {
+    if (!onPreparedSeed) return
     const router = makeRouterEvent({ pubkey: routerPubkey, senderPubkey: context.senderPubkey, imkcPubkey: context.imkcPubkey, imkcProof: context.imkcProof, receiverPubkey: routerReceiverTag, chunkIndex: 0, chunkTotal: 1, fileChunkIndex, content: '' })
     const payloadRow = readPreparedRow(context.preparedRows, 0)
     for (const rowIndex of rowIndexes) {
@@ -179,12 +180,18 @@ async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiver
       content
     }), routerSeckey)
     const createdAt = nowSeconds()
-    const outer = await privateChannelSigner.signEvent({
+    const prepareOuter = async () => privateChannelSigner.signEvent({
       kind: PRIVATE_BROADCAST_KIND,
       created_at: createdAt,
       tags: privateBroadcastTags({ deletionPubkey, createdAt, expirationSeconds }),
       content: await nip44v3EncryptText(privateChannelSigner, context.channelReaderPubkey, PRIVATE_BROADCAST_KIND, JSON.stringify(router))
     })
+    // These independent steps may run together, but no envelope is yielded
+    // until every seed is durable. Settle both before releasing prepared rows.
+    const [persistence, prepared] = await Promise.allSettled([index === 1 ? persistSeeds() : undefined, prepareOuter()])
+    if (persistence.status === 'rejected') throw persistence.reason
+    if (prepared.status === 'rejected') throw prepared.reason
+    const outer = prepared.value
     if (eventByteLength(outer) > MAX_EVENT_BYTES) throw new ValidationError('EVENT_TOO_LARGE')
     yield outer
   }

package/private-messenger/helpers/background-signer.js

@@ -0,0 +1,16 @@
+// Keep actual permissions and cryptography in the signer. Background presence
+// only yields before its next RPC, without interrupting an operation in flight.
+export function backgroundSigner (signer, wait, signal) {
+  if (!signer || !wait) return signer
+  return new Proxy(signer, {
+    get (target, key) {
+      const value = Reflect.get(target, key, target)
+      if (typeof value !== 'function') return value
+      return async (...args) => {
+        await wait(signal)
+        signal?.throwIfAborted()
+        return value.apply(target, args)
+      }
+    }
+  })
+}

package/private-messenger/helpers/fallback-race.js

@@ -0,0 +1,134 @@
+import { isReplaceableRelayFailure } from '../../relay/helpers/failure.js'
+
+// Each invocation owns one already signed outer event and its encrypted subset.
+// Lanes share coverage and the tried set; only started reports outlive the race.
+export function publishWithEarlyFallback ({ event, receivers, first, mirrors, tried, nextPrimary, nextFallback, sendEvent, isOnline, isCurrent, signal, pauseSignal, remember, delay, now, setTimer, clearTimer }) {
+  const pending = new Set(receivers)
+  const summaries = []
+  const transportSignal = signal && pauseSignal ? AbortSignal.any([signal, pauseSignal]) : signal || pauseSignal
+  const outcome = Promise.withResolvers()
+  let primaryRunning = true
+  let fallbackRunning = false
+  let fallbackScheduled = true
+  let done = false
+  let blocked = false
+  let offline = false
+  let timer = null
+  let onlineWork
+  const current = () => !transportSignal?.aborted && isCurrent()
+  const summary = success => Promise.all(summaries).then(reports => ({
+    success, total: tried.size,
+    fulfilled: reports.reduce((total, report) => total + (report.fulfilled || 0), 0),
+    succeededRelays: [...new Set(reports.flatMap(report => report.succeededRelays || []))],
+    errors: reports.flatMap(report => report.errors || [])
+  }))
+  const finish = success => {
+    if (done) return
+    done = true
+    clearTimer(timer); timer = null
+    transportSignal?.removeEventListener('abort', interrupted)
+    const interruptedWork = !success && (offline || !current())
+    outcome.resolve({
+      success, total: tried.size, promise: summary(success),
+      ...(interruptedWork && !signal?.aborted ? { retryWhenAvailable: true, ...(offline ? { retryWhenOnline: true } : {}) } : {})
+    })
+  }
+  const check = () => {
+    if (done) return
+    if (!pending.size) finish(true)
+    else if (!primaryRunning && !fallbackRunning && !fallbackScheduled) finish(false)
+  }
+  const interrupted = () => finish(false)
+  const online = async () => {
+    if (done || !current()) return false
+    try {
+      if (!onlineWork) {
+        const work = Promise.resolve().then(() => isOnline({ signal: transportSignal })).finally(() => { if (onlineWork === work) onlineWork = null })
+        onlineWork = work
+      }
+      const connected = await onlineWork
+      if (done || !current()) return false
+      if (!connected) offline = true
+      return connected
+    } catch { if (!done && current()) offline = true; return false }
+  }
+  const launch = async (batch, extra = []) => {
+    const relays = [...new Set([...batch.relays, ...extra])].filter(relay => !tried.has(relay))
+    if (!relays.length) return
+    for (const relay of relays) tried.add(relay)
+    const slot = Promise.withResolvers()
+    summaries.push(slot.promise)
+    let result
+    try { result = await sendEvent(event, relays, { signal: transportSignal }) } catch (reason) {
+      result = { success: false, promise: Promise.resolve({ fulfilled: 0, errors: [{ reason }] }) }
+    }
+    const settled = Promise.resolve(result.promise).catch(reason => ({ fulfilled: 0, errors: [{ reason }] }))
+    slot.resolve(settled)
+    settled.then(async report => {
+      const failed = (report.errors || []).filter(item => isReplaceableRelayFailure(item.reason))
+      // Late redundant failures can inform later sends after this race wins.
+      if (failed.length && (result.success || (done && !pending.size)) && !transportSignal?.aborted && isCurrent()) {
+        try { if (await isOnline({ signal: transportSignal }) && isCurrent()) remember(failed) } catch {}
+      }
+    }).catch(() => {})
+    if (result.success) {
+      if (!done) for (const receiver of batch.receivers) pending.delete(receiver)
+      check()
+      return
+    }
+    const report = await settled
+    if (done) return
+    const errors = report.errors || []
+    if (!errors.length || errors.some(item => !isReplaceableRelayFailure(item.reason))) blocked = true
+    else if (await online()) remember(errors)
+  }
+  async function fallback () {
+    if (done || fallbackRunning || !fallbackScheduled) return
+    clearTimer(timer)
+    fallbackScheduled = false
+    fallbackRunning = true
+    try {
+      if (blocked || offline || !pending.size || !current()) return
+      let batch = nextFallback(pending)
+      if (!batch || !await online()) return
+      while (batch) {
+        if (done || blocked || offline || !current()) break
+        await launch(batch)
+        batch = nextFallback(pending)
+      }
+    } finally { fallbackRunning = false; check() }
+  }
+  async function primary () {
+    try {
+      let batch = first || nextPrimary(pending)
+      let opening = true
+      while (batch) {
+        if (done || blocked || offline || !current()) break
+        await launch(batch, opening ? mirrors : [])
+        opening = false
+        batch = nextPrimary(pending)
+      }
+    } finally {
+      primaryRunning = false
+      // Exhaustion before the deadline starts the fallback immediately.
+      if (!done && fallbackScheduled) {
+        if (!blocked && !offline && current()) await fallback()
+        else { clearTimer(timer); fallbackScheduled = false }
+      }
+      check()
+    }
+  }
+  if (transportSignal?.aborted || !isCurrent()) { finish(false); return outcome.promise }
+  transportSignal?.addEventListener('abort', interrupted, { once: true })
+  const deadline = now() + delay
+  const failed = reason => {
+    if (done) return
+    done = true; clearTimer(timer); timer = null
+    transportSignal?.removeEventListener('abort', interrupted)
+    outcome.reject(reason)
+  }
+  timer = setTimer(() => { fallback().catch(failed) }, Math.max(0, deadline - now()))
+  timer?.unref?.()
+  primary().catch(failed)
+  return outcome.promise
+}

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

@@ -1,5 +1,6 @@
 import { normalizeRelayUrl } from '../../url/index.js'
 import { ValidationError } from '../../error/index.js'
+import { publishWithEarlyFallback } from './fallback-race.js'
 import { isReplaceableRelayFailure } from '../../relay/helpers/failure.js'
 
 const EXCLUSION_MS = 5 * 60 * 1000
@@ -12,6 +13,11 @@ export function normalizeFallbackRelays (value = []) {
   return [...new Set(Array.from(value, normalizeRelayUrl))]
 }
 
+export function normalizeFallbackDelay (value = null) {
+  if (value !== null && (!Number.isSafeInteger(value) || value < 0 || value > 2147483647)) throw new ValidationError('INVALID_FALLBACK_DELAY')
+  return value
+}
+
 function routeEntries (routes) {
   return routes instanceof Map ? [...routes] : Object.entries(routes || {})
 }
@@ -26,9 +32,11 @@ function routeGroups (routes) {
   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 }) {
+export function createSendRelayRouting ({ peer, peers = [peer], relaysByPubkey, primaryRelays, primaryRelayToReceivers, fallbackRelays = [], fallbackDelayMs = null, exclusions, pickRelays, recoveryRelays, publish, publishNymEvent, sendEvent, isOnline, isCurrent, signal, pauseSignal, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout }) {
   // Keep discovery's defaults when NIP-65 is unavailable. Explicit maps/lists
   // retain their fanout; configured fallbacks are a separate last-resort stage.
+  fallbackDelayMs = normalizeFallbackDelay(fallbackDelayMs)
+  const transportSignal = signal && pauseSignal ? AbortSignal.any([signal, pauseSignal]) : signal || pauseSignal
   const explicit = Boolean(primaryRelays || primaryRelayToReceivers)
   const primaryRoutes = primaryRelayToReceivers || (primaryRelays
     ? new Map(primaryRelays.map(relay => [relay, peers]))
@@ -61,12 +69,12 @@ export function createSendRelayRouting ({ peer, peers = [peer], relaysByPubkey,
     return routes
   }
   const relayToReceivers = primaryRelayToReceivers || select(peers, exclusions.keys())
-  const current = () => !signal?.aborted && isCurrent()
+  const current = () => !transportSignal?.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 remember = errors => { for (const item of errors) if (candidateSet.has(normalized(item.relay))) exclusions.set(normalized(item.relay), now() + EXCLUSION_MS) }
   const online = async () => {
     if (!current()) return false
-    try { return await isOnline({ signal }) && current() } catch { return false }
+    try { return await isOnline({ signal: transportSignal }) && current() } catch { return false }
   }
 
   async function send (event, initialRelays, context = {}) {
@@ -77,6 +85,24 @@ export function createSendRelayRouting ({ peer, peers = [peer], relaysByPubkey,
     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))
+    if (!explicit && fallbackDelayMs !== null && fallbackRelays.length) {
+      const tried = new Set()
+      const pick = (pending, fallback) => {
+        const excluded = [...new Set([...exclusions.keys(), ...tried])]
+        const routes = pickRelays([...pending], fallback
+          ? Object.fromEntries([...pending].map(pubkey => [pubkey, { read: fallbackRelays }]))
+          : primaryByPeer, { relayType: 'read', maxPerPubkey: 2, excludeRelaysByPubkey: new Map([...pending].map(pubkey => [pubkey, excluded])), emptyRelaysFallback: [] })
+        return routeGroups(routes)[0]
+      }
+      const result = await publishWithEarlyFallback({
+        event, receivers, first: first.length ? { receivers, relays: first } : null, mirrors, tried,
+        nextPrimary: pending => pick(pending, false), nextFallback: pending => pick(pending, true),
+        sendEvent, isOnline, isCurrent, signal, pauseSignal, remember,
+        delay: fallbackDelayMs, now, setTimer, clearTimer
+      })
+      if (!result.success && current()) exclusions.clear()
+      return result
+    }
     let batch = first.length ? { receivers, relays: first } : null
     const tried = new Set()
     const errors = []
@@ -106,7 +132,7 @@ export function createSendRelayRouting ({ peer, peers = [peer], relaysByPubkey,
       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)
+      result = await sendEvent(event, relays, { signal: transportSignal })
       const settled = Promise.resolve(result.promise)
       summaries.push(settled)
       if (result.success) {