libp2r2p 0.11.25 → 0.11.26

package/README.md

@@ -10,7 +10,8 @@ power-ups used by that messenger.
 
 For remote-work scheduling, see [`libp2r2p/network`](network/README.md):
 `isOnline` probes connectivity and `onOnline` shares recovery monitoring,
-including retries when the browser omits its native `online` event.
+including retries when the browser omits its native `online` event and optional
+30-second expedited windows for foreground remote sends.
 
 ## Relay reads and lifecycle
 

package/network/README.md

@@ -30,3 +30,34 @@ Successful probes do not guarantee a particular relay or HTTP server is reachabl
 Handle request failures, cancellations, and timeouts separately. Browsers can
 suspend background tabs, so recovery notification has no wall-clock guarantee.
 Consumers should keep their own work queues but should not duplicate probe loops.
+
+
+## Expedited connectivity detection
+
+`onOnline(handler, { strict = false, expediteForMs = 0, onDebug })` can request
+an optional urgent window (clamped to 30,000 ms; finite, nonnegative durations).
+The same realm/mode monitor coalesces subscriptions: urgent requests can advance
+the next check, at least two seconds after the previous start. Failed checks
+repeat at five seconds between starts, without overlapping slow checks. Native
+online/focus/visibility wakeups remain available. Removing a subscription removes
+its demand without stopping other listeners.
+
+The urgent loop does not spend/reset the ordinary jittered backoff. At expiry it
+returns to the ordinary deadline, or a fresh interval of the preserved retry step
+if that deadline passed; it never catches up missed checks. For example, a normal
+60-second wait remains a 60-second step after an unsuccessful urgent window.
+Connectivity returning after the window must await normal recovery or a new user
+send/retry; automatic retries never extend urgency. `expediteForMs` is scheduling
+advice, not evidence of Internet connectivity or a relay/ACK delivery deadline.
+
+Private-message sessions remember a runtime-only 30-second deadline for new
+remote intents and manual retry. Only work actually waiting for network subscribes
+with the remaining time, sharing one subscription per session. Self-chat, restored
+outbox entries, chunks and automatic retries never renew that deadline. Lock and
+close discard urgency. A confirmed monitor result resumes the existing automatic
+pause owner without another immediate probe; explicit pauses remain caller-owned.
+
+Optional `onDebug` reports only probe reason, state, remaining window and duration.
+Consumers wire it only in development; it is disabled by default. The monitor
+retains no diagnostic history. Session diagnostics additionally correlate the
+network wait and pause-release duration with the event ID.

package/network/index.js

