libp2r2p 0.10.11 → 0.10.12

package/README.md

@@ -364,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.10.11",
+  "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))
       }
     })