libp2r2p 0.10.23 → 0.10.25

package/network/README.md

@@ -1,18 +1,30 @@
 # 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.
+`isOnline({ signal, strict = false } = {})` returns a boolean after probing
+public connectivity endpoints, or immediately returns `false` when the browser
+reports offline. The first candidate probes alone with a 2.5-second timeout; if
+it is still pending after 1 second, the remaining candidates start in parallel
+with four-second timeouts and the first success wins, keeping the worst case near
+five seconds instead of serializing every timeout. Concurrent calls without a
+signal share one check per mode. A supplied abort signal cancels the caller's
+independent check immediately.
+
+By default a probe only proves the endpoint is reachable (`no-cors`), so HTTP
+errors and captive portals still resolve. With `strict: true`, probes use
+CORS-enabled endpoints and require `response.ok` plus the expected body marker,
+which rejects captive portals and error pages. `createConnectivityMonitor({
+strict })` and `onOnline(handler, { strict })` select the same mode; shared
+checks, monitors and listeners are kept per mode.
 
 `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 })`.
+Listeners of a mode 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 })` and `strict` default.
 
 Successful probes do not guarantee a particular relay or HTTP server is reachable.
 Handle request failures, cancellations, and timeouts separately. Browsers can

package/network/index.js

@@ -7,28 +7,74 @@ const CONNECTIVITY_PROBE_URLS = [
   { url: 'https://captive.apple.com/hotspot-detect.html' },
   { method: 'GET', url: 'https://connectivity-check.ubuntu.com' }
 ]
-let sharedCheck
+// CORS-enabled endpoints let the strict mode validate the response instead of
+// merely proving the host is reachable.
+const STRICT_CONNECTIVITY_PROBE_URLS = [
+  { url: 'https://captive.apple.com/hotspot-detect.html', method: 'GET', marker: 'Success' },
+  { url: 'https://1.1.1.1/cdn-cgi/trace', method: 'GET', marker: 'ip=' },
+  { url: 'https://cloudflare.com/cdn-cgi/trace', method: 'GET', marker: 'ip=' }
+]
+const FIRST_PROBE_TIMEOUT_MS = 2500
+const HEDGE_DELAY_MS = 1000
+const REMAINING_PROBE_TIMEOUT_MS = 4000
+const sharedChecks = new Map()
 
-// Treat the browser's offline flag as a fast failure; confirm online status with a probe.
-export async function isOnline ({ signal } = {}) {
+// Treat the browser's offline flag as a fast failure; confirm online status with
+// probes. The default mode only proves the hosts are reachable, while strict mode
+// requires CORS responses with an expected body and rejects captive portals.
+export async function isOnline ({ signal, strict = false } = {}) {
   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
+  if (signal) return hasInternetConnectivity(signal, strict)
+  const key = strict ? 'strict' : 'lenient'
+  if (!sharedChecks.has(key)) {
+    sharedChecks.set(key, hasInternetConnectivity(undefined, strict).finally(() => { sharedChecks.delete(key) }))
+  }
+  return sharedChecks.get(key)
 }
 
-async function hasInternetConnectivity (signal) {
-  for (const candidate of shuffle(CONNECTIVITY_PROBE_URLS)) {
-    if (signal?.aborted) throw signal.reason
+// The first candidate answers the common case alone. When it is still pending
+// after HEDGE_DELAY_MS, the remaining candidates race in parallel so one slow or
+// blocked host cannot serialize every timeout.
+async function hasInternetConnectivity (signal, strict) {
+  if (signal?.aborted) throw signal.reason
+  const candidates = shuffle(strict ? STRICT_CONNECTIVITY_PROBE_URLS : CONNECTIVITY_PROBE_URLS)
+  const [first, ...rest] = candidates
+  if (!first) return false
+  const controller = new AbortController()
+  const onAbort = () => controller.abort(signal?.reason)
+  signal?.addEventListener('abort', onAbort, { once: true })
+  if (signal?.aborted) onAbort()
+  let hedgeTimer
+  let onHedgeAbort
+  try {
+    let startHedge
+    const firstAttempt = ping(first, { strict, signal: controller.signal, timeout: FIRST_PROBE_TIMEOUT_MS })
+    const hedge = new Promise((resolve, reject) => {
+      startHedge = resolve
+      hedgeTimer = setTimeout(resolve, HEDGE_DELAY_MS)
+      if (signal) {
+        onHedgeAbort = () => reject(signal.reason)
+        signal.addEventListener('abort', onHedgeAbort, { once: true })
+        if (signal.aborted) onHedgeAbort()
+      }
+    }).then(() => Promise.any(rest.map(candidate => ping(candidate, { strict, signal: controller.signal, timeout: REMAINING_PROBE_TIMEOUT_MS }))))
+    // A definitive failure releases the hedge immediately; a slow probe waits
+    // for the hedge delay so a working network still costs one request.
+    firstAttempt.catch(() => startHedge())
     try {
-      await ping(candidate.url, { method: candidate.method, signal })
+      await Promise.any([firstAttempt, hedge])
       return true
     } catch {
       if (signal?.aborted) throw signal.reason
+      return false
     }
+  } finally {
+    clearTimeout(hedgeTimer)
+    if (onHedgeAbort) signal?.removeEventListener('abort', onHedgeAbort)
+    controller.abort()
+    signal?.removeEventListener('abort', onAbort)
   }
-  return false
 }
 
 function shuffle (list) {
@@ -41,7 +87,8 @@ function shuffle (list) {
 }
 
 // Bound each probe and release its timer and abort listener on every exit path.
-async function ping (url, { method = 'HEAD', timeout = 5000, signal } = {}) {
+async function ping (candidate, { strict = false, timeout, signal } = {}) {
+  if (signal?.aborted) throw signal.reason
   const controller = new AbortController()
   let timer
   let onAbort
@@ -58,19 +105,29 @@ async function ping (url, { method = 'HEAD', timeout = 5000, signal } = {}) {
     if (signal?.aborted) onAbort()
   })
   try {
-    await Promise.race([
-      fetch(url, { method, mode: 'no-cors', cache: 'no-store', redirect: 'follow', signal: controller.signal }),
+    const response = await Promise.race([
+      fetch(candidate.url, {
+        method: candidate.method ?? (strict ? 'GET' : 'HEAD'),
+        mode: strict ? 'cors' : 'no-cors',
+        cache: 'no-store',
+        redirect: 'follow',
+        signal: controller.signal
+      }),
       stopped
     ])
+    if (!strict) return
+    if (!response.ok) throw new Error('PING_STATUS')
+    if (!(await response.text()).includes(candidate.marker)) throw new Error('PING_BODY')
   } finally {
     clearTimeout(timer)
     signal?.removeEventListener('abort', onAbort)
   }
 }
 
-// A monitor owns one probe loop, regardless of how many consumers subscribe.
+// A monitor owns one probe loop per mode, regardless of how many consumers subscribe.
 export function createConnectivityMonitor ({
-  check = isOnline,
+  check,
+  strict = false,
   eventTarget = globalThis.window,
   document = globalThis.document,
   _setTimeout = globalThis.setTimeout,
@@ -78,7 +135,8 @@ export function createConnectivityMonitor ({
   _random = Math.random,
   reportError = error => console.error('Online listener failed', error)
 } = {}) {
-  if (typeof check !== 'function') throw new ValidationError('INVALID_CONNECTIVITY_CHECK')
+  if (check !== undefined && typeof check !== 'function') throw new ValidationError('INVALID_CONNECTIVITY_CHECK')
+  const runCheck = check ?? (options => isOnline({ ...options, strict }))
   const listeners = new Set()
   const setTimer = (...args) => Reflect.apply(_setTimeout, globalThis, args)
   const clearTimer = (...args) => Reflect.apply(_clearTimeout, globalThis, args)
@@ -106,7 +164,7 @@ export function createConnectivityMonitor ({
     current.timer = null
     current.pending = true
     try {
-      const online = await check({ signal: current.controller.signal })
+      const online = await runCheck({ signal: current.controller.signal })
       if (session !== current) return
       current.online = online === true && globalThis.navigator?.onLine !== false
       if (current.online) {
@@ -173,10 +231,15 @@ export function createConnectivityMonitor ({
   return { onOnline }
 }
 
-let defaultMonitor
+const defaultMonitors = new Map()
 
-// Share probes, capped backoff and wake-up listeners across callers in this realm.
-export function onOnline (handler) {
-  defaultMonitor ??= createConnectivityMonitor()
-  return defaultMonitor.onOnline(handler)
+// Share probes, capped backoff and wake-up listeners per mode in this realm.
+export function onOnline (handler, { strict = false } = {}) {
+  const key = strict ? 'strict' : 'lenient'
+  let monitor = defaultMonitors.get(key)
+  if (!monitor) {
+    monitor = createConnectivityMonitor({ strict })
+    defaultMonitors.set(key, monitor)
+  }
+  return monitor.onOnline(handler)
 }

package/package.json

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

package/relay/services/relay-pool.js

@@ -136,13 +136,23 @@ export class RelayPool {
   #liveSubCounts = new Map() // url -> number of active live subscriptions
   #timeout = 30000 // 30 seconds
   #createRelay
+  #WebSocket
   #admission
 
-  constructor ({ _createRelay = url => new RelayConnection(url), ...capacity } = {}) {
-    this.#createRelay = _createRelay
+  constructor ({ _createRelay, WebSocket: WebSocketImpl, ...capacity } = {}) {
+    this.#WebSocket = WebSocketImpl
+    this.#createRelay = _createRelay ?? (url => new RelayConnection(url, this.#WebSocket ? { WebSocket: this.#WebSocket } : undefined))
     this.#admission = new ReadAdmission(capacity)
   }
 
+  // Injects the WebSocket implementation used by new pooled connections (e.g.
+  // a launcher-owned relay multiplexer). Existing connections keep the
+  // implementation they were created with.
+  setWebSocket (WebSocketImpl) {
+    if (typeof WebSocketImpl !== 'function') throw new ValidationError('INVALID_WEBSOCKET_IMPLEMENTATION')
+    this.#WebSocket = WebSocketImpl
+  }
+
   #scheduleIdleDisconnect (url) {
     clearTimeout(this.#relayTimeouts.get(url))
     this.#relayTimeouts.set(url, maybeUnref(setTimeout(() => {