libp2r2p 0.11.5 → 0.11.7

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.
 
@@ -534,6 +534,42 @@ returned events; received messages may already have been queued. This is a
 history completeness failure, not evidence that an outgoing message failed.
 Existing rewatch/resume and relay-list refresh paths retry pending intervals;
 there is no dedicated periodic retry timer for a failed history fetch.
+`private-channel.fetchHistory(options)` (0.11.6) is the complete-interval API
+used by messenger recovery. It accepts the signers, processor/fragment options,
+callbacks and abort signal of `fetch`, plus inclusive `since`/`until` bounds
+(defaults: 0 and the start time of the call). It returns only
+`{ oldestCreatedAt, receivedEventCount, relays }`; an empty scan has a null oldest
+time. No complete-history event array is retained. `fetch` keeps its existing
+single-query array contract and optional limit.
+
+History queries each relay independently with limit 16. A response with 16 events
+or status `satisfied` is saturated, even if it already reports EOSE or contains
+fewer valid events. Saturated intervals split into nonoverlapping inclusive
+halves; completed pages process chronologically, oldest half first. Single-second
+intervals grow through 16, 32, 64, 128 and 256. Each response is also bounded to
+4 MiB of serialized UTF-8 event data. At the dense-second or volume ceiling,
+`PRIVATE_CHANNEL_FETCH_INCOMPLETE` retains the operational cause
+`PRIVATE_CHANNEL_HISTORY_PAGE_LIMIT`; the interval stays pending. There is no
+nonstandard cursor, disk spool, dropped excess or successful incomplete scan.
+
+A fragment processor and the existing scoped fragment storage span the entire
+call, including pages and relays. Callbacks are awaited before requesting the
+next page. Processing/persistence failures propagate; completed pages may already
+be ingested and retries remain subject to the existing idempotence contract.
+The summary count includes processed outer events per relay, including replicas,
+not unique decrypted messages or discarded saturated probes. It does not include
+all events observed in those probes.
+
+Recovery admits at most two pages per PrivateMessenger and one per normalized
+relay across the same library instance, including page processing time. Continuous
+live watches are outside those recovery gates. Waiters are abortable and FIFO,
+with at most 256 queued per gate (`PRIVATE_CHANNEL_HISTORY_QUEUE_FULL` on excess).
+The five-second network timeout begins after admission; reported read time also
+includes admission but excludes processing. Seeders still supplement the oldest
+relay result. Checkpoints advance only after the entire interval and existing
+seeder stages succeed; interruption preserves its original pending range. No
+persisted state format changes or migrations are needed.
+
 Subscription relay errors forwarded to `onError` include `relay` when known
 and `operation: 'private-channel.subscribe'`. A per-notification wrapper retains
 the native message, name, code, category and WebSocket close fields; `cause`
@@ -929,3 +965,23 @@ 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.

package/helpers/abortable-semaphore.js

