libp2r2p 0.10.18 → 0.10.20

package/README.md

@@ -12,35 +12,95 @@ For remote-work scheduling, see [`libp2r2p/network`](network/README.md):
 `isOnline` probes connectivity and `onOnline` shares recovery monitoring,
 including retries when the browser omits its native `online` event.
 
-## Relay feed lifecycle
-
-`RelayPool.getEventsFeedGenerator(filter, relays, options)` yields events directly,
-including the existing `event.meta.relay` field. By default it combines an initial
-historical query with a live subscription. `live: false` selects history only;
-`filter.limit: 0` selects live only. `getLiveEventsGenerator` exposes the same
-lifecycle controls along with its existing `ready` and `readyRelays` properties.
-
-The returned iterator has a synchronous, idempotent `stopAndDrain()` method. It
-closes subscription input and cancels reconnections and outstanding historical
-queries, while retaining events already accepted by the library's receive
-callbacks. Continue consuming the iterator to obtain those events and observe
-completion. This includes initial history, buffered live events, and both history
-and live buffers from reconnect recovery. Calling it before the first `next()`
-prevents subscriptions from opening. No reception timestamp or new event metadata
-is added. Events rejected by ordinary filtering/deduplication remain excluded.
+## Relay reads and lifecycle
+
+All three `RelayPool` read generators emit typed envelopes. The Nostr event is
+never decorated with `meta`; relay provenance belongs to its enclosing item:
+
+```js
+{ type: 'event', event, relay }
+{ type: 'error', relay, error }
+{ type: 'eose', relays: [{ relay, status, error }] } // error is optional
+```
+
+`eose` means the **initial read attempt is complete**, including empty reads and
+partial results. Its report distinguishes actual relay EOSE from other outcomes:
+
+| Status | Meaning |
+| --- | --- |
+| `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. |
+| `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. |
+
+Each normalized relay URL gets one report entry, preserving the first spelling
+provided by the caller. An empty relay list emits `{ type: 'eose', relays: [] }`.
+Caller cancellation never fabricates an initial completion. Individual relay
+failures do not prevent other relays from delivering; malformed arguments and
+general operation failures reject the call or iterator read.
+
+`getEvents(filter, relays, options)` resolves to
+`{ result: [{ event, relay }], errors: [{ relay, reason }], success, relays }`.
+Its optional `callback` receives the same event/error/EOSE envelopes immediately.
+`success` retains its existing meaning: an event was received or at least one
+relay completed without an error; it does not mean every relay sent EOSE.
+`getEventsGenerator` emits those envelopes and retains that report as its final
+iterator return value (not visible inside a `for await` loop).
+
+`getEventsFeedGenerator(filter, relays, options)` combines history and live
+subscription by default: history items, one historical `eose`, buffered live
+items, then ongoing live delivery. `live: false` ends after history and its marker;
+`filter.limit: 0` skips history and forwards the live stream's initial marker.
+Internal live/reconnect EOSEs do not produce additional feed markers.
+
+`getLiveEventsGenerator` discards retained events received before each relay's
+EOSE. A ready relay can deliver live events before the aggregate marker. Initial
+`timeout` defaults to 5000 ms (`null` disables it); expiration reports pending
+relays without stopping their connections or subsequent recovery. The grace
+period `timeoutAfterFirstEose` defaults to 500 ms (`null` disables it). Historical
+queries use these same defaults; their grace period starts only when a relay
+with events EOSEs or satisfies its filter. Reconnect-gap reads keep their separate
+`timeoutForReconnectGap` and `timeoutAfterFirstReconnectGapEose` options.
+
+The live iterator retains `ready: Promise<{ relays, errors }>` and the
+`readyRelays` getter. `ready` is the initial readiness snapshot, derived from the
+same outcomes as the marker; its errors use `{ relay, reason }`. `readyRelays`
+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.
+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,
+buffered live events, and reconnect recovery buffers. Calling it before the
+first `next()` prevents subscriptions from opening. It does not synthesize EOSE.
 
 Aborting `options.signal`, calling `return()` (including a `for await` break), or
-calling `throw()` cancels input and pending delivery instead. An event already
-delivered to the caller cannot be recalled. These operations also interrupt a
-drain. `stopAndDrain()` does not consume the iterator or return a completion
-promise: completion is the iterator's `{ done: true }` result.
+calling `throw()` cancels input and pending delivery instead. An item already
+delivered cannot be recalled. These operations can also interrupt a drain.
+`stopAndDrain()` does not consume the iterator or return a completion promise:
+completion is the iterator's `{ done: true }` result.
 
 ```js
 const stream = relayPool.getEventsFeedGenerator({ authors: [pubkey] }, [relay], { signal })
 // When this relay is removed, call stream.stopAndDrain() from the list handler.
-for await (const event of stream) await store(event)
+for await (const item of stream) {
+  if (item.type === 'event') await store(item.event)
+  else if (item.type === 'error') reportError(item.relay, item.error)
+  else if (item.type === 'eose') initialReadFinished(item.relays)
+}
 ```
 
