libp2r2p 0.10.10 → 0.10.11

package/README.md

@@ -8,6 +8,10 @@ the transport and discovery surface. The package was born to distribute the
 private messenger reference implementation, and it also carries a few Nostr
 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.
+
 ## Private Messenger
 
 The main API is `createPrivateMessenger` from `libp2r2p/private-messenger`.

package/network/README.md

@@ -0,0 +1,20 @@
+# Connectivity
+
+`isOnline({ signal } = {})` returns a boolean after probing public connectivity
+endpoints, or immediately returns `false` when the browser reports offline.
+Concurrent calls without a signal share one check. A supplied abort signal
+cancels the caller's independent check. Each endpoint has a five-second timeout.
+
+`onOnline(handler)` returns an idempotent unsubscribe function. It notifies
+asynchronously after confirmed initial connectivity and each detected recovery.
+The native `online` event only triggers a check; it is not sufficient evidence.
+Listeners share a monitor with retries at 5, 15, 30, then 60 seconds (20% jitter),
+checks on focus/visibility/network changes, and a 60-second interval while online.
+Unsubscribing the last listener removes timers/listeners and aborts its probe.
+Handler failures are isolated and logged. `createConnectivityMonitor(options)`
+creates an independent monitor with an optional custom `check({ signal })`.
+
+Successful probes do not guarantee a particular relay or HTTP server is reachable.
+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.

package/network/index.js

@@ -1,25 +1,31 @@
-export async function isOnline () {
-  if (typeof navigator !== 'undefined' && typeof navigator.onLine === 'boolean') {
-    if (!navigator.onLine) return false
-  }
-  return hasInternetConnectivity()
-}
+import { ValidationError } from '../error/index.js'
 
+const RETRY_DELAYS = [5000, 15000, 30000, 60000]
 const CONNECTIVITY_PROBE_URLS = [
   { url: 'https://www.gstatic.com/generate_204' },
   { url: 'https://connectivitycheck.gstatic.com/generate_204' },
   { url: 'https://captive.apple.com/hotspot-detect.html' },
   { method: 'GET', url: 'https://connectivity-check.ubuntu.com' }
 ]
+let sharedCheck
+
+// Treat the browser's offline flag as a fast failure; confirm online status with a probe.
+export async function isOnline ({ signal } = {}) {
+  if (signal?.aborted) throw signal.reason
+  if (globalThis.navigator?.onLine === false) return false
+  if (signal) return hasInternetConnectivity(signal)
+  sharedCheck ??= hasInternetConnectivity().finally(() => { sharedCheck = null })
+  return sharedCheck
+}
 