@@ -0,0 +1,41 @@
+// A bounded FIFO for asynchronous work. Acquired leases release explicitly;
+// queued cancellations never consume capacity or keep idle keyed gates alive.
+export function createAbortableSemaphore (capacity, onIdle = () => {}) {
+  const queue = []
+  let active = 0
+  const drain = () => {
+    while (active < capacity && queue.length) {
+      const job = queue.shift()
+      job.signal?.removeEventListener('abort', job.abort)
+      active++
+      let released = false
+      job.resolve(() => {
+        if (released) return
+        released = true
+        active--
+        drain()
+      })
+    }
+    if (!active && !queue.length) onIdle()
+  }
+  return {
+    acquire (signal) {
+      signal?.throwIfAborted()
+      if (queue.length >= 256) return Promise.reject(Object.assign(new Error('PRIVATE_CHANNEL_HISTORY_QUEUE_FULL'), { code: 'PRIVATE_CHANNEL_HISTORY_QUEUE_FULL' }))
+      return new Promise((resolve, reject) => {
+        const job = {
+          signal, resolve, abort: () => {
+            const index = queue.indexOf(job)
+            if (index < 0) return
+            queue.splice(index, 1)
+            reject(signal.reason)
+            drain()
+          }
+        }
+        signal?.addEventListener('abort', job.abort, { once: true })
+        queue.push(job)
+        drain()
+      })
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.11.5",
+  "version": "0.11.7",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",
@@ -22,6 +22,7 @@
     "ecdh",
     "error",
     "event",
+    "helpers",
     "idb",
     "idb-queue",
     "index.js",

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/history.js

@@ -0,0 +1,121 @@
+import { ValidationError } from '../../error/index.js'
+import { normalizeRelayUrl } from '../../url/index.js'
+import { createAbortableSemaphore } from '../../helpers/abortable-semaphore.js'
+import { incompleteFetchError } from './fetch-error.js'
+
+const PAGE_SIZE = 16
+const MAX_PAGE_SIZE = 256
+const MAX_PAGE_BYTES = 4 * 1024 * 1024
+const TIMEOUT_MS = 5000
+const relayGates = new Map()
+const encoder = new TextEncoder()
+const pageLimitError = () => Object.assign(new Error('PRIVATE_CHANNEL_HISTORY_PAGE_LIMIT'), { code: 'PRIVATE_CHANNEL_HISTORY_PAGE_LIMIT' })
+
+function acquireRelay (relay, signal) {
+  signal?.throwIfAborted()
+  let gate = relayGates.get(relay)
+  if (!gate) {
+    gate = createAbortableSemaphore(1, () => { if (relayGates.get(relay) === gate) relayGates.delete(relay) })
+    relayGates.set(relay, gate)
+  }
+  return gate.acquire(signal)
+}
+
+// Queries bounded temporal leaves, oldest first. A saturated one-second leaf
+// cannot be split using standard NIP-01; expand it only up to the safe ceiling.
+export async function readHistory ({ filter, relays, receiverPubkey, signal, getEvents, processEvent, acquirePage }) {
+  const since = filter.since ?? 0
+  const until = filter.until ?? Math.floor(Date.now() / 1000)
+  if (![since, until].every(value => Number.isSafeInteger(value) && value >= 0) || since > until) throw new ValidationError('INVALID_PRIVATE_CHANNEL_HISTORY_RANGE')
+  if (!Array.isArray(relays) || !relays.length) throw new ValidationError('NO_RELAYS')
+  const urls = [...new Set(relays.map(normalizeRelayUrl))]
+  const report = []
+  const errors = []
+  let oldestCreatedAt = null
+  let receivedEventCount = 0
+  let elapsedMs = 0
+  const process = async result => {
+    result.sort((a, b) => a.event.created_at - b.event.created_at || String(a.event.id).localeCompare(String(b.event.id)))
+    for (const { event } of result) {
+      signal?.throwIfAborted()
+      await processEvent(event)
+      receivedEventCount++
+      oldestCreatedAt = Math.min(oldestCreatedAt ?? event.created_at, event.created_at)
+    }
+  }
+  for (const relay of urls) {
+    const intervals = [{ since, until, limit: PAGE_SIZE }]
+    let outcome = { relay, status: 'eose' }
+    while (intervals.length) {
+      signal?.throwIfAborted()
+      const interval = intervals.pop()
+      const started = performance.now()
+      let releaseRelay
+      let releasePage
+      let page
+      try {
+        let bytes = 0
+        try {
+          releaseRelay = await acquireRelay(relay, signal)
+          releasePage = await acquirePage?.(signal)
+          signal?.throwIfAborted()
+          page = await getEvents({ ...filter, ...interval }, [relay], {
+            signal, timeout: TIMEOUT_MS, timeoutAfterFirstEose: null,
+            callback: item => {
+              if (item.type !== 'event') return
+              bytes += encoder.encode(JSON.stringify(item.event)).byteLength
+              if (bytes > MAX_PAGE_BYTES) throw pageLimitError()
+            }
+          })
+          // Also enforce the contract for injected readers that omit callbacks.
+          let resultBytes = 0
+          for (const { event } of page.result) {
+            resultBytes += encoder.encode(JSON.stringify(event)).byteLength
+            if (resultBytes > MAX_PAGE_BYTES) throw pageLimitError()
+          }
+        } catch (error) {
+          signal?.throwIfAborted()
+          errors.push({ relay, reason: error })
+          outcome = { relay, status: 'error', error }
+          break
+        } finally { elapsedMs += performance.now() - started }
+        signal?.throwIfAborted()
+        const status = page.relays?.find(item => item.relay === relay)
+        if (page.errors?.length || !status || !['eose', 'satisfied'].includes(status.status)) {
+          await process(page.result)
+          errors.push(...(page.errors ?? []))
+          outcome = status ?? { relay, status: 'error' }
+          break
+        }
+        if (status.status === 'satisfied' || page.result.length >= interval.limit) {
+          if (interval.since < interval.until) {
+            const middle = Math.floor(interval.since + (interval.until - interval.since) / 2)
+            intervals.push({ since: middle + 1, until: interval.until, limit: PAGE_SIZE }, { since: interval.since, until: middle, limit: PAGE_SIZE })
+          } else if (interval.limit < MAX_PAGE_SIZE) {
+            intervals.push({ ...interval, limit: interval.limit * 2 })
+          } else {
+            await process(page.result)
+            const error = pageLimitError()
+            errors.push({ relay, reason: error })
+            outcome = { relay, status: 'error', error }
+            break
+          }
+        } else {
+          await process(page.result)
+        }
+        signal?.throwIfAborted()
+      } finally {
+        releasePage?.()
+        releaseRelay?.()
+      }
+    }
+    report.push(outcome)
+  }
+  signal?.throwIfAborted()
+  if (errors.length || report.some(item => item.status !== 'eose')) {
+    const error = incompleteFetchError({ errors, report, receivedEventCount, elapsedMs: Math.round(elapsedMs), request: { relays: urls, channelPubkeys: filter.authors ?? [], receiverPubkey, since, until, limit: PAGE_SIZE, timeoutMs: TIMEOUT_MS } })
+    error.operation = 'private-channel.fetchHistory'
+    throw error
+  }
+  return { oldestCreatedAt, receivedEventCount, relays: report }
+}

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']) {
     if (reason?.[key] !== undefined) error[key] = reason[key]
   }
   error.operation = 'private-channel.subscribe'

package/private-channel/index.js

@@ -7,21 +7,21 @@ import { getIykcProofs } from '../content-key/index.js'
 import { ValidationError } from '../error/index.js'
 import { normalizeRumor, deliveryInfo } from './helpers/rumor.js'
 import { incompleteFetchError } from './helpers/fetch-error.js'
+import { readHistory } from './helpers/history.js'
 import { subscriptionError } from './helpers/subscription-error.js'
 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'
@@ -120,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
   }
 }
 
