libp2r2p 0.11.6 → 0.11.8

package/README.md

@@ -339,7 +339,7 @@ must not delete a kind `3560` event, whether or not that event has an `s` tag.
 ### Storage Maintenance
 
 While an outgoing private message is being assembled, the messenger keeps
-encrypted envelope rows and router chunks in `sessionStorage`. They are
+encrypted envelope rows in `sessionStorage` (router fragments are encoded on demand, without a second stored copy). They are
 removed when the send finishes, but an interrupted browser operation can leave
 them behind until cleanup runs.
 
@@ -965,3 +965,59 @@ latency, and short-lived channel/recipient preferences avoid recently refused
 relays without changing receive subscriptions. See the
 [session coordinator](private-messenger/session/README.md) for deferred offline
 attempts and final failure notifications.
+
+
+### Relay backpressure and bounded synchronization (0.11.7)
+
+Optional 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
+within their existing deadlines; active subscriptions remain live and `CLOSE`
+never waits. Cancelled or timed-out operations cannot be sent later. A rejection
+is still reported to the caller; this does not silently republish failed events.
+
+`createEventReplyPacker` and `createMissingMessageReplyPacker` accept
+`bytesPerChunk` (default 128 KiB of UTF-8 JSONL), in addition to the existing
+100-record maximum. One indivisible oversized record is sent alone. Consumers
+must keep failed requests pending; no record is truncated or discarded. Final
+publication failures retain the payload/index for retry. Outbound channel
+fragmentation streams from prepared encrypted rows, cleans partial writes and
+removes failed new keys from the temporary-storage registry. It does not raise
+the browser's Web Storage quota or delete unrelated application data.
+
+
+### Private subscription recovery (0.11.8)
+
+`privateChannel.subscribe()` returns `{ ready, done, close }`. `done` always
+resolves to `{ status: 'closed' | 'ended' | 'failed', error? }` after processing
+stops. Explicit cancellation is `closed`; a naturally exhausted stream is
+`ended`; a terminal error is `failed` and still reaches `onError`.
+
+`private-message.watch()` accepts an optional asynchronous
+`onSubscriptionState({ state, relay, since, until?, error? })` callback.
+`interrupted` identifies the conservative lower recovery boundary; after a
+buffer overflow, every affected channel must finish this callback before its
+shared relay subscription reopens. `ready` follows successful initial relay
+readiness on the replacement. Callbacks and completions are generation-fenced.
+Equal watch settings cannot keep a dead subscription registered as active.
+
+Overflow recovery keeps one timer per relay with exponential 1–30 second
+backoff and 20% jitter, reset after a stable minute. Other relays remain live.
+Removal, pause and close cancel pending work. Fragment storage stays scoped to
+the same session across replacement subscriptions. Permanent refusals remain
+reported and do not trigger this automatic retry loop.
+
+PrivateMessenger persists each interrupted interval before reopening, then
+uses paged `fetchHistory` to repair the gap while listening for new messages.
+Transient history failures retry with bounded backoff and honor `retryAt`;
+dense-page limits, permanent refusals and unknown failures stay pending without
+an automatic loop. Disabled historical recovery restores only live input.
+Existing persisted ranges, checkpoints, recovery windows and ack/nack semantics
+are unchanged; newer live arrivals cannot erase a pending interval.
+
+`RELAY_LIVE_BUFFER_FULL` retains `relay`, `phase`, `recoverySince` and a bounded
+`buffer` diagnostic: stage (`delivery`, `reconnect`, `history-wait`), queued
+count/bytes, incoming bytes, limits and oldest queued age. Queue bytes are UTF-8
+serialized volume, not heap use. Diagnostics never retain event contents or
+filters. Existing 1,000-item / 8-MiB live limits are unchanged.

package/package.json

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

package/private-channel/helpers/chunks.js

@@ -78,23 +78,6 @@ function encryptedPayload ({ messageSecretKey, event }) {
   return nip44v3.encrypt(messageSecretKey, messagePubkey, ROUTER_KIND, '', JSON.stringify(event))
 }
 
