libp2r2p 0.10.19 → 0.10.21

package/README.md

@@ -30,7 +30,7 @@ partial results. Its report distinguishes actual relay EOSE from other outcomes:
 | --- | --- |
 | `eose` | The relay sent EOSE. |
 | `satisfied` | The requested limit or IDs were satisfied, so the read closed early. |
-| `timeout` | The initial operation deadline elapsed. Also emits an error item. |
+| `timeout` | The initial relay attempt deadline elapsed. Also emits an error item. |
 | `cutoff` | The grace period after the first qualifying EOSE/early completion elapsed. |
 | `closed` | The subscription ended without EOSE or an explicit error. |
 | `error` | Connection or subscription failed. Also emits an error item. |
@@ -71,7 +71,7 @@ tracks currently ready relays and can change after that snapshot. Timeouts and
 cutoffs are not acknowledgements of readiness. Reconnections do not repeat the
 initial marker. Both APIs require consuming the iterator to start its work.
 
-Live and feed iterators have a synchronous, idempotent `stopAndDrain()` method.
+Read iterators have a synchronous, idempotent `stopAndDrain()` method.
 It closes subscription input and cancels reconnections and outstanding historical
 queries, while retaining items already accepted by receive callbacks. Continue
 consuming to obtain those items and completion. This includes initial history,
@@ -101,6 +101,72 @@ content-key, private-channel and NIP-46 helpers unwrap pool results internally
 and retain their higher-level event contracts. Count, publication and disconnect
 return formats are unchanged.
 
+### Read admission and bounded snapshots (0.10.21)
+
+Each pool coordinates event reads by normalized connection URL. Constructor
+options are `maxSubscriptionsPerRelay: 28`,
+`maxConcurrentHistoryPerRelay: 2`, and `maxQueuedReadsPerRelay: 256`.
+These are local budgets, not negotiated relay limits. A stricter relay can still
+reject subscriptions. Count and publication contracts are unchanged and do not
+consume event-read slots.
+
+Admission is FIFO per connection. A history+live feed reserves two slots
+atomically before either REQ opens; completing history releases only its slot.
+One-shot queries and reconnect gap reads share this budget. Reconnection reserves
+live+history together when recovery is needed. Caller cancellation removes queued
+work; `disconnect(url)` also rejects queued work for that connection. Existing
+live streams retain their reconnect behavior until cancelled by their owner.
+
+All event reads accept `queueTimeout: 30000` (milliseconds, `null` disables).
+The network `timeout` starts **after admission for each relay**, including its
+connection setup; time in the queue does not consume it. The first-EOSE grace
+can still cut short other relay attempts. Admission failures are ordinary error
+envelopes/report entries, with `error.code`, `error.relay` and
+`error.phase === 'admission'`: `RELAY_READ_QUEUE_FULL`,
+`RELAY_READ_QUEUE_TIMEOUT`, `RELAY_READ_CAPACITY`, or `RELAY_DISCONNECTED`.
+Cancellation rejects an outstanding direct `getEvents()` call; cancelled iterators
+stop delivering. Failures on one relay continue to allow results from others.
+
+Live and feed readers limit each pending live buffer to 1,000 envelopes and
+8 MiB of serialized UTF-8 data. Options `maxBufferedLiveEvents` and
+`maxBufferedLiveBytes` customize those positive limits. They cover consumer
+backlog and reconnect buffers as well as live events waiting for history. These
+are bounds on queued data, not a measurement of total JavaScript heap usage.
+Overflow fails the attempt with `RELAY_LIVE_BUFFER_FULL` (`phase: 'live-buffer'`),
+closes input and discards pending live data. Callers decide whether to retry;
+events already delivered are not recalled. Ordinary relay failures retain the
+existing partial-result behavior; they do not automatically discard the feed.
+
+With `snapshot: true`, a feed waits for its initial live readiness window before
+capturing the historical `until`. `filter.since` defaults to zero; `filter.until`
+can provide an earlier cutoff but cannot extend a snapshot into the future.
+The historical completion includes the actual inclusive bounds:
+
+```js
+const stream = relayPool.getEventsFeedGenerator(
+  { authors: [pubkey], kinds: [1], since: lastConfirmed - 600, limit: 200 },
+  [relay],
+  { snapshot: true, timeoutAfterFirstEose: null, signal }
+)
+// Historical completion:
+// { type: 'eose', relays: [...], snapshot: { since, until } }
+```
+
+Only history is bounded: the live REQ has no `until` in this mode. Events around
+the boundary can appear in both sources and are deduplicated by ID. Empty history
+still reports its bounds. With `live: false`, the cutoff is captured when the
+iterator starts; `limit: 0` remains live-only, without a historical snapshot.
+Default `snapshot: false` retains the existing filter time-range behavior.
+
+This is a bounded time interval, not a transactional relay snapshot or proof of
+complete coverage. Check each relay's outcome, exhaust pagination and commit
+received events before checkpointing. `satisfied` can mean a truncated page;
+EOSE can also terminate a limited response. A consumer that rejects a historical
+attempt can call `return()`/abort when it receives its report, before the buffered
+live events are released. Use `stopAndDrain()` only when those pending events
+should be preserved. Slow/failed live readiness is still reported by the live
+stream according to the existing partial-failure rules.
+
 ## Private Messenger
 
 The main API is `createPrivateMessenger` from `libp2r2p/private-messenger`.