@@ -138,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` })
-      }
+  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` })
     }
-    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
-    }
-  } 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
   }
 }
 
@@ -955,6 +951,17 @@ export async function fetch ({ signal, receiverSigner, iykcSigner, privateChanne
   }
 }
 
+// Complete interval recovery with bounded pages and one fragment processor.
+// Existing fetch() retains its one-query/event-array contract.
+export async function fetchHistory ({ receiverSigner, privateChannelSigner = receiverSigner, _getEvents = getEvents, _acquirePage, ...options }) {
+  const authors = privateChannelPubkeyList(options)
+  const filter = { kinds: [PRIVATE_BROADCAST_KIND], ...(authors.length ? { authors } : {}), since: options.since, until: options.until }
+  const processOuterEvent = createProcessor({ ...options, receiverSigner, privateChannelSigner, onError: error => { options.onError?.(error); throw error } })
+  try {
+    return await readHistory({ filter, relays: options.relays, receiverPubkey: options.receiverPubkey, signal: options.signal, getEvents: _getEvents, processEvent: processOuterEvent, acquirePage: _acquirePage })
+  } finally { processOuterEvent.close() }
+}
+
 export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, since = nowSeconds() - 5, limit, liveOnly = false, mode = 'leecher', modeByPubkey, receivedChunkScope = '', receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES, receivedChunkIndexedDB = globalThis.indexedDB, ignoredGroupTtlMs = DEFAULT_IGNORED_GROUP_TTL_MS, ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES, _liveEventsGenerator = getLiveEventsGenerator, _eventsFeedGenerator = getEventsFeedGenerator }) {
   if (!relays?.length) throw new ValidationError('NO_RELAYS')
   if (receiverSigner && !receiverSigner?.nip44DecryptDoubleDH && !receiverSigner?.nip44v3Decrypt) throw new ValidationError('RECEIVER_SIGNER_NIP44V3_DECRYPT_UNSUPPORTED')

package/private-messenger/index.js

@@ -42,6 +42,7 @@
 // - Seeder replies stream compact routers with createMissingMessageReplyPacker({ messenger, question }).update(seed), then finalize(optionalLastSeed).
 // - For other event-list replies, use createEventReplyPacker({ messenger, question, code }).update(event).
 
+import { createAbortableSemaphore } from '../helpers/abortable-semaphore.js'
 import * as privateMessage from '../private-message/index.js'
 import { isOnline } from '../network/index.js'
 import { createSendRelayRouting, normalizeFallbackRelays } from './helpers/send-routing.js'
@@ -285,6 +286,7 @@ export class PrivateMessenger {
     this.deliveryReads = new Set()
     this.deliveryWaiters = new Set()
     this.recoveries = new Map()
+    this.recoveryAdmission = createAbortableSemaphore(2)
     this.recoveryControllers = new Set()
     this.resumeWork = null
     this.capacityTimer = null
@@ -1950,12 +1952,11 @@ export class PrivateMessenger {
   }
 
   async askSeedersForRelayLeftEdge (channelPubkey, range, fetchedEvents) {
-    const { asks } = await this.#askSeedersForRelayLeftEdgeAttempt(channelPubkey, range, fetchedEvents)
+    const { asks } = await this.#askSeedersForRelayLeftEdgeAttempt(channelPubkey, range, oldestCreatedAt(fetchedEvents))
     return asks
   }
 
-  async #askSeedersForRelayLeftEdgeAttempt (channelPubkey, range, fetchedEvents) {
-    const oldest = oldestCreatedAt(fetchedEvents)
+  async #askSeedersForRelayLeftEdgeAttempt (channelPubkey, range, oldest) {
     const until = oldest == null ? range.end : Math.min(range.end, oldest)
     if (until < range.start) return { asks: [], failures: [] }
     return this.#askSeedersForMissingRangeAttempt(channelPubkey, range.start, until)
@@ -2098,7 +2099,8 @@ export class PrivateMessenger {
           if (this.pauseReasons.size || this.closePromise || !this.desiredChannels.has(pubkey)) throw new Error('PRIVATE_MESSENGER_PAUSED')
           const fetchRelays = await this.resolveWatchRelays(channel)
           controller.signal.throwIfAborted()
-          const fetchedEvents = await this._privateChannel.fetch({
+          const history = await this._privateChannel.fetchHistory({
+            _acquirePage: signal => this.recoveryAdmission.acquire(signal),
             signal: controller.signal,
             receivedChunkScope: this.storageLeaseId,
             receiverSigner: this.userSigner,
@@ -2120,9 +2122,9 @@ export class PrivateMessenger {
             onSeedEvent: seed => this.receive(pubkey, () => this.enqueueSeed(pubkey, seed), seed),
             onContentKeyUsage: usage => this.handleContentKeyUsage(pubkey, usage),
             onError: err => { throw err }
-          }) || []
+          })
           controller.signal.throwIfAborted()
-          const attempt = await this.#askSeedersForRelayLeftEdgeAttempt(pubkey, range, fetchedEvents)
+          const attempt = await this.#askSeedersForRelayLeftEdgeAttempt(pubkey, range, history.oldestCreatedAt)
           const lifecycleChanged = this.closePromise || !this.channels.has(pubkey) || !this.stopByChannel.has(pubkey) ||
             (this.watchRevisionByChannel.get(pubkey) || 0) !== watchRevision
           if (lifecycleChanged || attempt.failures.length) remaining.push(range)

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/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

@@ -233,21 +233,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'
     }
   }
@@ -1144,12 +1144,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 +1173,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) {