+Migration from 0.10.18: replace raw live/feed event reads with `item.event` after
+checking `item.type`, replace `event.meta.relay` with the envelope's `relay`, and
+unwrap each `getEvents().result` entry. There is no compatibility flag. Query,
+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.
+
 ## Private Messenger
 
 The main API is `createPrivateMessenger` from `libp2r2p/private-messenger`.
@@ -66,8 +126,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()
   }
 }
 
@@ -146,7 +207,7 @@ if (sent.delivery.deletionSeckey) {
     const deletion = finalizeEvent({
       kind: 5,
       created_at: Math.floor(Date.now() / 1000),
-      tags: [['k', '3560'], ...outerEvents.slice(offset, offset + 100).map(event => ['e', event.id])],
+      tags: [['k', '3560'], ...outerEvents.slice(offset, offset + 100).map(({ event }) => ['e', event.id])],
       content: ''
     }, deletionKey.secretKey)
     await relayPool.sendEvent(deletion, relays)
@@ -256,23 +317,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
@@ -478,11 +617,11 @@ from `libp2r2p/relay`.
 `getEvents` and `getEventsGenerator` accept `deduplicateAcrossRelays` (boolean,
 default `true`). With `false`, a matching event is delivered once per relay,
 while repeated IDs from the same relay remain suppressed. Each occurrence owns
-its `meta.relay`; callbacks still run immediately and deadlines, EOSE handling,
-and per-relay filter limits are unchanged. The callback/generator item remains
-`{ type: 'event', event, relay }`, and the completed query remains
-`{ result, errors, success }`. The option does not extend to the live or feed
-generators. Callers that need replication coverage can aggregate the returned
+its envelope's `relay`; callbacks still run immediately and per-relay filter
+limits are unchanged. The callback/generator event item is
+`{ type: 'event', event, relay }`; the completed query is
+`{ result: [{ event, relay }], errors, success, relays }`. The option does not
+extend to the live or feed generators. Callers that need replication coverage can aggregate the returned
 copies by event ID; missing responses do not prove absence from a relay.
 
 Publication errors retain their existing `reason` objects and may expose
@@ -566,3 +705,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/content-key/services/iykc-proof.js

@@ -103,7 +103,7 @@ export async function getIykcProofs (pubkeys, {
           timeout: 5000,
           timeoutAfterFirstEose: null
         })
-        return result
+        return result.map(({ event }) => event)
       })
   )
 

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/nip46/services/client.js

@@ -75,12 +75,16 @@ export class Nip46Client {
       limit: 0
     }, parsed.relays, {
       signal: controller.signal,
+      timeout: options.timeout ?? DEFAULT_TIMEOUT,
       timeoutAfterFirstEose: options.timeoutAfterFirstEose ?? DEFAULT_TIMEOUT_AFTER_FIRST_EOSE
     })
     const found = Promise.withResolvers()
     const consume = (async () => {
       try {
-        for await (const event of stream) {
+        for await (const item of stream) {
+          if (item.type === 'error') { options.onError?.(item.error); continue }
+          if (item.type !== 'event') continue
+          const { event } = item
           if (!isNip46EventFor(event, clientPubkey)) continue
           const response = decodeNip46Frame(event, clientSecretKey)
           if (response?.result === parsed.secret) {

package/nip46/services/transport.js

@@ -95,14 +95,16 @@ export class Nip46Transport {
     const controller = new AbortController()
     const stream = this.#relayPool.getLiveEventsGenerator(filter, relays, {
       signal: controller.signal,
+      timeout: this.#operationTimeout,
       timeoutAfterFirstEose: this.#timeoutAfterFirstEose
     })
     const context = { controller, stream, relays: [...relays], consume: null }
     this.#contexts.add(context)
     context.consume = (async () => {
       try {
-        for await (const event of stream) {
-          Promise.resolve(onEvent(event)).catch(error => this.#reportError(error))
+        for await (const item of stream) {
+          if (item.type === 'error') this.#reportError(item.error)
+          else if (item.type === 'event') Promise.resolve(onEvent(item.event)).catch(error => this.#reportError(error))
         }
       } catch (error) {
         if (!this.#closed && error?.message !== 'Aborted') this.#reportError(error)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.10.18",
+  "version": "0.10.20",
   "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,21 +907,30 @@ export async function fetch ({ receiverSigner, iykcSigner, privateChannelSigner
   if (until != null) filter.until = until
   if (limit != null) filter.limit = limit
 
-  const { result: events } = 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')
@@ -926,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, {
@@ -940,9 +953,10 @@ export function subscribe ({ receiverSigner, iykcSigner, privateChannelSigner =
 
   async function consumeEvents () {
     try {
-      for await (const outer of events) {
+      for await (const item of events) {
         if (controller.signal.aborted) continue
-        await processOuterEvent(outer)
+        if (item.type === 'error') onError?.(item.error)
+        else if (item.type === 'event') await processOuterEvent(item.event)
       }
     } catch (error) {
       if (!controller.signal.aborted && error?.message !== 'Aborted') onError?.(error)

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) {