@@ -126,8 +192,9 @@ const messenger = await createPrivateMessenger({
 })
 
 async function logMessages () {
-  for await (const message of messenger.messages()) {
+  for await (const { message, ack } of messenger.messages()) {
     console.log(message.type, message.payload)
+    await ack()
   }
 }
 
@@ -316,23 +383,101 @@ needed by private channels. For double-DH content-key use, pass a
 `contentKeySigner` or a signer implementation that handles content keys
 internally.
 
-Messages are stored in a bounded, durable IndexedDB queue until consumed or
+Messages are stored in a bounded, durable IndexedDB queue until acknowledged or
 until the principal identity has been inactive for 60 days:
 
 ```js
 async function handleMessages () {
-  for await (const message of messenger.messages()) {
-    if (message.type === 'message') {
-      console.log(message.payload)
-    }
+  for await (const { message, ack } of messenger.messages()) {
+    await persistMessageIdempotently(message)
+    await ack() // only after the destination commits
   }
 }
 
 handleMessages().catch(err => console.warn('private messenger messages failed', err))
 ```
 
-For one-at-a-time consumption, use `await messenger.nextMessage()`. Queue
-clearing is asynchronous too: `await messenger.clearChannel(channelPubkey)`.
+For one-at-a-time consumption, `await messenger.nextMessage()` returns
+`{ message, ack, nack }` or `null` if no record is currently available. `ack()`
+removes the reserved record; `nack()` releases it for another attempt. Both
+return a boolean and are idempotent for the same reservation. An expired or
+superseded reservation returns `false` and cannot delete a later delivery.
+
+Delivery leases last 30 seconds and renew every 10 seconds while held. Closing
+the messenger or returning the iterator releases its unacknowledged deliveries;
+returning an iterator also cancels an empty pending read. A crashed/suspended
+consumer's expired leases are reclaimable by another instance. Apps must save
+idempotently: a crash between their commit and `ack()` can repeat delivery.
+The queue is shared by identity, so concurrent consumers claim distinct records.
+
+The app-message queue defaults to 16 MiB and rejects writes at capacity, without
+evicting pending messages. Capacity pressure pauses ingestion and records a
+recovery gap; successful acknowledgments resume it when possible. While capacity-paused, a
+one-second capacity check also detects space released by another instance. Oversized
+records and storage failures report errors and pause with reason `storage`;
+after correcting the cause, call `resume('storage')`. Retention cleanup and
+explicit `clearQueue()`/`clearChannel()` remain destructive. The queue's budget
+bounds serialized storage, not the size of every intermediate decoded message.
+
+### Forwarded authors and isolated consumers
+
+`broadcastRumor({ rumor, ... })` accepts an optional `rumor.pubkey`. Omission
+means the sender; a different pubkey forwards that claimed author and requires
+the original `created_at`. A supplied ID must match the reconstructed event.
+The wire retains the original fields; recipients never overwrite an explicit
+author with the transport sender. Signed events retain their signature.
+
+Received messages expose `senderPubkey` and `provenance` alongside `event`,
+`outer`, `meta` and `payload`. Provenance is `direct`, `hearsay`, or `signed`,
+calculated by the receiver. Pending deduplication includes provenance, so an original can upgrade a queued
+hearsay copy of the same event. Private-channel callbacks also expose these fields
+in their metadata. Nothing is attached to the Nostr event. A rumor naming the
+recipient is still hearsay unless independently matched to a known original.
+Forwarded controls cannot invoke ask/reply/presence/recovery handlers in the
+name of another author. Direct rumors are not transferable signed proof.
+
+Each PrivateMessenger owns a `createPrivateMessageSession()` from
+`libp2r2p/private-message`. A session groups relay reads for one receiver and
+owns its watches, callbacks, and scoped receive-fragment progress. Independent
+sessions can watch the same channel, including with the same receiver, without
+overwriting or closing each other's reads. The module-level watch helpers are
+a convenience scope per receiver; use explicit sessions for separate consumers.
+`receivedChunkScope` can also scope lower-level private-channel reads; receiver
+pubkeys are included in fragment keys. Expiration/cleanup still use the shared
+receive-chunk database and budget.
+
+### Pause, resume and recovery
+
+`pause(reason)` and `resume(reason)` accept nonempty strings. Reasons compose:
+removing `network` cannot override an application's `vault` pause. Pause stops
+live watches, recovery fetches and presence publishing, but retains channel
+configuration and pending deliveries. Already-started operations can finish;
+failed ingestion remains recoverable. Send attempts while paused reject.
+
+`watch(channels)` declares desired subscriptions. `unwatch(channels)` removes
+that intent while retaining configuration and history. Browser `online` only
+clears the internal `network` pause, never restarts explicitly unwatched
+channels. Updating retained channel configuration preserves explicit unwatch;
+new channels are watched unless paused. Applications may explicitly watch again.
+
+Pauses, unwatch and close record the start of the gap, even for channels that
+have never received a message. Rewatch/resume uses live delivery plus historical
+recovery with overlap. A failed resume remains retryable under its pause reason.
+Before opening a watch, the messenger persists a pending recovery interval.
+A first watch scans the configured recovery window (seven days by default),
+including messages sent before this identity first opened the channel. Successful
+scans persist `recoveredThrough`, even when empty; later watches resume from the
+latest persisted message or scan checkpoint with overlap. Pending older ranges
+remain until successfully recovered, even if newer live messages arrive.
+This also covers abrupt termination without `close()` and channels with no
+messages. Applications still supply signers and desired channels on reopening;
+storage is scoped by origin and user pubkey, not the transient session ID.
+Failed ingestion or incomplete relay fetch reports never complete the gap.
+`lastSeenAt` tracks messages persisted in the incoming queue, not app commits.
+The default recovery window is seven days; recovery still depends on available
+relay/seeder data, and retention limits cannot guarantee indefinite delivery.
+
+Queue clearing remains asynchronous: `await messenger.clearChannel(channelPubkey)`.
 
 Use explicit subpath imports for bundle size. The package root re-exports the
 main messenger API for convenience, but applications that only need one piece
@@ -626,3 +771,22 @@ limit, retaining the full URL and exposing decoded `url.nfile` and MIME `url.m`.
 
 The NIP-94 extension also carries optional `download` intent; see
 [nip94/README.md](nip94/README.md#download-intent) for event and inline URL forms.
+
+## Reliable IndexedDB queue reservations
+
+`createQueue({ prefix, evictionPolicy: 'reject', maxBytes })` opts out of
+capacity eviction. Oversized items reject with `QUEUE_ITEM_TOO_LARGE`, full
+queues with `QUEUE_CAPACITY_EXCEEDED`; browser quota errors propagate without
+trimming existing records. Other eviction policies retain their cache behavior.
+Opening a reject-policy queue under a smaller budget preserves existing items.
+
+`queue.reserve({ leaseMs = 30000 })` returns `null` or
+`{ item, ack, nack, renew }`. Reservation token/deadline are internal record
+metadata, persisted atomically in the same IndexedDB transaction as selection.
+`renew()` extends a still-valid lease. Low-level callers own renewal and release;
+PrivateMessenger supplies both. Do not mix reservations with destructive or
+position-shifting queue operations on the same queue except explicit removal.
+A stale token cannot acknowledge a newly reserved or replaced record.
+
+`queue.getCapacity()` returns `{ usedBytes, maxBytes }`; capacity rejections
+also expose `requiredBytes` and `maxBytes`, without retaining the rejected item.

package/idb-queue/index.js

@@ -56,6 +56,7 @@ function byteLength (value) {
 
 function normalizeEvictionPolicy (policy) {
   if (policy === 'opposite-end' || policy === undefined || policy === null) return 'opposite-end'
+  if (policy === 'reject') return 'reject'
   if (policy === 'fifo' || policy === 'head') return 'head'
   if (policy === 'lifo' || policy === 'tail') return 'tail'
   throw new ValidationError('QUEUE_INVALID_EVICTION_POLICY')
@@ -468,6 +469,12 @@ export async function createQueue ({
   async function evictToFit (tx, state, requiredBytes, options = {}) {
     if (!hasByteLimit()) return
     if (requiredBytes > sessionMaxBytes) throw new Error('QUEUE_ITEM_TOO_LARGE')
+    if (configuredEvictionPolicy === 'reject') {
+      if (state.usedBytes + requiredBytes > sessionMaxBytes) {
+        throw Object.assign(new Error('QUEUE_CAPACITY_EXCEEDED'), { requiredBytes, maxBytes: sessionMaxBytes })
+      }
+      return
+    }
     // Make room for the write and retain eviction headroom for the next one.
     const targetBytes = targetBytesAfterWrite(requiredBytes)
     while (state.usedBytes + requiredBytes > targetBytes) {
@@ -477,7 +484,7 @@ export async function createQueue ({
   }
 
   async function evictToBytes (tx, state, targetBytes, options = {}) {
-    if (!hasByteLimit()) return
+    if (!hasByteLimit() || configuredEvictionPolicy === 'reject') return
     while (state.usedBytes > targetBytes) {
       if (!await evictOne(tx, state, options)) break
     }
@@ -590,7 +597,7 @@ export async function createQueue ({
         if (wakeWaiters) wake()
         return value
       } catch (err) {
-        if (retried || !hasByteLimit() || !isQuotaExceeded(err)) throw err
+        if (configuredEvictionPolicy === 'reject' || retried || !hasByteLimit() || !isQuotaExceeded(err)) throw err
         // Browser quota can be lower than the configured logical budget.
         // Retry once with a smaller in-memory budget after atomic rollback.
         lowerSessionMaxBytes(requiredBytes)
@@ -748,6 +755,61 @@ export async function createQueue ({
     })
   }
 
+  // Reservations are stored atomically with the item; another tab/process can
+  // reclaim an expired lease after a crash. Destructive/positional queue APIs
+  // must not be mixed with reservations on the same queue.
+  async function reserve ({ leaseMs = 30000, now = Date.now() } = {}) {
+    if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0 || !Number.isSafeInteger(now) || now < 0) throw new ValidationError('QUEUE_INVALID_LEASE')
+    const token = globalThis.crypto.randomUUID()
+    const reserved = await mutate(async tx => {
+      const p = deferred()
+      let cursor = (await run('openCursor', [], ITEMS_STORE, null, { tx, p })).result
+      while (cursor) {
+        const record = cursor.value
+        if (!record.reservation || record.reservation.until <= now) {
+          record.reservation = { token, until: now + leaseMs }
+          await putRecord(tx, record)
+          return record
+        }
+        cursor = await nextCursor(cursor, p)
+      }
+      return null
+    })
+    if (!reserved) return null
+    let settled = false
+    let completedAction
+    let completedResult
+    let tail = Promise.resolve()
+    const update = (action, at = Date.now()) => {
+      const operation = tail.then(async () => {
+        if (settled) return action === completedAction ? completedResult : false
+        const result = await mutate(async (tx, state) => {
+          const record = await getRecord(tx, reserved.position)
+          if (record?.reservation?.token !== token || record.reservation.until <= at) return false
+          if (action === 'ack') {
+            await deleteRecord(tx, record.position)
+            state.usedBytes = Math.max(0, state.usedBytes - record.byteSize)
+            await trimBounds(tx, state)
+          } else {
+            if (action === 'renew') record.reservation.until = at + leaseMs
+            else delete record.reservation
+            await putRecord(tx, record)
+          }
+          return true
+        }, { wakeWaiters: action !== 'renew' })
+        if (action !== 'renew' || !result) {
+          settled = true
+          completedAction = action
+          completedResult = result
+        }
+        return result
+      })
+      tail = operation.catch(() => {})
+      return operation
+    }
+    return { item: reserved.item, ack: () => update('ack'), nack: () => update('nack'), renew: () => update('renew') }
+  }
+
   async function snapshotStoredItems () {
     return snapshot(async tx => {
       const state = await readState(tx)
@@ -819,6 +881,8 @@ export async function createQueue ({
   })
 
   return {
+    reserve,
+    getCapacity: () => snapshot(async tx => ({ usedBytes: (await readState(tx)).usedBytes, maxBytes: sessionMaxBytes })),
     enqueue: push,
     push,
     pop,

package/package.json

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

package/private-channel/helpers/rumor.js

@@ -0,0 +1,26 @@
+import { getEventHash, isSerializableEvent } from '../../event/index.js'
+import { ValidationError } from '../../error/index.js'
+
+// Transport sender and claimed author are distinct. This also validates a
+// supplied ID before discarding it from the unsigned wire representation.
+export function normalizeRumor (rumor, senderPubkey) {
+  if (!rumor || typeof rumor !== 'object' || Array.isArray(rumor) || 'sig' in rumor) throw new ValidationError('INVALID_RUMOR')
+  const event = {
+    pubkey: rumor.pubkey === undefined ? senderPubkey : rumor.pubkey,
+    kind: rumor.kind,
+    created_at: rumor.created_at,
+    tags: rumor.tags,
+    content: rumor.content
+  }
+  if (!isSerializableEvent(event)) throw new ValidationError('INVALID_RUMOR')
+  const id = getEventHash(event)
+  if (rumor.id !== undefined && rumor.id !== id) throw new ValidationError('INVALID_RUMOR_ID')
+  return { ...event, id }
+}
+
+export function deliveryInfo (event, senderPubkey) {
+  return {
+    senderPubkey,
+    provenance: event.sig ? 'signed' : event.pubkey === senderPubkey ? 'direct' : 'hearsay'
+  }
+}

package/private-channel/index.js

@@ -5,6 +5,7 @@ import { hexToBytes } from '../base16/index.js'
 import { isValidContentKeyProof, isValidIykcProof, makeContentKeyEventForPubkey, parseContentKeyEvent } from '../content-key/event/index.js'
 import { getIykcProofs } from '../content-key/index.js'
 import { ValidationError } from '../error/index.js'
+import { normalizeRumor, deliveryInfo } from './helpers/rumor.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'
@@ -371,8 +372,7 @@ function eventFromPayload ({ payloadCiphertext, messageSeckey, senderPubkey }) {
   const messagePubkey = getPublicKey(messageSecretKey)
   const decrypted = JSON.parse(nip44v3.decrypt(messageSecretKey, messagePubkey, ROUTER_KIND, NIP44_V3_SCOPE, payloadCiphertext))
   if (hasEventSignature(decrypted)) return assertValidSignedInnerEvent(decrypted)
-  const normalized = { ...decrypted, pubkey: senderPubkey }
-  return { ...normalized, id: getEventHash(normalized) }
+  return normalizeRumor(decrypted, senderPubkey)
 }
 
 async function unwrapRecipientEnvelope ({ payloadCiphertext, envelope, receiverSigner, receiverPubkey, senderPubkey, imkcPubkey, rowScope = '' }) {
@@ -670,6 +670,7 @@ function createProcessor ({
   onSeedEvent,
   onContentKeyUsage,
   onError,
+  receivedChunkScope = '',
   receivedChunkTtlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS,
   receivedChunkTtlMsByPubkey,
   receivedChunkMaxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES,
@@ -678,6 +679,7 @@ function createProcessor ({
   ignoredGroupMaxEntries = DEFAULT_IGNORED_GROUP_MAX_ENTRIES
 }) {
   const receivedChunks = createReceivedChunkStore({
+    scope: `${receivedChunkScope}:${receiverPubkey || ''}`,
     ttlMs: receivedChunkTtlMs,
     maxBytes: receivedChunkMaxBytes,
     indexedDB: receivedChunkIndexedDB
@@ -750,7 +752,8 @@ function createProcessor ({
         await onNymEvent?.(event, outer, {
           carrier: carriers[0],
           carriers,
-          channelPubkey
+          channelPubkey,
+          ...deliveryInfo(event, carriers[0].pubkey)
         })
         await receivedChunks.removeGroup(groupKey)
         return
@@ -833,7 +836,7 @@ function createProcessor ({
       })
 
       if (event && !mustScanWholeBundle) {
-        await onEvent?.(event, outer, { router: joinedRouter(router), channelPubkey })
+        await onEvent?.(event, outer, { router: joinedRouter(router), channelPubkey, ...deliveryInfo(event, senderPubkey) })
         ignoredGroups.add(groupKey)
         await receivedChunks.removeGroup(groupKey)
         return
@@ -855,7 +858,7 @@ function createProcessor ({
         onContentKeyUsage
       })
       if (shouldSeed) await onSeedEvent?.({ recordType: 'routerRow_v1', outer, router: completeRouter, channelPubkey, jsonl, innerEventIdsByRowIndex })
-      if (event) await onEvent?.(event, outer, { router: completeRouter, channelPubkey, jsonl })
+      if (event) await onEvent?.(event, outer, { router: completeRouter, channelPubkey, jsonl, ...deliveryInfo(event, senderPubkey) })
 
       await receivedChunks.removeGroup(groupKey)
     } catch (err) {
@@ -863,6 +866,7 @@ function createProcessor ({
         ignoredGroups.add(groupKey)
         await receivedChunks.removeGroup(groupKey).catch(() => {})
       }
+      if (groupKey && !shouldIgnoreGroupError(err)) await receivedChunks.removeGroup(groupKey).catch(() => {})
       onError?.(err)
     }
   }
@@ -894,7 +898,7 @@ function shouldIgnoreGroupError (err) {
   ].includes(err?.message)
 }
 
-export async function fetch ({ receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, since, until, limit, mode = 'leecher', modeByPubkey, 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, _getEvents = getEvents }) {
+export async function fetch ({ signal, receiverSigner, iykcSigner, privateChannelSigner = receiverSigner, privateChannelSignersByPubkey, privateChannelReaderSigner = privateChannelSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, privateChannelPubkey, privateChannelPubkeys, receiverPubkey, relays, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, since, until, limit, 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, _getEvents = getEvents }) {
   if (!relays?.length) throw new ValidationError('NO_RELAYS')
   const authors = privateChannelPubkeyList({ privateChannelPubkey, privateChannelPubkeys })
   const filter = { kinds: [PRIVATE_BROADCAST_KIND] }
@@ -903,22 +907,30 @@ export async function fetch ({ receiverSigner, iykcSigner, privateChannelSigner
   if (until != null) filter.until = until
   if (limit != null) filter.limit = limit
 
-  const { result } = await _getEvents(filter, relays, {
+  const { result, errors = [], relays: report = [] } = await _getEvents(filter, relays, {
     timeout: 5000,
-    timeoutAfterFirstEose: null
+    timeoutAfterFirstEose: null,
+    ...(signal ? { signal } : {})
   })
   const events = result.map(({ event }) => event)
   events.sort((a, b) => a.created_at - b.created_at)
-  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
+  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, receivedChunkScope, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
   try {
-    for (const event of events) await processOuterEvent(event)
+    for (const event of events) {
+      signal?.throwIfAborted()
+      await processOuterEvent(event)
+    }
+    signal?.throwIfAborted()
+    if (errors.length || report.some(entry => !['eose', 'satisfied'].includes(entry.status))) {
+      throw new AggregateError(errors.map(entry => entry.reason), 'PRIVATE_CHANNEL_FETCH_INCOMPLETE')
+    }
     return events
   } 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, 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 }) {
+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')
   if (!privateChannelReaderSigner && !privateChannelReaderSignersByPubkey && !privateChannelSigner && !privateChannelSignersByPubkey) throw new ValidationError('PRIVATE_CHANNEL_READER_REQUIRED')
@@ -927,7 +939,7 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
   const filter = { kinds: [PRIVATE_BROADCAST_KIND], since }
   if (authors.length) filter.authors = authors
   if (limit != null) filter.limit = limit
-  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
+  const processOuterEvent = createProcessor({ receiverSigner, iykcSigner, privateChannelSigner, privateChannelSignersByPubkey, privateChannelReaderSigner, privateChannelReaderSignersByPubkey, privateChannelReaderPubkey, privateChannelReaderPubkeysByPubkey, receiverPubkey, mode, modeByPubkey, onChunk, onEvent, onNymEvent, onSeedEvent, onContentKeyUsage, onError, receivedChunkScope, receivedChunkTtlMs, receivedChunkTtlMsByPubkey, receivedChunkMaxBytes, receivedChunkIndexedDB, ignoredGroupTtlMs, ignoredGroupMaxEntries })
   const controller = new AbortController()
   const events = liveOnly
     ? _liveEventsGenerator(filter, relays, {

package/private-channel/services/received-chunks.js

@@ -20,7 +20,7 @@ IndexedDB schema, scoped per received-chunk prefix:
 database `${prefix}:idb`, version 2
 
 groups, keyPath "groupKey"
-  groupKey                  `${channelPubkey}:${routerPubkey}`
+  groupKey                  optional consumer scope + `${channelPubkey}:${routerPubkey}`
   channelPubkey/routerPubkey private-channel coordinates
   total                     expected chunk count
   received/receivedCount    sparse received-index map and its count
@@ -181,6 +181,7 @@ function wait (ms) {
 
 export function createReceivedChunkStore ({
   prefix = DEFAULT_PREFIX,
+  scope = '',
   indexedDB = globalThis.indexedDB,
   ttlMs = DEFAULT_RECEIVED_CHUNK_TTL_MS,
   maxBytes = DEFAULT_RECEIVED_CHUNK_MAX_BYTES
@@ -220,7 +221,7 @@ export function createReceivedChunkStore ({
   }
 
   function groupKeyFor (channelPubkey, routerPubkey) {
-    return `${channelPubkey}:${routerPubkey}`
+    return `${scope ? `${scope}:` : ''}${channelPubkey}:${routerPubkey}`
   }
 
   async function readUsage (tx) {