-function appendLine (chunk, line, id, chunkIndex, temporaryStorage) {
-  while (line.length) {
-    const available = JSONL_CHUNK_BYTES - chunk.length
-    chunk = appendBytes(chunk, line.slice(0, available))
-    line = line.slice(available)
-    if (chunk.length === JSONL_CHUNK_BYTES) {
-      temporaryStorage.setItem(tempKey(id, chunkIndex++), bytesToBase64(chunk))
-      chunk = new Uint8Array()
-    }
-  }
-  return { chunk, chunkIndex }
-}
-
-function appendRow (chunk, row, id, chunkIndex, temporaryStorage) {
-  return appendLine(chunk, encoder.encode(`${row}\n`), id, chunkIndex, temporaryStorage)
-}
-
 function joinByteChunks (parts) {
   let length = 0
   const decoded = parts.map(part => {
@@ -249,20 +232,42 @@ export function preparedRowIndexesForReceivers (preparedRows, receivers) {
   return indexes
 }
 
+// Keep only one encoded row and one fragment in memory; do not stage a
+// second, Base64-expanded copy of the entire message in Web Storage.
+export function preparedChunkCount (preparedRows, rowIndexes = preparedRows.rowIndexes) {
+  let bytes = 0
+  for (const index of [0, ...rowIndexes]) bytes += encoder.encode(readPreparedRow(preparedRows, index)).length + 1
+  return Math.max(1, Math.ceil(bytes / JSONL_CHUNK_BYTES))
+}
+
+export function * preparedChunks (preparedRows, rowIndexes = preparedRows.rowIndexes) {
+  let chunk = new Uint8Array()
+  for (const index of [0, ...rowIndexes]) {
+    const row = encoder.encode(`${readPreparedRow(preparedRows, index)}\n`)
+    for (let offset = 0; offset < row.length;) {
+      const size = Math.min(JSONL_CHUNK_BYTES - chunk.length, row.length - offset)
+      chunk = appendBytes(chunk, row.subarray(offset, offset + size))
+      offset += size
+      if (chunk.length === JSONL_CHUNK_BYTES) {
+        yield bytesToBase64(chunk)
+        chunk = new Uint8Array()
+      }
+    }
+  }
+  if (chunk.length) yield bytesToBase64(chunk)
+}
+
 export function writeChunksFromPreparedRows (preparedRows, rowIndexes = preparedRows?.rowIndexes || []) {
   const temporaryStorage = storageFor(preparedRows?.temporaryStorage)
   const id = temporaryId()
-  let chunk = new Uint8Array()
   let chunkIndex = 0
   try {
-    ;({ chunk, chunkIndex } = appendRow(chunk, readPreparedRow(preparedRows, 0), id, chunkIndex, temporaryStorage))
-    for (const rowIndex of rowIndexes) {
-      ;({ chunk, chunkIndex } = appendRow(chunk, readPreparedRow(preparedRows, rowIndex), id, chunkIndex, temporaryStorage))
+    for (const content of preparedChunks(preparedRows, rowIndexes)) {
+      temporaryStorage.setItem(tempKey(id, chunkIndex++), content)
     }
-    if (chunk.length || chunkIndex === 0) temporaryStorage.setItem(tempKey(id, chunkIndex++), bytesToBase64(chunk))
     return { id, total: chunkIndex, ownContentPubkey: preparedRows.ownContentPubkey || '' }
   } catch (err) {
-    cleanupChunks(id, chunkIndex + 1, temporaryStorage)
+    cleanupChunks(id, chunkIndex, temporaryStorage)
     throw err
   }
 }

package/private-channel/helpers/subscription-error.js

@@ -5,7 +5,7 @@ export function subscriptionError (reason, relay) {
   const error = reason instanceof AggregateError
     ? new AggregateError(reason.errors, message, { cause: reason })
     : new Error(message, { cause: reason })
-  for (const key of ['name', 'code', 'category', 'closeCode', 'closeReason', 'wasClean']) {
+  for (const key of ['name', 'code', 'category', 'retryAfterMs', 'retryAt', 'closeCode', 'closeReason', 'wasClean', 'phase', 'buffer', 'recoverySince']) {
     if (reason?.[key] !== undefined) error[key] = reason[key]
   }
   error.operation = 'private-channel.subscribe'

package/private-channel/index.js

@@ -13,16 +13,15 @@ import * as nip44v3 from '../nip44-v3/index.js'
 import { relayPool } from '../relay/index.js'
 import { JSONL_CHUNK_BYTES, NYM_CARRIER_CHUNK_CHARS } from './helpers/chunk-size.js'
 import {
-  cleanupChunks,
   cleanupEnvelopeRows,
   decodeChunkLines,
   prepareEnvelopeRows,
   preparedRowIndexesForReceivers,
-  readChunkContent,
   readPreparedRow,
   receiverPubkeys,
   receiverPubkeysWithoutContentKeys,
-  writeChunksFromPreparedRows
+  preparedChunkCount,
+  preparedChunks
 } from './helpers/chunks.js'
 import { EXPIRATION_SECONDS, MAX_EVENT_BYTES, NYM_CARRIER_KIND, PRIVATE_BROADCAST_KIND, ROUTER_KIND } from './constants/index.js'
 import { eventByteLength, hasImkcTag, makeNymCarrierEvent, makeRouterEvent, nowSeconds, readChunkTag, readFileChunkIndex, readIdTag, readImkcProof, readImkcTag, readReceiverTag, readSenderTag } from './helpers/event.js'
@@ -121,15 +120,20 @@ async function prepareRoutedMessage ({ senderSigner, imkcSigner, privateChannelS
     rowScope: channelPubkey,
     temporaryStorageArea
   })
-  const imkcPubkey = preparedRows.ownContentPubkey || ''
-  const imkcProof = imkcPubkey ? await makeImkcProof({ senderSigner, senderPubkey, imkcPubkey }) : ''
-  return {
-    senderPubkey,
-    channelPubkey,
-    channelReaderPubkey,
-    preparedRows,
-    imkcPubkey,
-    imkcProof
+  try {
+    const imkcPubkey = preparedRows.ownContentPubkey || ''
+    const imkcProof = imkcPubkey ? await makeImkcProof({ senderSigner, senderPubkey, imkcPubkey }) : ''
+    return {
+      senderPubkey,
+      channelPubkey,
+      channelReaderPubkey,
+      preparedRows,
+      imkcPubkey,
+      imkcProof
+    }
+  } catch (error) {
+    cleanupEnvelopeRows(preparedRows)
+    throw error
   }
 }
 
@@ -139,45 +143,36 @@ async function * wrapPreparedEvents ({ privateChannelSigner, receivers, receiver
   const receiverPubkeyList = receiverPubkeys(receivers)
   const routerReceiverTag = receiverTag ?? (receiverPubkeyList.length === 1 ? receiverPubkeyList[0] : '')
   const rowIndexes = preparedRowIndexesForReceivers(context.preparedRows, receivers)
-  const {
-    id,
-    total
-  } = writeChunksFromPreparedRows(context.preparedRows, rowIndexes)
-  const temporaryStorage = context.preparedRows.temporaryStorage
-
-  try {
-    if (onPreparedSeed) {
-      const router = makeRouterEvent({ pubkey: routerPubkey, senderPubkey: context.senderPubkey, imkcPubkey: context.imkcPubkey, imkcProof: context.imkcProof, receiverPubkey: routerReceiverTag, chunkIndex: 0, chunkTotal: 1, fileChunkIndex, content: '' })
-      const payloadRow = readPreparedRow(context.preparedRows, 0)
-      for (const rowIndex of rowIndexes) {
-        await onPreparedSeed({ channelPubkey: context.channelPubkey, router, jsonl: `${payloadRow}\n${readPreparedRow(context.preparedRows, rowIndex)}\n` })
-      }
-    }
-    for (let index = 0; index < total; index++) {
-      const content = readChunkContent(id, index, temporaryStorage)
-      const router = finalizeEvent(makeRouterEvent({
-        pubkey: routerPubkey,
-        senderPubkey: context.senderPubkey,
-        imkcPubkey: context.imkcPubkey,
-        imkcProof: context.imkcProof,
-        receiverPubkey: routerReceiverTag,
-        fileChunkIndex,
-        chunkIndex: index,
-        chunkTotal: total,
-        content
-      }), routerSeckey)
-      const createdAt = nowSeconds()
-      const outer = await privateChannelSigner.signEvent({
-        kind: PRIVATE_BROADCAST_KIND,
-        created_at: createdAt,
-        tags: privateBroadcastTags({ deletionPubkey, createdAt, expirationSeconds }),
-        content: await nip44v3EncryptText(privateChannelSigner, context.channelReaderPubkey, PRIVATE_BROADCAST_KIND, JSON.stringify(router))
-      })
-      if (eventByteLength(outer) > MAX_EVENT_BYTES) throw new ValidationError('EVENT_TOO_LARGE')
-      yield outer
+  const total = preparedChunkCount(context.preparedRows, rowIndexes)
+  if (onPreparedSeed) {
+    const router = makeRouterEvent({ pubkey: routerPubkey, senderPubkey: context.senderPubkey, imkcPubkey: context.imkcPubkey, imkcProof: context.imkcProof, receiverPubkey: routerReceiverTag, chunkIndex: 0, chunkTotal: 1, fileChunkIndex, content: '' })
+    const payloadRow = readPreparedRow(context.preparedRows, 0)
+    for (const rowIndex of rowIndexes) {
+      await onPreparedSeed({ channelPubkey: context.channelPubkey, router, jsonl: `${payloadRow}\n${readPreparedRow(context.preparedRows, rowIndex)}\n` })
     }
-  } finally {
-    cleanupChunks(id, total, temporaryStorage)
+  }
+  let index = 0
+  for (const content of preparedChunks(context.preparedRows, rowIndexes)) {
+    const router = finalizeEvent(makeRouterEvent({
+      pubkey: routerPubkey,
+      senderPubkey: context.senderPubkey,
+      imkcPubkey: context.imkcPubkey,
+      imkcProof: context.imkcProof,
+      receiverPubkey: routerReceiverTag,
+      fileChunkIndex,
+      chunkIndex: index++,
+      chunkTotal: total,
+      content
+    }), routerSeckey)
+    const createdAt = nowSeconds()
+    const outer = await privateChannelSigner.signEvent({
+      kind: PRIVATE_BROADCAST_KIND,
+      created_at: createdAt,
+      tags: privateBroadcastTags({ deletionPubkey, createdAt, expirationSeconds }),
+      content: await nip44v3EncryptText(privateChannelSigner, context.channelReaderPubkey, PRIVATE_BROADCAST_KIND, JSON.stringify(router))
+    })
+    if (eventByteLength(outer) > MAX_EVENT_BYTES) throw new ValidationError('EVENT_TOO_LARGE')
+    yield outer
   }
 }
 
@@ -989,6 +984,7 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
     })
 
   async function consumeEvents () {
+    let result = { status: 'ended' }
     try {
       for await (const item of events) {
         if (controller.signal.aborted) continue
@@ -996,19 +992,26 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
         else if (item.type === 'event') await processOuterEvent(item.event)
       }
     } catch (error) {
-      if (!controller.signal.aborted && error?.message !== 'Aborted') onError?.(error)
+      if (!controller.signal.aborted) {
+        const diagnostic = subscriptionError(error, error?.relay)
+        result = { status: 'failed', error: diagnostic }
+        // Consumer error callbacks must not turn `done` into an unhandled rejection.
+        try { onError?.(diagnostic) } catch {}
+      }
     } finally {
       processOuterEvent.close()
     }
+    return controller.signal.aborted ? { status: 'closed' } : result
   }
 
-  const consumePromise = consumeEvents()
+  const done = consumeEvents()
 
   return {
     ready: events.ready || Promise.resolve(),
+    done,
     close () {
       controller.abort()
-      return consumePromise
+      return done
     }
   }
 }

package/private-message/index.js

@@ -1,3 +1,4 @@
+import { normalizeRelayUrl } from '../url/index.js'
 import { isValidEvent } from '../event/index.js'
 import { ValidationError } from '../error/index.js'
 import { generateKeypair } from '../key/index.js'
@@ -144,9 +145,10 @@ async function ownPrivateChannelPubkey (signer) {
 
 // A session owns its callbacks and relay reads. Other consumers, including
 // the other side of the same shared channel, cannot overwrite or stop them.
-export function createPrivateMessageSession () {
+export function createPrivateMessageSession ({ _setTimeout = setTimeout, _clearTimeout = clearTimeout, _now = Date.now, _random = Math.random } = {}) {
   const watchesByChannel = new Map()
   const subsByRelay = new Map()
+  const relayRecoveries = new Map()
   let nextWatchRevision = 1
   let requestSequence = 0
   const watchRequests = new Map()
@@ -301,11 +303,113 @@ export function createPrivateMessageSession () {
     }
   }
 
-  function rebuildSubscriptions ({ _subscribe = privateChannel.subscribe, gracefulClose = true } = {}) {
+  function reportSubscriptionError (channels, error) {
+    try { watchCallbacks([...channels][0]).onError?.(error) } catch {}
+  }
+
+  function cancelRelayRecovery (relay) {
+    const recovery = relayRecoveries.get(relay)
+    if (recovery?.timer != null) _clearTimeout(recovery.timer)
+    relayRecoveries.delete(relay)
+  }
+
+  async function notifyInterruption (relay, recovery) {
+    const channels = desiredRelayState().get(relay) || []
+    // Each consumer must persist its gap before this shared subscription restarts.
+    // Keep acknowledgments on partial failure; new/replaced watches participate too.
+    const outcomes = await Promise.allSettled([...channels].map(async channel => {
+      const watch = watchesByChannel.get(channel)
+      if (recovery.notified.get(channel) === watch) return
+      await watch.callbacks.onSubscriptionState?.({ state: 'interrupted', relay, error: recovery.error, since: recovery.since })
+      recovery.notified.set(channel, watch)
+    }))
+    const failed = outcomes.find(result => result.status === 'rejected')
+    if (failed) throw failed.reason
+    if (relayRecoveries.get(relay) === recovery && [...(desiredRelayState().get(relay) || [])].some(channel => recovery.notified.get(channel) !== watchesByChannel.get(channel))) {
+      await notifyInterruption(relay, recovery)
+    }
+  }
+
+  function scheduleRelayRecovery (relay, recovery) {
+    if (relayRecoveries.get(relay) !== recovery || recovery.timer || !desiredRelayState().has(relay)) return
+    const delay = Math.min(30000, recovery.delay * (0.8 + _random() * 0.4))
+    recovery.delay = Math.min(30000, recovery.delay * 2)
+    recovery.timer = _setTimeout(async () => {
+      recovery.timer = null
+      try {
+        await notifyInterruption(relay, recovery)
+        if (relayRecoveries.get(relay) !== recovery || !desiredRelayState().has(relay)) return
+        await rebuildSubscriptions({ retryRelay: relay })
+      } catch (error) {
+        reportSubscriptionError(desiredRelayState().get(relay) || [], error)
+        scheduleRelayRecovery(relay, recovery)
+      }
+    }, delay)
+    recovery.timer?.unref?.()
+  }
+
+  function subscriptionEnded (relay, entry, result) {
+    if (subsByRelay.get(relay) !== entry) return
+    subsByRelay.delete(relay)
+    if (result.status === 'closed' || !desiredRelayState().has(relay)) return
+    const error = result.error || Object.assign(new Error('PRIVATE_CHANNEL_SUBSCRIPTION_ENDED'), { code: 'PRIVATE_CHANNEL_SUBSCRIPTION_ENDED', relay })
+    const previous = relayRecoveries.get(relay)
+    const recovery = {
+      error,
+      since: Math.min(entry.since, error.recoverySince ?? entry.since, previous?.since ?? Infinity),
+      delay: entry.readyAt !== undefined && _now() - entry.readyAt >= 60000 ? 1000 : (previous?.delay || entry.retryDelay || 1000),
+      notified: new Map(), timer: null
+    }
+    if (/^(auth-required:|restricted:|blocked:|invalid:|pow:)/.test(error.message || '') || error.name === 'ValidationError' ||
+        (error.code !== 'RELAY_LIVE_BUFFER_FULL' && !previous)) {
+      cancelRelayRecovery(relay)
+      notifyInterruption(relay, recovery).catch(error => reportSubscriptionError(entry.channels, error))
+      return
+    }
+    cancelRelayRecovery(relay)
+    relayRecoveries.set(relay, recovery)
+    // Start persistence immediately, without overlapping a later retry callback.
+    recovery.preparing = notifyInterruption(relay, recovery).catch(error => reportSubscriptionError(entry.channels, error))
+    recovery.preparing.finally(() => scheduleRelayRecovery(relay, recovery))
+  }
+
+  async function subscriptionReady (relay, entry, ready) {
+    if (subsByRelay.get(relay) !== entry) return
+    const recovery = relayRecoveries.get(relay)
+    if (!ready?.relays?.includes(relay)) {
+      if (recovery) {
+        const error = ready?.errors?.[0]?.reason || Object.assign(new Error('RELAY_LIVE_NOT_READY'), { code: 'RELAY_LIVE_NOT_READY', relay })
+        subscriptionEnded(relay, entry, { status: 'failed', error })
+        await entry.sub.close()
+      }
+      return
+    }
+    entry.readyAt = _now()
+    if (!recovery) return
+    try {
+      const until = Math.floor(_now() / 1000)
+      await Promise.all([...entry.channels].map(async channel => {
+        if (subsByRelay.get(relay) !== entry || !watchesByChannel.has(channel)) return
+        await watchCallbacks(channel).onSubscriptionState?.({ state: 'ready', relay, since: recovery.since, until })
+      }))
+      if (subsByRelay.get(relay) === entry && relayRecoveries.get(relay) === recovery) {
+        entry.retryDelay = recovery.delay
+        cancelRelayRecovery(relay)
+        await rebuildSubscriptions()
+      }
+    } catch (error) {
+      reportSubscriptionError(entry.channels, error)
+      subscriptionEnded(relay, entry, { status: 'failed', error })
+      await entry.sub.close()
+    }
+  }
+
+  function rebuildSubscriptions ({ _subscribe = privateChannel.subscribe, gracefulClose = true, retryRelay } = {}) {
     subscribe = _subscribe === privateChannel.subscribe ? subscribe : _subscribe
     _subscribe = subscribe
     const desired = desiredRelayState()
     const closing = []
+    for (const relay of relayRecoveries.keys()) if (!desired.has(relay)) cancelRelayRecovery(relay)
 
     for (const [relay, current] of subsByRelay) {
       const nextChannels = desired.get(relay)
@@ -321,6 +425,8 @@ export function createPrivateMessageSession () {
       const current = subsByRelay.get(relay)
       if (doesSubscriptionMatch(current, channels)) continue
 
+      if (relayRecoveries.has(relay) && retryRelay !== relay) continue
+      const since = nowSeconds()
       const channelList = [...channels]
       const firstWatch = watchesByChannel.get(channelList[0])
       const sub = _subscribe({
@@ -345,7 +451,7 @@ export function createPrivateMessageSession () {
         ignoredGroupTtlMs: maxWatchNumber(channelList, 'ignoredGroupTtlMs'),
         ignoredGroupMaxEntries: maxWatchNumber(channelList, 'ignoredGroupMaxEntries'),
         limit: 0,
-        since: nowSeconds(),
+        since,
         liveOnly: true,
         onChunk: handleChunk,
         onEvent: (event, outer, meta) => {
@@ -358,14 +464,24 @@ export function createPrivateMessageSession () {
           return dispatchSeedEvent(seed)
         },
         onContentKeyUsage: dispatchContentKeyUsage,
-        onError: err => firstWatch.callbacks.onError?.(err)
+        onError: err => reportSubscriptionError(channels, err)
       })
 
-      subsByRelay.set(relay, {
+      const entry = {
+        since,
         channels: new Set(channels),
         revisions: watchRevisionsForChannels(channelList),
         sub
-      })
+      }
+      subsByRelay.set(relay, entry)
+      if (sub.done) sub.done.then(result => subscriptionEnded(relay, entry, result)).catch(error => reportSubscriptionError(channels, error))
+      if (sub.ready) {
+        sub.ready.then(ready => subscriptionReady(relay, entry, ready)).catch(error => {
+          reportSubscriptionError(channels, error)
+          subscriptionEnded(relay, entry, { status: 'failed', error })
+          Promise.resolve(sub.close()).catch(() => {})
+        })
+      }
       if (current) {
         const close = closeSubscription(current.sub, gracefulClose)
         if (close) closing.push(close)
@@ -393,6 +509,7 @@ export function createPrivateMessageSession () {
     onSeed,
     onChunk,
     onContentKeyUsage,
+    onSubscriptionState,
     onError,
     receivedChunkTtlMs,
     receivedChunkMaxBytes,
@@ -403,6 +520,7 @@ export function createPrivateMessageSession () {
     _subscribe = privateChannel.subscribe
   }) {
     if (!relays?.length) throw new ValidationError('NO_RELAYS')
+    relays = uniq(relays.map(normalizeRelayUrl))
     const request = ++requestSequence
     const channelList = uniq(channels?.length ? channels : [await ownPrivateChannelPubkey(privateChannelSigner)])
     for (const channel of channelList) {
@@ -411,9 +529,8 @@ export function createPrivateMessageSession () {
     const ownPubkey = receiverPubkey || await receiverSigner?.getPublicKey?.()
     if (identity !== undefined && identity !== ownPubkey) throw new ValidationError('PRIVATE_MESSAGE_IDENTITY_MISMATCH')
     identity = ownPubkey
-    const callbacks = { onAsk, onReply, onTell, onYell, onNym, onMessage, onSeed, onChunk, onContentKeyUsage, onError }
+    const callbacks = { onAsk, onReply, onTell, onYell, onNym, onMessage, onSeed, onChunk, onContentKeyUsage, onSubscriptionState, onError }
 
-    let changed = false
     for (const channel of channelList) {
       if (watchRequests.get(channel) !== request) continue
       const next = {
@@ -457,10 +574,9 @@ export function createPrivateMessageSession () {
         continue
       }
       watchesByChannel.set(channel, next)
-      changed = true
     }
 
-    if (changed) await rebuildSubscriptions({ _subscribe })
+    await rebuildSubscriptions({ _subscribe })
     return () => {
       const owned = channelList.filter(channel => watchRequests.get(channel) === request)
       return unwatch(owned)

package/private-messenger/helpers/recovery-retry.js

@@ -0,0 +1,26 @@
+// Retry operational interruptions, never dense-page limits or permanent refusals.
+export function recoveryRetryDelay (errors, delay) {
+  let retry = false
+  let blocked = false
+  let retryAt = 0
+  const seen = new Set()
+  function visit (error) {
+    if (!error || seen.has(error)) return
+    seen.add(error)
+    if (error.code === 'PRIVATE_CHANNEL_HISTORY_PAGE_LIMIT' || error.name === 'ValidationError' ||
+        /^(auth-required:|restricted:|blocked:|invalid:|pow:)/.test(error.message || '')) blocked = true
+    if (['transport', 'timeout'].includes(error.category) ||
+        ['QuotaExceededError', 'InvalidStateError', 'UnknownError'].includes(error.name) ||
+        /^(rate-limited:|error:)/.test(error.message || '') ||
+        ['RELAY_LIVE_BUFFER_FULL', 'RELAY_LIVE_NOT_READY'].includes(error.code)) retry = true
+    if (Number.isFinite(error.retryAt)) retryAt = Math.max(retryAt, Math.min(Date.now() + 300000, error.retryAt))
+    for (const child of error.errors || []) visit(child)
+    for (const entry of error.relays || []) {
+      if (['timeout', 'cutoff', 'closed'].includes(entry.status)) retry = true
+      visit(entry.error)
+    }
+    visit(error.cause)
+  }
+  errors.forEach(visit)
+  return retry && !blocked ? Math.max(delay, retryAt - Date.now()) : null
+}

package/private-messenger/index.js

@@ -1,3 +1,4 @@
+import { recoveryRetryDelay } from './helpers/recovery-retry.js'
 // Expected use:
 // const messenger = await createPrivateMessenger({
 //   userSigner,
@@ -293,6 +294,8 @@ export class PrivateMessenger {
     this.capacityCheck = null
     this.capacityRequiredBytes = 0
     this.reloadGapTimers = new Map()
+    this.liveInterruptions = new Map()
+    this.liveRecoveryTimers = new Map()
     this.watchRevisionByChannel = new Map()
     this.presenceTimers = new Map()
     this.stopRelayListWatcher = null
@@ -1103,6 +1106,7 @@ export class PrivateMessenger {
         onContentKeyUsage: usage => this.handleContentKeyUsage(pubkey, usage),
         receivedChunkTtlMs: this.receivedChunkTtlMsFor(channel),
         receivedChunkIndexedDB: this._indexedDB,
+        onSubscriptionState: state => this.handleSubscriptionState(pubkey, state),
         onError: err => this.onError?.(err)
       })
       if (this.closePromise || this.pauseReasons.size || !this.desiredChannels.has(pubkey) || revision !== (this.watchRevisionByChannel.get(pubkey) || 0)) {
@@ -1136,6 +1140,76 @@ export class PrivateMessenger {
     return this
   }
 
+  async handleSubscriptionState (pubkey, { state, relay, since, until }) {
+    if (this.closePromise || this.pauseReasons.size || !this.desiredChannels.has(pubkey)) return
+    if (!this.offlineRecoverySecondsFor(pubkey)) return
+    let interrupted = this.liveInterruptions.get(pubkey)
+    if (state === 'interrupted') {
+      if (!interrupted) { interrupted = new Map(); this.liveInterruptions.set(pubkey, interrupted) }
+      const start = Math.min(interrupted.get(relay) ?? Infinity, since)
+      interrupted.set(relay, start)
+      this.cancelReloadGap(pubkey)
+      for (const controller of this.recoveryControllers) {
+        if (controller.channelPubkey === pubkey) { controller.liveInterrupted = true; controller.abort() }
+      }
+      this.recordInterruption([pubkey], start)
+      this.addOfflineRange(pubkey, Math.max(0, start - this.offlineSkewSeconds), nowSeconds())
+      // This rejection prevents the session from reopening the shared relay.
+      await this.flushStateWrites()
+    } else if (state === 'ready' && interrupted?.has(relay)) {
+      const start = interrupted.get(relay)
+      this.addOfflineRange(pubkey, Math.max(0, start - this.offlineSkewSeconds), until)
+      if (interrupted.size === 1) this.closeOpenOfflineRanges([pubkey])
+      await this.flushStateWrites()
+      if (this.closePromise || this.pauseReasons.size || !this.desiredChannels.has(pubkey) || this.liveInterruptions.get(pubkey) !== interrupted) return
+      interrupted.delete(relay)
+      if (!interrupted.size) this.liveInterruptions.delete(pubkey)
+      this.scheduleLiveRecovery(pubkey)
+    }
+  }
+
+  cancelLiveRecovery (pubkey) {
+    const work = this.liveRecoveryTimers.get(pubkey)
+    if (work?.timer != null) this._clearTimeout(work.timer)
+    this.liveRecoveryTimers.delete(pubkey)
+  }
+
+  scheduleLiveRecovery (pubkey) {
+    const current = this.liveRecoveryTimers.get(pubkey)
+    if (current) { current.again = true; return }
+    const work = { delay: 1000, timer: null, again: false }
+    this.liveRecoveryTimers.set(pubkey, work)
+    const isCurrent = () => this.liveRecoveryTimers.get(pubkey) === work && !this.closePromise &&
+      !this.pauseReasons.size && this.desiredChannels.has(pubkey)
+    const schedule = delay => {
+      work.timer = this._setTimeout(async () => {
+        work.timer = null
+        if (!isCurrent()) return
+        work.again = false
+        let errors
+        try {
+          // A ready notification may overtake cancellation of the previous scan.
+          // Let that scan retain its range, then start a fresh recovery attempt.
+          await this.recoveries.get(pubkey)
+          if (!isCurrent()) return
+          errors = await this.recoverOfflineRanges([pubkey])
+        } catch (error) {
+          this.onError?.(error)
+          errors = [error]
+        }
+        if (!isCurrent()) return
+        const pending = this.readState().channels[pubkey]?.offlineRanges?.length
+        const retry = pending ? recoveryRetryDelay(errors, Math.min(30000, work.delay * (0.8 + Math.random() * 0.4))) : null
+        if (work.again || retry !== null) {
+          schedule(work.again ? 0 : retry)
+          work.delay = Math.min(30000, work.delay * 2)
+        } else this.liveRecoveryTimers.delete(pubkey)
+      }, delay)
+      work.timer?.unref?.()
+    }
+    schedule(0)
+  }
+
   recordInterruption (channels, at = nowSeconds()) {
     const state = this.readState()
     for (const pubkey of channels) {
@@ -1152,6 +1226,8 @@ export class PrivateMessenger {
     const closing = []
     for (const pubkey of channels) {
       this.cancelReloadGap(pubkey)
+      this.cancelLiveRecovery(pubkey)
+      this.liveInterruptions.delete(pubkey)
       this.watchRevisionByChannel.set(pubkey, (this.watchRevisionByChannel.get(pubkey) || 0) + 1)
       const close = this.stopByChannel.get(pubkey)?.()
       if (close?.then) closing.push(close)
@@ -2063,6 +2139,7 @@ export class PrivateMessenger {
   }
 
   async recoverOfflineRanges (channels = [...this.stopByChannel.keys()]) {
+    const failures = []
     for (const pubkey of uniq(channels)) {
       if (this.pauseReasons.size || this.closePromise || !this.desiredChannels.has(pubkey)) continue
       let work = this.recoveries.get(pubkey)
@@ -2070,11 +2147,13 @@ export class PrivateMessenger {
         work = this.recoverChannelRanges([pubkey])
         this.recoveries.set(pubkey, work)
       }
-      try { await work } finally { if (this.recoveries.get(pubkey) === work) this.recoveries.delete(pubkey) }
+      try { failures.push(...await work) } finally { if (this.recoveries.get(pubkey) === work) this.recoveries.delete(pubkey) }
     }
+    return failures
   }
 
   async recoverChannelRanges (channels) {
+    const failures = []
     const state = this.readState()
     const now = nowSeconds()
 
@@ -2125,12 +2204,14 @@ export class PrivateMessenger {
           })
           controller.signal.throwIfAborted()
           const attempt = await this.#askSeedersForRelayLeftEdgeAttempt(pubkey, range, history.oldestCreatedAt)
-          const lifecycleChanged = this.closePromise || !this.channels.has(pubkey) || !this.stopByChannel.has(pubkey) ||
+          const lifecycleChanged = controller.signal.aborted || this.closePromise || !this.channels.has(pubkey) || !this.stopByChannel.has(pubkey) ||
             (this.watchRevisionByChannel.get(pubkey) || 0) !== watchRevision
+          failures.push(...attempt.failures.map(failure => failure.error))
           if (lifecycleChanged || attempt.failures.length) remaining.push(range)
           else recoveredThrough = Math.max(recoveredThrough, range.end)
         } catch (err) {
-          this.onError?.(err)
+          if (!(controller.liveInterrupted && err === controller.signal.reason)) this.onError?.(err)
+          failures.push(err)
           remaining.push(range)
         } finally { this.recoveryControllers.delete(controller) }
       }
@@ -2145,6 +2226,7 @@ export class PrivateMessenger {
       this.writeState(fresh)
       await this.flushStateWrites()
     }
+    return failures
   }
 
   async clearChannel (pubkey) {

package/private-messenger/recovery/index.js

@@ -9,6 +9,7 @@ export const MISSING_MESSAGES_REPLY_CODE = 'missingMessages_reply_8mj8'
 export const ROUTER_SEED_RECORD_TYPE = 'routerEnvelopeRow_v1'
 export const NYM_CARRIER_SEED_RECORD_TYPE = 'nymCarrier_v1'
 
+export const DEFAULT_REPLY_BYTES_PER_CHUNK = 128 * 1024
 const DEFAULT_EVENTS_PER_CHUNK = 100
 const encoder = new TextEncoder()
 const decoder = new TextDecoder()
@@ -224,6 +225,7 @@ export function createEventReplyPacker ({
   code,
   payload = {},
   eventsPerChunk = DEFAULT_EVENTS_PER_CHUNK,
+  bytesPerChunk = DEFAULT_REPLY_BYTES_PER_CHUNK,
   recordsFromInput = eventRecordFromInput,
   sendEmptyReply = false
 }) {
@@ -231,18 +233,17 @@ export function createEventReplyPacker ({
   if (!question?.id) throw new ValidationError('QUESTION_REQUIRED')
   if (!receiverPubkey) throw new ValidationError('RECEIVER_PUBKEY_REQUIRED')
   if (!Number.isSafeInteger(eventsPerChunk) || eventsPerChunk < 1) throw new ValidationError('INVALID_EVENTS_PER_CHUNK')
+  if (!Number.isSafeInteger(bytesPerChunk) || bytesPerChunk < 1) throw new ValidationError('INVALID_BYTES_PER_CHUNK')
 
   let chunk = ''
   let chunkEvents = 0
+  let chunkBytes = 0
   let index = 0
   let finalized = false
   let published = false
 
   async function publish (isLast) {
     const jsonl = chunk
-    chunk = ''
-    chunkEvents = 0
-    published = true
     await messenger.reply({
       channelPubkey,
       question,
@@ -250,17 +251,27 @@ export function createEventReplyPacker ({
       code,
       payload: {
         ...payload,
-        index: index++,
+        index,
         isLast,
         jsonl
       }
     })
+    index++
+    chunk = ''
+    chunkEvents = 0
+    chunkBytes = 0
+    published = true
   }
 
   async function appendRecord (record, { flush = true } = {}) {
-    chunk += `${JSON.stringify(record)}\n`
+    const line = `${JSON.stringify(record)}\n`
+    const bytes = encoder.encode(line).length
+    if (chunk && (chunkBytes + bytes > bytesPerChunk || chunkEvents >= eventsPerChunk)) await publish(false)
+    chunk += line
+    chunkBytes += bytes
     chunkEvents++
-    if (flush && chunkEvents >= eventsPerChunk) await publish(false)
+    // A record is indivisible: an oversized one travels alone, never truncated.
+    if (flush && (chunkEvents >= eventsPerChunk || chunkBytes >= bytesPerChunk)) await publish(false)
   }
 
   async function appendRecords (records, { final = false } = {}) {
@@ -278,9 +289,8 @@ export function createEventReplyPacker ({
   async function finalize (input) {
     if (finalized) return
     if (input != null) await appendRecords(await recordsFromInput(input), { final: true })
+    if (chunk || sendEmptyReply || published) await publish(true)
     finalized = true
-    if (!chunk && !sendEmptyReply && !published) return
-    await publish(true)
   }
 
   return {
@@ -297,12 +307,14 @@ export function createMissingMessageReplyPacker ({
   since,
   until,
   eventsPerChunk = DEFAULT_EVENTS_PER_CHUNK,
+  bytesPerChunk = DEFAULT_REPLY_BYTES_PER_CHUNK,
   sendEmptyReply = false
 }) {
   if (!messenger?.reply) throw new ValidationError('MESSENGER_REQUIRED')
   if (!question?.id) throw new ValidationError('QUESTION_REQUIRED')
   if (!receiverPubkey) throw new ValidationError('RECEIVER_PUBKEY_REQUIRED')
   if (!Number.isSafeInteger(eventsPerChunk) || eventsPerChunk < 1) throw new ValidationError('INVALID_EVENTS_PER_CHUNK')
+  if (!Number.isSafeInteger(bytesPerChunk) || bytesPerChunk < 1) throw new ValidationError('INVALID_BYTES_PER_CHUNK')
 
   const range = backfillRequestRange(question, since, until)
   return createEventReplyPacker({
@@ -313,6 +325,7 @@ export function createMissingMessageReplyPacker ({
     code: MISSING_MESSAGES_REPLY_CODE,
     payload: { since: range.since, until: range.until },
     eventsPerChunk,
+    bytesPerChunk,
     sendEmptyReply,
     recordsFromInput: seed => compactRecordsFromSeed(seed, { receiverPubkey, since: range.since, until: range.until })
   })

package/relay/helpers/error.js

@@ -28,3 +28,15 @@ export function relayCloseError (event, category, cause) {
   if (event?.wasClean !== undefined) error.wasClean = event.wasClean
   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.
+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
+  }
+  return error
+}

package/relay/helpers/live-buffer-error.js

@@ -0,0 +1,15 @@
+// Bounded diagnostics only: never attach queued payloads or subscription filters.
+export function liveBufferError ({ relay, stage, queue, queuedBytes, incoming, incomingBytes, maxEvents, maxBytes, since }) {
+  const now = Date.now()
+  const boundaries = [since, incoming?.event?.created_at, ...queue.map(entry => entry.item?.event?.created_at)]
+    .filter(value => Number.isFinite(value) && value >= 0)
+  return Object.assign(new Error('RELAY_LIVE_BUFFER_FULL'), {
+    code: 'RELAY_LIVE_BUFFER_FULL', relay, phase: 'live-buffer',
+    recoverySince: Math.min(Math.floor(now / 1000), ...boundaries),
+    buffer: {
+      stage, queuedEvents: queue.length, queuedBytes, incomingBytes,
+      limits: { events: maxEvents, bytes: maxBytes },
+      oldestQueuedMs: queue.length ? Math.max(0, now - queue[0].receivedAt) : 0
+    }
+  })
+}

package/relay/services/relay-connection.js

@@ -1,7 +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'
+import { categorizeRelayError, relayCloseError, relayTimeoutError, relayRejectionError } from '../helpers/error.js'
 
 const DEFAULT_CONNECT_TIMEOUT = 3000
 const DEFAULT_OPERATION_TIMEOUT = 30000
@@ -50,6 +50,7 @@ export class RelayConnection {
   #publishes = new Map()
   #authentications = new Map()
   #counts = new Map()
+  #retryAt = 0
 
   constructor (url, { WebSocket: WebSocketImpl = globalThis.WebSocket } = {}) {
     this.url = url
@@ -121,47 +122,87 @@ export class RelayConnection {
     }
   }
 
+  // New work respects relay cooldowns; cleanup uses send() directly. These
+  // waits stay within the caller's existing deadline and are cancellable.
+  #dispatchWork (send, fail) {
+    let timer = null
+    let cancelled = false
+    const dispatch = () => {
+      if (cancelled) return
+      const remaining = this.#retryAt - Date.now()
+      if (remaining > 0) {
+        timer = maybeUnref(setTimeout(dispatch, remaining))
+        return
+      }
+      try { send() } catch (error) { fail(error) }
+    }
+    dispatch()
+    return () => { cancelled = true; clearTimeout(timer) }
+  }
+
+  #rejection (reason, extra, fallback) {
+    const error = relayRejectionError(reason, extra, fallback)
+    this.#retryAt = Math.max(this.#retryAt, error.retryAt || 0)
+    return error
+  }
+
   subscribe (filters, handlers = {}) {
     if (!Array.isArray(filters) || !filters.length) throw new ValidationError('SUBSCRIPTION_FILTERS_REQUIRED')
     const id = `p2r2p-sub:${++this.#serial}`
     let closed = false
+    let sent = false
     const close = () => {
       if (closed) return
       closed = true
       const subscription = this.#subscriptions.get(id)
       if (!subscription) return
       this.#subscriptions.delete(id)
-      try { this.send(JSON.stringify(['CLOSE', id])) } catch {}
+      subscription.cancelSend?.()
+      if (sent) { try { this.send(JSON.stringify(['CLOSE', id])) } catch {} }
       handlers.onclose?.()
     }
-    this.#subscriptions.set(id, { filters, handlers, close })
-    try { this.send(JSON.stringify(['REQ', id, ...filters])) } catch (error) {
+    const subscription = { filters, handlers, close, cancelSend: null }
+    this.#subscriptions.set(id, subscription)
+    subscription.cancelSend = this.#dispatchWork(() => {
+      this.send(JSON.stringify(['REQ', id, ...filters]))
+      sent = true
+    }, error => {
       this.#subscriptions.delete(id)
-      throw error
-    }
+      handlers.onclose?.(error)
+    })
     return { id, close }
   }
 
-  publish (event) {
+  publish (event, { signal } = {}) {
     if (!isValidEvent(event)) return Promise.reject(new Error('INVALID_EVENT'))
-    return this.#sendEventOperation('EVENT', event, this.#publishes, 'PUBLISH_TIMEOUT')
+    return this.#sendEventOperation('EVENT', event, this.#publishes, 'PUBLISH_TIMEOUT', signal)
   }
 
-  async authenticate (getAuthEvent) {
+  async authenticate (getAuthEvent, { signal } = {}) {
     if (!this.#challenge) throw new Error('AUTH_CHALLENGE_MISSING')
     const event = await getAuthEvent({ relay: this.url, challenge: this.#challenge })
     if (!isValidEvent(event)) throw new ValidationError('INVALID_AUTH_EVENT')
-    return await this.#sendEventOperation('AUTH', event, this.#authentications, 'AUTH_TIMEOUT')
+    return await this.#sendEventOperation('AUTH', event, this.#authentications, 'AUTH_TIMEOUT', signal)
   }
 
-  #sendEventOperation (type, event, map, timeoutCode) {
+  #sendEventOperation (type, event, map, timeoutCode, signal) {
+    if (signal?.aborted) return Promise.reject(signal.reason || relayTimeoutError(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, relayTimeoutError(timeoutCode, this.#lastTransportError)), this.publishTimeout))
-    map.set(event.id, { ...deferred, timer, promise: deferred.promise })
-    try { this.send(JSON.stringify([type, event])) } catch (error) {
+    const onAbort = () => this.#settleEvent(map, event.id, signal.reason || relayTimeoutError(timeoutCode))
+    const stopAbort = () => signal?.removeEventListener('abort', onAbort)
+    const pending = { ...deferred, timer, promise: deferred.promise, cancelSend: null, stopAbort }
+    map.set(event.id, pending)
+    signal?.addEventListener('abort', onAbort, { once: true })
+    pending.cancelSend = this.#dispatchWork(() => {
+      // Once transmitted, keep the existing ACK/report semantics. Before that,
+      // an operation-wide deadline must cancel the deferred publication.
+      stopAbort()
+      this.send(JSON.stringify([type, event]))
+    }, error => {
       this.#settleEvent(map, event.id, error)
-    }
+    })
     return deferred.promise
   }
 
@@ -170,11 +211,12 @@ export class RelayConnection {
     const id = `p2r2p-count:${++this.#serial}`
     const deferred = Promise.withResolvers()
     const onAbort = () => this.#settleCount(id, null, new Error('COUNT_ABORTED'))
-    this.#counts.set(id, { ...deferred, signal, onAbort })
+    const pending = { ...deferred, signal, onAbort, cancelSend: null }
+    this.#counts.set(id, pending)
     signal?.addEventListener('abort', onAbort, { once: true })
-    try { this.send(JSON.stringify(['COUNT', id, ...filters])) } catch (error) {
+    pending.cancelSend = this.#dispatchWork(() => this.send(JSON.stringify(['COUNT', id, ...filters])), error => {
       this.#settleCount(id, null, error)
-    }
+    })
     return deferred.promise
   }
 
@@ -182,6 +224,8 @@ export class RelayConnection {
     const pending = map.get(id)
     if (!pending) return
     map.delete(id)
+    pending.cancelSend?.()
+    pending.stopAbort?.()
     clearTimeout(pending.timer)
     if (reason) pending.reject(errorFrom(reason, 'OPERATION_REJECTED'))
     else pending.resolve(value)
@@ -191,6 +235,7 @@ export class RelayConnection {
     const pending = this.#counts.get(id)
     if (!pending) return
     this.#counts.delete(id)
+    pending.cancelSend?.()
     pending.signal?.removeEventListener('abort', pending.onAbort)
     if (reason) pending.reject(errorFrom(reason, 'COUNT_REJECTED'))
     else pending.resolve(payload)
@@ -219,14 +264,16 @@ export class RelayConnection {
     if (data[0] === 'CLOSED') {
       const id = data[1]
       const subscription = this.#subscriptions.get(id)
+      const reason = this.#rejection(data[2], data[3], subscription ? 'SUBSCRIPTION_CLOSED' : 'COUNT_CLOSED')
       if (subscription) {
         this.#subscriptions.delete(id)
-        subscription.handlers.onclose?.(errorFrom(data[2], 'SUBSCRIPTION_CLOSED'))
-      } else this.#settleCount(id, null, errorFrom(data[2], 'COUNT_CLOSED'))
+        subscription.cancelSend?.()
+        subscription.handlers.onclose?.(reason)
+      } else this.#settleCount(id, null, reason)
       return
     }
     if (data[0] === 'OK') {
-      const reason = data[2] === true ? null : categorizeRelayError(data[3], 'relay', 'EVENT_REJECTED')
+      const reason = data[2] === true ? null : this.#rejection(data[3], data[4], 'EVENT_REJECTED')
       this.#settleEvent(this.#publishes, data[1], reason, data[3])
       this.#settleEvent(this.#authentications, data[1], reason, data[3])
       return
@@ -248,6 +295,7 @@ export class RelayConnection {
     const reason = relayCloseError(event, 'transport', this.#lastTransportError)
     for (const [id, subscription] of this.#subscriptions) {
       this.#subscriptions.delete(id)
+      subscription.cancelSend?.()
       subscription.handlers.onclose?.(reason)
     }
     for (const id of [...this.#publishes.keys()]) this.#settleEvent(this.#publishes, id, reason)
@@ -263,6 +311,7 @@ export class RelayConnection {
     const reason = relayCloseError(null, 'transport', this.#lastTransportError)
     for (const [id, subscription] of this.#subscriptions) {
       this.#subscriptions.delete(id)
+      subscription.cancelSend?.()
       subscription.handlers.onclose?.()
     }
     for (const id of [...this.#publishes.keys()]) this.#settleEvent(this.#publishes, id, reason)

package/relay/services/relay-pool.js

@@ -1,3 +1,4 @@
+import { liveBufferError } from '../helpers/live-buffer-error.js'
 import { ValidationError } from '../../error/index.js'
 import { decodeHll, encodeHll, estimateHllCount, mergeHll } from '../helpers/hll.js'
 import { createPublishSettlements, firstFulfillment, publishSummary } from '../helpers/publish.js'
@@ -233,21 +234,21 @@ export class RelayPool {
 
   // NIP-42 retries happen inside one relay attempt, so sendEvent still reports
   // exactly one terminal outcome for each relay URL.
-  async #publishEvent (relay, event, getAuthEvent) {
+  async #publishEvent (relay, event, getAuthEvent, signal) {
     try {
-      await relay.publish(event)
+      await relay.publish(event, { signal })
       return 'published'
     } catch (error) {
       const reason = error instanceof Error ? error : new Error(String(error))
       if (!getAuthEvent || !requiresNip42Auth(reason)) throw reason
 
       try {
-        await relay.authenticate(getAuthEvent)
+        await relay.authenticate(getAuthEvent, { signal })
       } catch (error) {
         const authReason = error instanceof Error ? error : new Error(String(error))
         throw new Nip42AuthenticationError(authReason)
       }
-      await relay.publish(event)
+      await relay.publish(event, { signal })
       return 'published'
     }
   }
@@ -651,18 +652,23 @@ export class RelayPool {
     const seenIds = new Set()
 
     let untilTimer = null
-    const overflow = relay => {
-      failure = Object.assign(new Error('RELAY_LIVE_BUFFER_FULL'), { code: 'RELAY_LIVE_BUFFER_FULL', relay, phase: 'live-buffer' })
+    const overflow = (item, bytes, stage = 'delivery', entries = queue, volume = queuedBytes) => {
+      if (isDone) return
+      failure = liveBufferError({
+        relay: item.relay, stage, queue: entries, queuedBytes: volume, incoming: item, incomingBytes: bytes,
+        maxEvents: maxBufferedLiveEvents, maxBytes: maxBufferedLiveBytes,
+        since: Math.min(sinceFloor, ...pendingGaps.values(), ...queue.map(entry => entry.item?.event?.created_at).filter(Number.isFinite))
+      })
       teardown()
     }
     const enqueue = item => {
       const bytes = encoder.encode(JSON.stringify(item)).byteLength
       if (queue.length >= maxBufferedLiveEvents || queuedBytes + bytes > maxBufferedLiveBytes) {
-        overflow(item.relay)
+        overflow(item, bytes)
         return
       }
       queuedBytes += bytes
-      queue.push({ item, bytes })
+      queue.push({ item, bytes, receivedAt: Date.now() })
       p.resolve()
       p = Promise.withResolvers()
     }
@@ -863,11 +869,11 @@ export class RelayPool {
             if (liveBuffer) {
               const bytes = encoder.encode(JSON.stringify(event)).byteLength
               if (liveBuffer.length >= maxBufferedLiveEvents || bufferedBytes + bytes > maxBufferedLiveBytes) {
-                overflow(url)
+                overflow({ event, relay: url }, bytes, 'reconnect', liveBuffer, bufferedBytes)
                 return
               }
               bufferedBytes += bytes
-              liveBuffer.push(event)
+              liveBuffer.push({ item: { event, relay: url }, receivedAt: Date.now() })
             } else pushEvent(event, url)
           },
           onclose: error => {
@@ -906,7 +912,7 @@ export class RelayPool {
           }).finally(() => {
             const buf = liveBuffer
             liveBuffer = null
-            for (const event of buf) pushEvent(event, url, true)
+            for (const entry of buf) pushEvent(entry.item.event, url, true)
             gapTasks.delete(task)
             scheduleProgress(attempt)
             p.resolve()
@@ -1052,9 +1058,9 @@ export class RelayPool {
           else {
             const bytes = encoder.encode(JSON.stringify(item)).byteLength
             if (liveBuffer.length >= maxBufferedLiveEvents || bufferedBytes + bytes > maxBufferedLiveBytes) {
-              throw Object.assign(new Error('RELAY_LIVE_BUFFER_FULL'), { code: 'RELAY_LIVE_BUFFER_FULL', relay: item.relay, phase: 'live-buffer' })
+              throw liveBufferError({ relay: item.relay, stage: 'history-wait', queue: liveBuffer, queuedBytes: bufferedBytes, incoming: item, incomingBytes: bytes, maxEvents: maxBufferedLiveEvents, maxBytes: maxBufferedLiveBytes, since: filter.since ?? 0 })
             }
-            liveBuffer.push({ item, bytes })
+            liveBuffer.push({ item, bytes, receivedAt: Date.now() })
             bufferedBytes += bytes
           }
           liveWake.resolve()
@@ -1144,12 +1150,14 @@ export class RelayPool {
     const eventToSend = event.meta ? { ...event } : event
     if (eventToSend.meta) delete eventToSend.meta
 
+    const sendControllers = urls.map(() => new AbortController())
     const sendDeferreds = urls.map(() => Promise.withResolvers())
     const sendPromises = sendDeferreds.map(({ promise }) => promise)
 
     // Starts before connection work so every relay shares one real deadline.
     const settlement = createPublishSettlements(sendPromises, timeout, {
       onSettled: (settlement, index) => {
+        sendControllers[index].abort(settlement.reason)
         if (settlement.reason?.category === 'timeout' && !settlement.reason.cause) {
           const relay = this.#relays.get(normalizeRelayUrl(urls[index]))
           if (relay?.lastTransportError) settlement.reason.cause = relay.lastTransportError
@@ -1171,7 +1179,9 @@ export class RelayPool {
       ;(async () => {
         try {
           const relay = await this.#getRelay(url)
-          return await this.#publishEvent(relay, eventToSend, getAuthEvent)
+          const signal = sendControllers[index].signal
+          if (signal.aborted) throw signal.reason
+          return await this.#publishEvent(relay, eventToSend, getAuthEvent, signal)
         } catch (err) {
           const reason = err instanceof Error ? err : new Error(String(err))
           if (reason instanceof Nip42AuthenticationError) throw reason

package/temporary-storage/index.js

@@ -36,8 +36,9 @@ export function createTemporaryStorage ({ storageArea = globalThis.sessionStorag
 
   function trackTemporaryKey (key) {
     const tracked = readTrackedKeys()
-    if (tracked.includes(key)) return
+    if (tracked.includes(key)) return false
     writeTrackedKeys(tracked.concat(key))
+    return true
   }
 
   function untrackTemporaryKeys (keys) {
@@ -57,8 +58,14 @@ export function createTemporaryStorage ({ storageArea = globalThis.sessionStorag
 
   function setItem (key, value) {
     if (typeof key !== 'string' || !key || key === TEMPORARY_STORAGE_KEYS_KEY) throw new ValidationError('INVALID_TEMPORARY_STORAGE_KEY')
-    trackTemporaryKey(key)
-    storage().setItem(key, value)
+    const newlyTracked = trackTemporaryKey(key)
+    try {
+      storage().setItem(key, value)
+    } catch (error) {
+      // A failed write is atomic; keep tracking any previous value.
+      if (newlyTracked && storage().getItem(key) === null) untrackTemporaryKeys([key])
+      throw error
+    }
   }
 
   function removeItems (keys) {