-async function hasInternetConnectivity () {
-  const candidates = shuffle(CONNECTIVITY_PROBE_URLS)
-  for (const candidate of candidates) {
+async function hasInternetConnectivity (signal) {
+  for (const candidate of shuffle(CONNECTIVITY_PROBE_URLS)) {
+    if (signal?.aborted) throw signal.reason
     try {
-      await ping(candidate.url, { method: candidate.method })
+      await ping(candidate.url, { method: candidate.method, signal })
       return true
-    } catch (err) {
-      console.warn('connectivity probe failed', candidate.url, err?.message ?? err)
+    } catch {
+      if (signal?.aborted) throw signal.reason
     }
   }
   return false
@@ -34,35 +40,143 @@ function shuffle (list) {
   return copy
 }
 
-async function ping (url, { method = 'HEAD', timeout = 5000 } = {}) {
-  const abortController = typeof AbortController === 'function' ? new AbortController() : null
-  let timerId = null
-
-  const fetchPromise = fetch(url, {
-    method,
-    mode: 'no-cors',
-    cache: 'no-store',
-    redirect: 'follow',
-    signal: abortController?.signal
-  })
-
-  const completionPromise = fetchPromise.finally(() => {
-    if (timerId != null) clearTimeout(timerId)
-  })
-
-  const timeoutPromise = new Promise((_resolve, reject) => {
-    timerId = setTimeout(() => {
-      if (abortController) abortController.abort()
+// Bound each probe and release its timer and abort listener on every exit path.
+async function ping (url, { method = 'HEAD', timeout = 5000, signal } = {}) {
+  const controller = new AbortController()
+  let timer
+  let onAbort
+  const stopped = new Promise((_resolve, reject) => {
+    onAbort = () => {
+      controller.abort(signal.reason)
+      reject(signal.reason)
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+    timer = setTimeout(() => {
+      controller.abort()
       reject(new Error('PING_TIMEOUT'))
     }, timeout)
+    if (signal?.aborted) onAbort()
   })
+  try {
+    await Promise.race([
+      fetch(url, { method, mode: 'no-cors', cache: 'no-store', redirect: 'follow', signal: controller.signal }),
+      stopped
+    ])
+  } finally {
+    clearTimeout(timer)
+    signal?.removeEventListener('abort', onAbort)
+  }
+}
 
-  await Promise.race([completionPromise, timeoutPromise])
-  return true
+// A monitor owns one probe loop, regardless of how many consumers subscribe.
+export function createConnectivityMonitor ({
+  check = isOnline,
+  eventTarget = globalThis.window,
+  document = globalThis.document,
+  _setTimeout = globalThis.setTimeout,
+  _clearTimeout = globalThis.clearTimeout,
+  _random = Math.random,
+  reportError = error => console.error('Online listener failed', error)
+} = {}) {
+  if (typeof check !== 'function') throw new ValidationError('INVALID_CONNECTIVITY_CHECK')
+  const listeners = new Set()
+  const setTimer = (...args) => Reflect.apply(_setTimeout, globalThis, args)
+  const clearTimer = (...args) => Reflect.apply(_clearTimeout, globalThis, args)
+  let session
+
+  function deliver (entry, current) {
+    if (entry.delivered || !listeners.has(entry) || session !== current) return
+    entry.delivered = true
+    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)]
+    current.timer = setTimer(() => {
+      current.timer = null
+      return probe(current)
+    }, Math.round(delay * (0.8 + _random() * 0.4)))
+    current.timer?.unref?.()
+  }
+
+  async function probe (current) {
+    if (session !== current || current.pending) return
+    if (current.timer != null) clearTimer(current.timer)
+    current.timer = null
+    current.pending = true
+    try {
+      const online = await check({ signal: current.controller.signal })
+      if (session !== current) return
+      current.online = online === true && globalThis.navigator?.onLine !== false
+      if (current.online) {
+        current.retry = 0
+        for (const entry of [...listeners]) deliver(entry, current)
+      } else {
+        for (const entry of listeners) entry.delivered = false
+      }
+    } catch {
+      if (session !== current) return
+      current.online = false
+      for (const entry of listeners) entry.delivered = false
+    } finally {
+      current.pending = false
+      schedule(current)
+    }
+  }
+
+  function start () {
+    const current = { online: false, retry: 0, timer: null, pending: false, controller: new AbortController() }
+    session = current
+    current.wake = () => { probe(current) }
+    current.connectionChanged = () => {
+      current.online = false
+      current.retry = 0
+      for (const entry of listeners) entry.delivered = false
+      current.wake()
+    }
+    current.visible = () => { if (document?.visibilityState !== 'hidden') current.wake() }
+    eventTarget?.addEventListener('online', current.connectionChanged)
+    eventTarget?.addEventListener('offline', current.connectionChanged)
+    eventTarget?.addEventListener('focus', current.wake)
+    document?.addEventListener('visibilitychange', current.visible)
+    queueMicrotask(current.wake)
+  }
+
+  function stop () {
+    const current = session
+    session = null
+    if (current.timer != null) clearTimer(current.timer)
+    current.controller.abort()
+    eventTarget?.removeEventListener('online', current.connectionChanged)
+    eventTarget?.removeEventListener('offline', current.connectionChanged)
+    eventTarget?.removeEventListener('focus', current.wake)
+    document?.removeEventListener('visibilitychange', current.visible)
+  }
+
+  // Notify once on confirmed initial connectivity, then after each detected reconnection.
+  function onOnline (handler) {
+    if (typeof handler !== 'function') throw new ValidationError('INVALID_ONLINE_HANDLER')
+    const entry = { handler, delivered: false }
+    listeners.add(entry)
+    if (!session) start()
+    else {
+      const current = session
+      queueMicrotask(() => { probe(current) })
+    }
+    return () => {
+      if (!listeners.delete(entry)) return
+      if (!listeners.size) stop()
+    }
+  }
+
+  return { onOnline }
 }
 
+let defaultMonitor
+
+// Share probes, capped backoff and wake-up listeners across callers in this realm.
 export function onOnline (handler) {
-  const listener = () => handler()
-  window.addEventListener('online', listener)
-  return () => window.removeEventListener('online', listener)
+  defaultMonitor ??= createConnectivityMonitor()
+  return defaultMonitor.onOnline(handler)
 }

package/package.json

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