@@ -133,6 +133,8 @@ export function createConnectivityMonitor ({
   _setTimeout = globalThis.setTimeout,
   _clearTimeout = globalThis.clearTimeout,
   _random = Math.random,
+  _now = () => performance.now(),
+  onDebug,
   reportError = error => console.error('Online listener failed', error)
 } = {}) {
   if (check !== undefined && typeof check !== 'function') throw new ValidationError('INVALID_CONNECTIVITY_CHECK')
@@ -148,21 +150,49 @@ export function createConnectivityMonitor ({
     try { Promise.resolve(entry.handler()).catch(reportError) } catch (error) { reportError(error) }
   }
 
-  function schedule (current) {
-    if (session !== current || !listeners.size) return
-    const delay = current.online ? 60000 : RETRY_DELAYS[Math.min(current.retry++, RETRY_DELAYS.length - 1)]
+  const urgencyEnd = () => Math.max(0, ...[...listeners].map(entry => entry.expediteUntil))
+  function arm (current) {
+    if (session !== current || current.pending || !listeners.size) return
+    if (current.timer != null) clearTimer(current.timer)
+    const now = _now()
+    const until = urgencyEnd()
+    const urgent = until > now && (!current.online || current.urgentDue != null)
+    // Urgent checks do not consume or reset the ordinary retry sequence.
+    if (!urgent && current.normalDue <= now) current.normalDue = now + current.normalDelay
+    let due = current.normalDue
+    if (urgent) due = Math.min(until, current.urgentDue ?? current.lastStartedAt + 5000)
     current.timer = setTimer(() => {
       current.timer = null
-      return probe(current)
-    }, Math.round(delay * (0.8 + _random() * 0.4)))
+      if (urgent && _now() >= urgencyEnd()) { arm(current); return }
+      return probe(current, urgent ? 'expedited' : 'backoff')
+    }, Math.max(0, due - now))
     current.timer?.unref?.()
   }
 
-  async function probe (current) {
+  function schedule (current, expedited) {
+    if (session !== current || !listeners.size) return
+    if (!expedited || current.online) {
+      const delay = current.online ? 60000 : RETRY_DELAYS[Math.min(current.retry++, RETRY_DELAYS.length - 1)]
+      current.normalDelay = Math.round(delay * (0.8 + _random() * 0.4))
+      current.normalDue = _now() + current.normalDelay
+    }
+    current.urgentDue = null
+    arm(current)
+  }
+
+  async function probe (current, reason = 'wake') {
     if (session !== current || current.pending) return
     if (current.timer != null) clearTimer(current.timer)
     current.timer = null
     current.pending = true
+    current.lastStartedAt = _now()
+    const expedited = reason === 'expedited'
+    const startedAt = _now()
+    const report = values => {
+      const entry = { stage: 'connectivity-probe', reason, expediteRemainingMs: Math.max(0, urgencyEnd() - _now()), ...values }
+      for (const callback of [onDebug, ...[...listeners].map(listener => listener.onDebug)]) { try { callback?.(entry) } catch {} }
+    }
+    report({ state: 'started' })
     try {
       const online = await runCheck({ signal: current.controller.signal })
       if (session !== current) return
@@ -179,12 +209,13 @@ export function createConnectivityMonitor ({
       for (const entry of listeners) entry.delivered = false
     } finally {
       current.pending = false
-      schedule(current)
+      report({ state: current.online ? 'online' : 'offline', elapsedMs: _now() - startedAt })
+      schedule(current, expedited)
     }
   }
 
   function start () {
-    const current = { online: false, retry: 0, timer: null, pending: false, controller: new AbortController() }
+    const current = { online: false, retry: 0, timer: null, pending: false, lastStartedAt: -Infinity, normalDue: Infinity, normalDelay: 5000, urgentDue: null, controller: new AbortController() }
     session = current
     current.wake = () => { probe(current) }
     current.connectionChanged = () => {
@@ -213,18 +244,29 @@ export function createConnectivityMonitor ({
   }
 
   // Notify once on confirmed initial connectivity, then after each detected reconnection.
-  function onOnline (handler) {
+  function onOnline (handler, { expediteForMs = 0, onDebug } = {}) {
     if (typeof handler !== 'function') throw new ValidationError('INVALID_ONLINE_HANDLER')
-    const entry = { handler, delivered: false }
+    if (!Number.isFinite(expediteForMs) || expediteForMs < 0) throw new ValidationError('INVALID_EXPEDITE_FOR_MS')
+    if (onDebug !== undefined && typeof onDebug !== 'function') throw new ValidationError('INVALID_CONNECTIVITY_DEBUG')
+    const entry = { handler, onDebug, delivered: false, expediteUntil: _now() + Math.min(expediteForMs, 30000) }
     listeners.add(entry)
     if (!session) start()
     else {
       const current = session
-      queueMicrotask(() => { probe(current) })
+      if (expediteForMs > 0 || urgencyEnd() > _now()) {
+        current.urgentDue = Math.max(_now(), current.lastStartedAt + 2000)
+        arm(current)
+      } else {
+        queueMicrotask(() => {
+          if (urgencyEnd() > _now()) arm(current)
+          else probe(current)
+        })
+      }
     }
     return () => {
       if (!listeners.delete(entry)) return
       if (!listeners.size) stop()
+      else arm(session)
     }
   }
 
@@ -234,12 +276,12 @@ export function createConnectivityMonitor ({
 const defaultMonitors = new Map()
 
 // Share probes, capped backoff and wake-up listeners per mode in this realm.
-export function onOnline (handler, { strict = false } = {}) {
+export function onOnline (handler, { strict = false, expediteForMs = 0, onDebug } = {}) {
   const key = strict ? 'strict' : 'lenient'
   let monitor = defaultMonitors.get(key)
   if (!monitor) {
     monitor = createConnectivityMonitor({ strict })
     defaultMonitors.set(key, monitor)
   }
-  return monitor.onOnline(handler)
+  return monitor.onOnline(handler, { expediteForMs, onDebug })
 }

package/package.json

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

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

@@ -33,11 +33,14 @@ export function createPauseRecovery ({ attempt, online, onOnline, retryable, onE
     const run = () => {
       if (!active() || job.work) return job.work
       const work = (async () => {
-        if (online && !await online({ signal: job.controller.signal })) {
+        const confirmedOnline = job.confirmedOnline
+        job.confirmedOnline = false
+        if (online && !confirmedOnline && !await online({ signal: job.controller.signal })) {
           if (!active()) return
           job.stopOnline = onOnline(() => {
             if (!active()) return
             job.stopOnline?.(); job.stopOnline = null
+            job.confirmedOnline = true
             schedule(0)
           })
           return

package/private-messenger/session/index.js

@@ -45,7 +45,7 @@ function messengerStatusSnapshot (value) {
   return { closed: value.closed, paused: value.paused, pauseReasons: [...value.pauseReasons] }
 }
 
-export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], fallbackDelayMs = null, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], useContentKeys = true, pendingDecryptionReady = true, onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, onDebug, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, _isOnline = isOnline, _getIykcProofs = getIykcProofs, _setTimeout = setTimeout, _clearTimeout = clearTimeout, _random = Math.random, openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
+export function createPrivateMessageSession ({ owner, signer, eventStore, messageStorage, chunkStorage, recoveryStorage, fallbackRelays = [], fallbackDelayMs = null, mode = 'seeder', seedersForPeer = peer => [peer], allowedKinds = [5, 9, 1063, 34601], useContentKeys = true, pendingDecryptionReady = true, onMedia = () => {}, onOutbox = () => {}, onError = () => {}, onSendError = () => {}, onDebug, Messenger = createPrivateMessenger, openOutbox = createChatOutbox, FileTransfer = createPrivateFileTransfer, _onOnline = onOnline, _isOnline = isOnline, _getIykcProofs = getIykcProofs, _setTimeout = setTimeout, _clearTimeout = clearTimeout, _random = Math.random, _now = () => performance.now(), openDownloads = options => createChatOutbox({ ...options, namespace: 'downloads' }) }) {
   fallbackRelays = normalizeFallbackRelays(fallbackRelays)
   fallbackDelayMs = normalizeFallbackDelay(fallbackDelayMs)
   if (typeof pendingDecryptionReady !== 'boolean') throw new ValidationError('INVALID_PENDING_DECRYPTION_READY')
@@ -67,6 +67,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   const entries = new Map()
   const cancelled = new Set()
   const attemptStarts = new Map()
+  const networkUrgency = new Map()
   const sendControllers = new Map()
   const localReady = new Set()
   const localIdleWaiters = new Set()
@@ -79,6 +80,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   const offlineSends = new Set()
   const pausedSends = new Set()
   let messengerStatus
+  let networkPauseStartedAt
+  let networkConfirmed = false
   let messengerBinding
   let storageBlocked = false
   const inboxRecovery = createPauseRecovery({
@@ -89,22 +92,31 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
   let inboxError
   const stateChanged = state => {
     if (closed) return
+    const wasNetworkPaused = messengerStatus?.pauseReasons.includes('network')
     messengerStatus = messengerStatusSnapshot(state)
+    if (!wasNetworkPaused && state.pauseReasons.includes('network')) { networkPauseStartedAt = _now(); networkConfirmed = false }
+    if (wasNetworkPaused && !state.pauseReasons.includes('network')) {
+      for (const entry of entries.values()) if (entry.peer !== owner && entry.status !== 'saved') debug(entry, 'network-pause-released', undefined, { elapsedMs: _now() - networkPauseStartedAt })
+      networkPauseStartedAt = undefined; networkConfirmed = false
+    }
     if (!available || state.closed) return
     if (state.paused) {
       for (const entry of entries.values()) {
         if (entry.peer !== owner && entry.failed && entry.status === 'pending') pausedSends.add(entry.id)
       }
       if (![...entries.values()].some(entry => pendingRetryable(entry) && !pausedSends.has(entry.id))) clearSendRetry()
+      watchOfflineSends()
       return
     }
     clearSendRetry()
     for (const id of pausedSends) { const entry = entries.get(id); if (entry) { entry.failed = false; attemptStarts.set(entry.id, performance.now()) } }
     pausedSends.clear()
+    watchOfflineSends()
     // The callback can run inside construction/resume, before configure settles.
     queueMicrotask(() => pump())
   }
   let stopOnline
+  let requestedUrgency = 0
   let sendRetryTimer
   let sendRetryDelay = SEND_RETRY_MIN_MS
   let messenger
@@ -152,6 +164,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       }
     },
     changed: entry => {
+      watchOfflineSends()
       if (!entry.prepared && (entry.status === 'saved' || entry.cancelled)) cleanupEntry(entry)
       else if (!closed && available) pumpRemote()
     }
@@ -559,7 +572,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       emit()
     } finally { sendControllers.delete(entry.id); releaseForeground() }
   }
-  function stopOnlineRetry () { stopOnline?.(); stopOnline = undefined }
+  function stopOnlineRetry () { stopOnline?.(); stopOnline = undefined; requestedUrgency = 0 }
   // Transient availability failures without an active messenger pause retain
   // bounded retries. Observed pauses wait exclusively for their release.
   function clearSendRetry () {
@@ -591,21 +604,47 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     sendRetryTimer.unref?.()
   }
   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.
+    const waiting = [...entries.values()].filter(entry => entry.peer !== owner && peers.has(entry.peer) && entry.status !== 'saved' && !entry.cancelled && !cancelled.has(entry.id) && !entry.prepared?.accepted && (!entry.failed || pendingRetryable(entry)) &&
+      (offlineSends.has(entry.id) || (!networkConfirmed && messengerStatus?.pauseReasons.includes('network'))))
+    for (const id of networkUrgency.keys()) {
+      const entry = entries.get(id)
+      if (!entry || entry.status === 'saved' || entry.cancelled || cancelled.has(id)) networkUrgency.delete(id)
+    }
+    if (closed || !available || !waiting.length) { stopOnlineRetry(); return }
+    const deadline = Math.max(0, ...waiting.map(entry => networkUrgency.get(entry.id) ?? 0))
+    if (stopOnline && deadline === requestedUrgency) return
+    const previous = stopOnline
+    requestedUrgency = deadline
+    const startedAt = _now()
+    // Replacing a subscription retains the shared loop and its backoff. This is
+    // only done when a new user action extends the window, never per chunk/retry.
     stopOnline = _onOnline(() => {
       stopOnlineRetry()
       if (closed || !available) return
+      networkConfirmed = true
+      for (const entry of waiting) debug(entry, 'network-confirmed', undefined, { elapsedMs: _now() - startedAt })
       for (const id of offlineSends) {
         const entry = entries.get(id)
         if (entry?.retryable) { entry.failed = false; attemptStarts.set(entry.id, performance.now()) }
       }
       offlineSends.clear()
+      // The messenger's automatic recovery owns its network pause; the same
+      // monitor also notifies that recovery job. Never resume explicit pauses.
       return schedule()
+    }, {
+      expediteForMs: Math.max(0, deadline - _now()),
+      ...(onDebug
+        ? {
+            onDebug: measure => {
+              const entry = waiting[0]
+              debug(entry, measure.stage, undefined, measure)
+            }
+          }
+        : {})
     })
+    previous?.()
   }
+
   async function pumpLocal () {
     if (!available || closed || !storage) return
     if (localSaving) { relocal = true; return }
@@ -738,6 +777,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       const next = new Set([...values].filter(peer => peer !== owner))
       if (next.size === peers.size && [...next].every(peer => peers.has(peer))) return configuring
       peers.clear(); for (const peer of next) peers.add(peer)
+      watchOfflineSends()
       preparation.reconcile(peers)
       if (pendingDecryptionPeer && !peers.has(pendingDecryptionPeer)) {
         pendingDecryptionPeer = null
@@ -757,7 +797,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
       const changed = available !== (value === true)
       available = value === true
       if (!changed && !available) return
-      stopOnlineRetry(); offlineSends.clear()
+      if (changed || !available) { stopOnlineRetry(); offlineSends.clear() }
+      if (!available) { networkUrgency.clear(); networkConfirmed = false }
       if (available) resetSendRetry()
       else clearSendRetry()
       if (changed) lifecycle++
@@ -778,6 +819,8 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     async enqueue ({ peer, event, context = [], requiredFiles = [], deletion = false, attemptStartedAt }) {
       if (closed || !available || (peer !== owner && !peers.has(peer))) throw new Error('CHAT_UNAVAILABLE')
       if (attemptStartedAt !== undefined && (!Number.isFinite(attemptStartedAt) || attemptStartedAt < 0)) throw new ValidationError('INVALID_ATTEMPT_STARTED_AT')
+      const urgencyUntil = _now() + 30000
+      const urgencyLifecycle = lifecycle
       const releaseForeground = foreground.enter()
       enqueuing++
       try {
@@ -797,17 +840,26 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
         // An accepted durable intent survives shutdown/locking for replay. Only
         // explicit cancellation removes it; no late callback or work is admitted.
         if (closed) return id
-        entries.set(id, entry); emit(); pump()
+        entries.set(id, entry)
+        if (peer !== owner && available && lifecycle === urgencyLifecycle) networkUrgency.set(id, urgencyUntil)
+        watchOfflineSends(); emit(); pump()
         if (available && peer !== owner) preparePeer(peer).catch(() => {})
         return id
       } finally { releaseForeground(); enqueuing--; settled() }
     },
     async retry (id) {
-      offlineSends.delete(id); pausedSends.delete(id); watchOfflineSends()
       if (storageBlocked) inboxRecovery.start({ immediate: true })
       await ready()
       const entry = entries.get(id)
-      if (entry) { attemptStarts.set(id, performance.now()); journal.retry(); entry.failed = false; resetSendRetry(); if (entry.peer !== owner) preparePeer(entry.peer).catch(() => {}); return pump() }
+      if (!entry) return
+      if (entry.peer !== owner && entry.status !== 'saved' && available) networkUrgency.set(id, _now() + 30000)
+      // Renew while the old wait is still subscribed, preserving the monitor's
+      // generation/backoff even if this session is its only consumer.
+      watchOfflineSends()
+      offlineSends.delete(id); pausedSends.delete(id)
+      attemptStarts.set(id, performance.now()); journal.retry(); entry.failed = false; resetSendRetry()
+      if (entry.peer !== owner) preparePeer(entry.peer).catch(() => {})
+      return pump()
     },
     async cancel (id) {
       cancelled.add(id)
@@ -821,7 +873,7 @@ export function createPrivateMessageSession ({ owner, signer, eventStore, messag
     close () {
       return (closeWork ??= (async () => {
         closed = true; available = false; lifecycle++
-        stopOnlineRetry(); offlineSends.clear(); activeDownloads.clear(); pendingPriorityRanges.clear()
+        stopOnlineRetry(); offlineSends.clear(); networkUrgency.clear(); activeDownloads.clear(); pendingPriorityRanges.clear()
         clearSendRetry(); inboxRecovery.stop(); preparation.close(); foreground.close(); pausedSends.clear()
         for (const controller of sendControllers.values()) controller.abort()
         await Promise.allSettled([configuring, initialized, messengerWork, fileSetupWork])