libp2r2p 0.11.16 → 0.11.18

package/README.md

@@ -1056,7 +1056,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
@@ -1126,3 +1126,17 @@ are unchanged; newer live arrivals cannot erase a pending interval.
 count/bytes, incoming bytes, limits and oldest queued age. Queue bytes are UTF-8
 serialized volume, not heap use. Diagnostics never retain event contents or
 filters. Existing 1,000-item / 8-MiB live limits are unchanged.
+
+Private messenger status (`readStatus`, `onStateChanged`) exposes pause reasons
+without events or credentials. Sessions recover owned network/storage failures
+and wake pending sends on release rather than repeatedly publishing while paused.
+Custom session factories must expose `readStatus()` and deliver the initial and
+subsequent `onStateChanged` snapshots; missing observation is rejected instead of
+using polling compatibility. See [session lifecycle](private-messenger/session/README.md).
+
+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/package.json

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

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/pause-recovery.js

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

package/private-messenger/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) {