libp2r2p 0.10.10 → 0.10.12

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`.
@@ -360,6 +364,26 @@ Low-level relay sockets, subscriptions, message parsing, and serialization are
 internal implementation details; use `RelayPool` or the `relayPool` singleton
 from `libp2r2p/relay`.
 
+`getEvents` and `getEventsGenerator` accept `deduplicateAcrossRelays` (boolean,
+default `true`). With `false`, a matching event is delivered once per relay,
+while repeated IDs from the same relay remain suppressed. Each occurrence owns
+its `meta.relay`; callbacks still run immediately and deadlines, EOSE handling,
+and per-relay filter limits are unchanged. The callback/generator item remains
+`{ type: 'event', event, relay }`, and the completed query remains
+`{ result, errors, success }`. The option does not extend to the live or feed
+generators. Callers that need replication coverage can aggregate the returned
+copies by event ID; missing responses do not prove absence from a relay.
+
+Publication errors retain their existing `reason` objects and may expose
+`category`: `connection` (WebSocket establishment), `transport` (socket send or
+close), `relay` (an explicit negative `OK`), or `timeout` (missing confirmation).
+Native messages, codes, nested causes and aggregate errors remain available;
+WebSocket closure details use `closeCode`, `closeReason`, and `wasClean` rather
+than overwriting a native `code`. A timeout can retain a preceding socket error
+as its cause without claiming that the relay rejected the event. Authentication
+wrappers preserve this context. Local failures can remain uncategorized.
+Event metadata is internal and is removed by `sendEvent` before serialization.
+
 The same public subpath exports `getRelaysByPubkey(pubkeys)`, which discovers
 the latest NIP-65 relay list for every requested pubkey through `seedRelays`,
 normalizes and deduplicates its public relay URLs, and falls back to the first

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.12",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",

package/relay/constants/index.js

@@ -1,7 +1,8 @@
 // Used only to discover users' NIP-65 relay lists (kind:10002).
 export const seedRelays = [
   'wss://relay.44billion.net',
-  'wss://purplepag.es',
+  // Disabled 2026-09-08: offline for some days
+  // 'wss://purplepag.es',
   'wss://user.kindpag.es',
   'wss://relay.nos.social',
   // Disabled 2026-08-05: accepted kind:10002 with OK but did not broadcast it
@@ -15,6 +16,7 @@ export const seedRelays = [
 export const freeRelays = [
   'wss://relay.44billion.net',
   'wss://nos.lol',
+  'wss://relay.dreamith.to',
   'wss://relay.primal.net'
 ]
 

package/relay/helpers/error.js

@@ -0,0 +1,30 @@
+// Adds transport context without replacing native messages, codes or causes.
+export function categorizeRelayError (reason, category, fallback = 'RELAY_OPERATION_FAILED') {
+  const error = reason instanceof Error ? reason : new Error(String(reason || fallback))
+  try {
+    Object.defineProperty(error, 'category', { value: category, enumerable: true, configurable: true })
+    return error
+  } catch {
+    const wrapped = error instanceof AggregateError
+      ? new AggregateError(error.errors, error.message, { cause: error })
+      : new Error(error.message, { cause: error })
+    wrapped.name = error.name
+    if (error.code !== undefined) wrapped.code = error.code
+    wrapped.category = category
+    return wrapped
+  }
+}
+
+// A timeout indicates missing confirmation, even when a socket error preceded it.
+export function relayTimeoutError (message, cause) {
+  return categorizeRelayError(new Error(message, cause ? { cause } : undefined), 'timeout')
+}
+
+// WebSocket close codes are distinct from native system error codes.
+export function relayCloseError (event, category, cause) {
+  const error = new Error(event?.reason || 'CONNECTION_CLOSED', cause ? { cause } : undefined)
+  if (event?.code !== undefined) error.closeCode = event.code
+  if (event?.reason !== undefined) error.closeReason = event.reason
+  if (event?.wasClean !== undefined) error.wasClean = event.wasClean
+  return categorizeRelayError(error, category)
+}

package/relay/helpers/publish.js

@@ -1,7 +1,8 @@
 import { maybeUnref } from './timer.js'
+import { relayTimeoutError } from './error.js'
 
 function publishTimeoutError () {
-  return new Error('PUBLISH_TIMEOUT')
+  return relayTimeoutError('PUBLISH_TIMEOUT')
 }
 
 // Resolves once any relay accepts the event, all relays reject, an optional

package/relay/services/relay-connection.js

@@ -1,6 +1,7 @@
 import { isValidEvent } from '../../event/index.js'
 import { ValidationError } from '../../error/index.js'
 import { maybeUnref } from '../helpers/timer.js'
+import { categorizeRelayError, relayCloseError, relayTimeoutError } from '../helpers/error.js'
 
 const DEFAULT_CONNECT_TIMEOUT = 3000
 const DEFAULT_OPERATION_TIMEOUT = 30000
@@ -44,6 +45,7 @@ export class RelayConnection {
   #connectPromise = null
   #challenge = null
   #serial = 0
+  #lastTransportError = null
   #subscriptions = new Map()
   #publishes = new Map()
   #authentications = new Map()
@@ -60,14 +62,22 @@ export class RelayConnection {
     this.onauth = null
   }
 
+  // Exposes socket context to the pool's operation-wide publication deadline.
+  get lastTransportError () { return this.#lastTransportError }
+
   async connect ({ timeout = DEFAULT_CONNECT_TIMEOUT, signal } = {}) {
     if (this.ws?.readyState === 1) return
     if (this.#connectPromise) return await this.#connectPromise
     if (signal?.aborted) throw new Error('CONNECT_ABORTED')
-    if (typeof this.#WebSocket !== 'function') throw new Error('WEBSOCKET_UNAVAILABLE')
+    if (typeof this.#WebSocket !== 'function') throw categorizeRelayError(new Error('WEBSOCKET_UNAVAILABLE'), 'connection')
 
+    this.#lastTransportError = null
     this.#connectPromise = new Promise((resolve, reject) => {
-      const socket = new this.#WebSocket(this.url)
+      let socket
+      try { socket = new this.#WebSocket(this.url) } catch (error) {
+        reject(categorizeRelayError(error, 'connection'))
+        return
+      }
       this.ws = socket
       let settled = false
       const finish = (reason) => {
@@ -81,18 +91,21 @@ export class RelayConnection {
         } else resolve()
       }
       const onAbort = () => finish(new Error('CONNECT_ABORTED'))
-      const timer = timeout === null ? null : maybeUnref(setTimeout(() => finish(new Error('CONNECT_TIMEOUT')), timeout))
+      const timer = timeout === null ? null : maybeUnref(setTimeout(() => finish(relayTimeoutError('CONNECT_TIMEOUT')), timeout))
       signal?.addEventListener('abort', onAbort, { once: true })
 
       socket.onopen = () => finish()
       socket.onerror = event => {
-        const reason = errorFrom(event?.error, 'CONNECTION_ERROR')
+        const reason = categorizeRelayError(event?.error, settled ? 'transport' : 'connection', 'CONNECTION_ERROR')
         if (!settled) finish(reason)
-        else this.onerror?.(reason)
+        else {
+          this.#lastTransportError = reason
+          this.onerror?.(reason)
+        }
       }
       socket.onmessage = event => { this.#handleMessage(event).catch(reason => this.onerror?.(reason)) }
       socket.onclose = event => {
-        if (!settled) finish(new Error('CONNECTION_CLOSED'))
+        if (!settled) finish(relayCloseError(event, 'connection'))
         if (this.ws === socket) this.ws = null
         this.#handleClose(event)
       }
@@ -101,8 +114,11 @@ export class RelayConnection {
   }
 
   send (message) {
-    if (this.ws?.readyState !== 1) throw new Error('CONNECTION_CLOSED')
-    this.ws.send(message)
+    if (this.ws?.readyState !== 1) throw relayCloseError(null, 'transport', this.#lastTransportError)
+    try { this.ws.send(message) } catch (error) {
+      this.#lastTransportError = categorizeRelayError(error, 'transport')
+      throw this.#lastTransportError
+    }
   }
 
   subscribe (filters, handlers = {}) {
@@ -141,7 +157,7 @@ export class RelayConnection {
   #sendEventOperation (type, event, map, timeoutCode) {
     if (map.has(event.id)) return map.get(event.id).promise
     const deferred = Promise.withResolvers()
-    const timer = maybeUnref(setTimeout(() => this.#settleEvent(map, event.id, new Error(timeoutCode)), this.publishTimeout))
+    const timer = maybeUnref(setTimeout(() => this.#settleEvent(map, event.id, relayTimeoutError(timeoutCode, this.#lastTransportError)), this.publishTimeout))
     map.set(event.id, { ...deferred, timer, promise: deferred.promise })
     try { this.send(JSON.stringify([type, event])) } catch (error) {
       this.#settleEvent(map, event.id, error)
@@ -210,7 +226,7 @@ export class RelayConnection {
       return
     }
     if (data[0] === 'OK') {
-      const reason = data[2] === true ? null : errorFrom(data[3], 'EVENT_REJECTED')
+      const reason = data[2] === true ? null : categorizeRelayError(data[3], 'relay', 'EVENT_REJECTED')
       this.#settleEvent(this.#publishes, data[1], reason, data[3])
       this.#settleEvent(this.#authentications, data[1], reason, data[3])
       return
@@ -229,7 +245,7 @@ export class RelayConnection {
 
   #handleClose (event) {
     this.#challenge = null
-    const reason = errorFrom(event?.reason, 'CONNECTION_CLOSED')
+    const reason = relayCloseError(event, 'transport', this.#lastTransportError)
     for (const [id, subscription] of this.#subscriptions) {
       this.#subscriptions.delete(id)
       subscription.handlers.onclose?.(reason)
@@ -244,7 +260,7 @@ export class RelayConnection {
     const socket = this.ws
     this.ws = null
     this.#challenge = null
-    const reason = new Error('CONNECTION_CLOSED')
+    const reason = relayCloseError(null, 'transport', this.#lastTransportError)
     for (const [id, subscription] of this.#subscriptions) {
       this.#subscriptions.delete(id)
       subscription.handlers.onclose?.()

package/relay/services/relay-pool.js

@@ -2,6 +2,7 @@ import { ValidationError } from '../../error/index.js'
 import { decodeHll, encodeHll, estimateHllCount, mergeHll } from '../helpers/hll.js'
 import { createPublishSettlements, firstFulfillment, publishSummary } from '../helpers/publish.js'
 import { maybeUnref } from '../helpers/timer.js'
+import { categorizeRelayError } from '../helpers/error.js'
 import { normalizeRelayUrl } from '../../url/index.js'
 import { RelayConnection } from './relay-connection.js'
 
@@ -102,6 +103,8 @@ class Nip42AuthenticationError extends Error {
   constructor (reason) {
     super(reason.message, { cause: reason })
     this.name = 'Nip42AuthenticationError'
+    if (reason.category) this.category = reason.category
+    if (reason.code !== undefined) this.code = reason.code
   }
 }
 
@@ -143,7 +146,7 @@ export class RelayPool {
       try {
         await relay.close()
       } catch {}
-      throw error
+      throw categorizeRelayError(error, error?.category ?? 'connection')
     }
 
     // Only reset idle timeout when no live subscriptions are holding this relay open.
@@ -335,8 +338,10 @@ export class RelayPool {
 
   // Collects a one-shot relay read. The first EOSE with events opens a short
   // grace window; null disables that window so callers wait for every relay or
-  // the operation deadline. Event ids are deduplicated across relay responses.
-  async getEvents (filter, relays, { timeout = 5000, timeoutAfterFirstEose = 500, callback, signal } = {}) {
+  // the operation deadline. Disabling cross-relay deduplication still suppresses
+  // repeated ids from the same relay; callbacks remain immediate in both modes.
+  async getEvents (filter, relays, { timeout = 5000, timeoutAfterFirstEose = 500, callback, signal, deduplicateAcrossRelays = true } = {}) {
+    if (typeof deduplicateAcrossRelays !== 'boolean') throw new ValidationError('INVALID_DEDUPLICATE_ACROSS_RELAYS')
     const urls = normalizedRelayUrls(relays)
     if (!urls.length) return { result: [], errors: [], success: false }
     if (signal?.aborted) throw new Error('Aborted')
@@ -346,7 +351,7 @@ export class RelayPool {
     const normalCloseUrls = new Set()
     const errors = []
     const events = []
-    const eventIds = new Set()
+    const eventIds = deduplicateAcrossRelays ? new Set() : null
     let completed = 0
     let isResolved = false
     let eoseTimer = null
@@ -411,6 +416,7 @@ export class RelayPool {
       if (timeout !== null) timeoutTimer = maybeUnref(setTimeout(timeoutPending, timeout))
 
       for (const url of urls) {
+        const seenIds = eventIds ?? new Set()
         this.#getRelay(url).then(relay => {
           if (isResolved || !pending.has(url)) return
           let hasEvents = false
@@ -432,10 +438,8 @@ export class RelayPool {
             onevent: (event) => {
               if (isResolved || !pending.has(url)) return
               hasEvents = true
-              // Keep filter-limit accounting per relay, but only expose one copy of
-              // a matching event when several relays return the same id.
-              if (!event?.id || !eventIds.has(event.id)) {
-                if (event?.id) eventIds.add(event.id)
+              if (!event?.id || !seenIds.has(event.id)) {
+                if (event?.id) seenIds.add(event.id)
                 event.meta = { relay: url }
                 events.push(event)
                 if (callback) callback({ type: 'event', event, relay: url })
@@ -859,6 +863,10 @@ export class RelayPool {
     // Starts before connection work so every relay shares one real deadline.
     const settlement = createPublishSettlements(sendPromises, timeout, {
       onSettled: (settlement, index) => {
+        if (settlement.reason?.category === 'timeout' && !settlement.reason.cause) {
+          const relay = this.#relays.get(normalizeRelayUrl(urls[index]))
+          if (relay?.lastTransportError) settlement.reason.cause = relay.lastTransportError
+        }
         notifyRelayResult(onRelayResult, relayResultForSettlement(urls[index], settlement))
       }
     })