libp2r2p 0.11.15 → 0.11.16

package/README.md

@@ -936,9 +936,22 @@ also admits relay policy refusals (`blocked:`, `restricted:`, `auth-required:`,
 Local authentication denials, invalid events and unknown errors qualify for
 neither policy. Predicates classify individual native errors; callers decide
 how to handle mixed per-relay outcomes and application-specific aggregates.
-Existing rate-limit parsing preserves numeric positive `retry_after` seconds as
-`retryAfterMs` and absolute `retryAt`, bounded to five minutes. Schedulers must
-use the later of their backoff deadline and `retryAt`, not add the two delays.
+`parseRelayRetryAdvice(reason, extra, { now = Date.now() })`, exported by
+`libp2r2p/relay`, returns `{ retryAt, retryAfterMs? }` or `null`. It only interprets
+leading `rate-limited:` refusals. Optional `retry_at` is a Unix timestamp in
+seconds (fractions allowed), converted to milliseconds. Finite positive absolute
+advice takes precedence over `retry_after`, including when already expired;
+expired advice does not restart a relative wait. Future waits are capped at five
+minutes from processing. Missing/invalid absolute advice falls back to finite
+positive relative seconds, capped at 300. A valid relative value is retained as
+`retryAfterMs` even when the absolute deadline wins. Schedulers wait until
+max(local backoff deadline, retryAt), never sum the two or renew the deadline on
+online notifications.
+
+The optional Nostr extension works with older relays that only send
+`retry_after` and older consumers that ignore `retry_at`. Neither field supplies
+provenance or retry eligibility: `local`, `origin`, `retryable`, category and code
+claims in extras are ignored. Native messages, causes and codes remain intact.
 
 ## Binary encodings
 
@@ -1059,7 +1072,7 @@ user-facing send error.
 
 ### Relay backpressure and bounded synchronization (0.11.7)
 
-Optional numeric `retry_after` seconds on relay `CLOSED` and rejected `OK`
+Optional `retry_at` Unix seconds or numeric `retry_after` seconds on relay `CLOSED` and rejected `OK`
 responses are preserved as `retryAfterMs` and `retryAt` on native relay errors.
 Only `rate-limited:` responses apply this advice; invalid values are ignored
 and delays are capped at five minutes. New operations on that connection wait

package/package.json

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

package/relay/helpers/error.js

@@ -1,3 +1,5 @@
+import { parseRelayRetryAdvice } from './retry-advice.js'
+
 // 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))
@@ -29,14 +31,10 @@ export function relayCloseError (event, category, cause) {
   return categorizeRelayError(error, category)
 }
 
-// retry_after is an optional relay extension, in seconds. Bound remote advice
-// to five minutes; invalid metadata must not stall unrelated operations.
+// Keep native diagnostics and attach only bounded timing advice. An absolute
+// deadline survives delayed delivery through a launcher-owned relay bridge.
 export function relayRejectionError (reason, extra, fallback) {
   const error = categorizeRelayError(reason, 'relay', fallback)
-  const seconds = extra?.retry_after
-  if (error.message.startsWith('rate-limited:') && typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0) {
-    error.retryAfterMs = Math.min(seconds, 300) * 1000
-    error.retryAt = Date.now() + error.retryAfterMs
-  }
+  Object.assign(error, parseRelayRetryAdvice(error.message, extra))
   return error
 }

package/relay/helpers/retry-advice.js

@@ -0,0 +1,18 @@
+// Nostr transport extensions, in seconds. Timing advice is bounded and never
+// supplies an error category, provenance or a routing/retry policy.
+export function parseRelayRetryAdvice (reason, extra, { now = Date.now() } = {}) {
+  if (typeof reason !== 'string' || !reason.startsWith('rate-limited:') ||
+      !extra || typeof extra !== 'object' || Array.isArray(extra) || !Number.isFinite(now)) return null
+
+  const after = extra.retry_after
+  const retryAfterMs = typeof after === 'number' && Number.isFinite(after) && after > 0
+    ? Math.min(after, 300) * 1000
+    : undefined
+  const at = extra.retry_at
+  const absolute = typeof at === 'number' && Number.isFinite(at) && at > 0 && Number.isFinite(at * 1000)
+    ? Math.min(at * 1000, now + 300000)
+    : undefined
+  const retryAt = absolute ?? (retryAfterMs === undefined ? undefined : now + retryAfterMs)
+  if (retryAt === undefined) return null
+  return { ...(retryAfterMs === undefined ? {} : { retryAfterMs }), retryAt }
+}

package/relay/index.js

@@ -1,5 +1,6 @@
 export { freeRelays, nappRelays, seedRelays } from './constants/index.js'
 export { isRetryableRelayFailure, isReplaceableRelayFailure } from './helpers/failure.js'
+export { parseRelayRetryAdvice } from './helpers/retry-advice.js'
 export { pickRelaysForPubkeys } from './helpers/routing.js'
 export { RelayPool, relayPool } from './services/relay-pool.js'
 export { getLatestEventsByPubkey } from './services/events.js'