@estiva-app/interop 0.30.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/projection.ts CHANGED
@@ -1440,30 +1440,44 @@ async function resolveAspectApp(
1440
1440
  // as Peek does, or two.
1441
1441
  entity: 'naddr' | 'nevent' = 'naddr',
1442
1442
  ): Promise<ResolvedManifest | null> {
1443
- const key = `aspect:${aspect}:${entity}`
1443
+ return throughCache(cache, `aspect:${aspect}:${entity}`, async () => {
1444
+ const handlers = await query([{ kinds: [KIND_HANDLER_INFORMATION], limit: HANDLER_SWEEP_LIMIT }])
1445
+ for (const candidate of [...handlers].sort((a, b) => b.created_at - a.created_at)) {
1446
+ const manifest = parseManifest(candidate)
1447
+ if (manifest?.aspect !== aspect) continue
1448
+ const template = webTemplate(candidate, entity)
1449
+ // Declaring the aspect and publishing nowhere to open a file is a manifest
1450
+ // this consumer has no use for yet; keep looking rather than answer with
1451
+ // an app that cannot be linked to.
1452
+ if (!template) continue
1453
+ return {
1454
+ manifest,
1455
+ address: `${candidate.kind}:${candidate.pubkey}:${tagValue(candidate, 'd') ?? ''}`,
1456
+ viaRecommendation: false,
1457
+ webTemplate: template,
1458
+ }
1459
+ }
1460
+ return null
1461
+ })
1462
+ }
1463
+
1464
+ /**
1465
+ * The memo, then a shared read, then the network — in that order. A cache
1466
+ * without `share` (hand-written, or older) keeps the old behaviour exactly:
1467
+ * look up, read, remember.
1468
+ */
1469
+ async function throughCache(
1470
+ cache: ProjectionCache | undefined,
1471
+ key: string,
1472
+ read: () => Promise<ResolvedManifest | null>,
1473
+ ): Promise<ResolvedManifest | null> {
1444
1474
  const now = Date.now()
1445
1475
  const memo = cache?.lookup(key, now)
1446
1476
  if (memo) return memo.value
1447
-
1448
- const handlers = await query([{ kinds: [KIND_HANDLER_INFORMATION], limit: HANDLER_SWEEP_LIMIT }])
1449
- let answer: ResolvedManifest | null = null
1450
- for (const candidate of [...handlers].sort((a, b) => b.created_at - a.created_at)) {
1451
- const manifest = parseManifest(candidate)
1452
- if (manifest?.aspect !== aspect) continue
1453
- const template = webTemplate(candidate, entity)
1454
- // Declaring the aspect and publishing nowhere to open a file is a manifest
1455
- // this consumer has no use for yet; keep looking rather than answer with
1456
- // an app that cannot be linked to.
1457
- if (!template) continue
1458
- answer = {
1459
- manifest,
1460
- address: `${candidate.kind}:${candidate.pubkey}:${tagValue(candidate, 'd') ?? ''}`,
1461
- viaRecommendation: false,
1462
- webTemplate: template,
1463
- }
1464
- break
1465
- }
1466
- cache?.remember(key, answer, now)
1477
+ if (!cache) return read()
1478
+ if (cache.share) return cache.share(key, now, read)
1479
+ const answer = await read()
1480
+ cache.remember(key, answer, now)
1467
1481
  return answer
1468
1482
  }
1469
1483
 
@@ -1494,6 +1508,13 @@ export interface ProjectionCache {
1494
1508
  lookup(key: string, now: number): { value: ResolvedManifest | null } | undefined
1495
1509
  /** @internal */
1496
1510
  remember(key: string, value: ResolvedManifest | null, now: number): void
1511
+ /**
1512
+ * @internal Run `read` for `key` unless a read for it is already running, in
1513
+ * which case join that one; remember the answer as `remember` would. Optional
1514
+ * so a hand-written cache still satisfies the interface — without it, a burst
1515
+ * of cold resolves asks once each, which is the old behaviour.
1516
+ */
1517
+ share?(key: string, now: number, read: () => Promise<ResolvedManifest | null>): Promise<ResolvedManifest | null>
1497
1518
  }
1498
1519
 
1499
1520
  /**
@@ -1506,10 +1527,53 @@ export interface ProjectionCache {
1506
1527
  */
1507
1528
  export const MANIFEST_TTL_MS = 5 * 60_000
1508
1529
 
1530
+ /**
1531
+ * ## One read per manifest, however many resolves ask at once (PER-8)
1532
+ *
1533
+ * The memo only helps a resolve that starts after another has *finished*. A
1534
+ * consumer that resolves a set together — Peek's Screener does
1535
+ * `Promise.all(files.map(resolveObject))` every minute — starts every one of
1536
+ * them against the same cold entry, so each fetched the recommendation and the
1537
+ * manifest itself, and did it again every time the entry expired. Measured on
1538
+ * production: 133 of an idle tab's 385 requests in five minutes were manifest
1539
+ * lookups, against a meter that refused 74 of them.
1540
+ *
1541
+ * So a read in flight is shared: the second asker for a key joins the first
1542
+ * one's promise. A failure is shared the same way and **not** remembered — the
1543
+ * burst that caused it costs one request instead of one each, and the next
1544
+ * resolve asks afresh. Remembering it would blank every reference to that app
1545
+ * for the whole window over what may have been one refused request.
1546
+ */
1509
1547
  export function createProjectionCache(ttlMs: number = MANIFEST_TTL_MS): ProjectionCache {
1510
1548
  const entries = new Map<string, { at: number; value: ResolvedManifest | null }>()
1549
+ const flights = new Map<string, Promise<ResolvedManifest | null>>()
1550
+ // Bumped by `clear`, so a read that was in flight when a manifest was
1551
+ // republished does not write its stale answer back afterwards.
1552
+ let generation = 0
1511
1553
  return {
1512
- clear: () => entries.clear(),
1554
+ clear: () => {
1555
+ generation += 1
1556
+ entries.clear()
1557
+ flights.clear()
1558
+ },
1559
+ share(key, now, read) {
1560
+ const running = flights.get(key)
1561
+ if (running) return running
1562
+ const began = generation
1563
+ const flight = read().then(
1564
+ (value) => {
1565
+ if (flights.get(key) === flight) flights.delete(key)
1566
+ if (began === generation) entries.set(key, { at: now, value })
1567
+ return value
1568
+ },
1569
+ (error: unknown) => {
1570
+ if (flights.get(key) === flight) flights.delete(key)
1571
+ throw error
1572
+ },
1573
+ )
1574
+ flights.set(key, flight)
1575
+ return flight
1576
+ },
1513
1577
  lookup(key, now) {
1514
1578
  const found = entries.get(key)
1515
1579
  if (!found) return undefined
@@ -1566,13 +1630,7 @@ export async function resolveManifest(
1566
1630
  ? { ...bareFileManifest(), webTemplate: opener.webTemplate }
1567
1631
  : bareFileManifest()
1568
1632
  }
1569
- const key = `${pointer.kind}:${pointer.pubkey}`
1570
- const now = Date.now()
1571
- const memo = cache?.lookup(key, now)
1572
- if (memo) return memo.value
1573
- const answer = await resolveManifestUncached(pointer, query)
1574
- cache?.remember(key, answer, now)
1575
- return answer
1633
+ return throughCache(cache, `${pointer.kind}:${pointer.pubkey}`, () => resolveManifestUncached(pointer, query))
1576
1634
  }
1577
1635
 
1578
1636
  async function resolveManifestUncached(
@@ -2537,19 +2595,166 @@ export async function resolveForeignObject(
2537
2595
  */
2538
2596
  cache?: ProjectionCache,
2539
2597
  ): Promise<ForeignObject | null> {
2540
- let pointer: AddressPointer
2598
+ const pointer = addressPointerOf(naddr)
2599
+ if (!pointer) return null
2600
+ const resolved = await resolveManifest(pointer, query, cache)
2601
+ if (!resolved) return null
2602
+ const plan = planObject(naddr, pointer, resolved, depth)
2603
+ if (!plan) return null
2604
+
2605
+ const assembled = assembleObject(plan, await query(plan.filters))
2606
+ if (assembled.object.unreachable) return assembled.object
2607
+ return withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled)))
2608
+ }
2609
+
2610
+ /**
2611
+ * Many addressed objects in one round trip — PER-10.
2612
+ *
2613
+ * {@link resolveForeignObject} costs one request per object once the manifest
2614
+ * is cached, and a consumer holding a set re-reads the whole set on every
2615
+ * refresh: Peek's Screener asked once per followed file, every minute, and an
2616
+ * idle Desk spent 144 of 194 requests in five minutes on exactly that, against
2617
+ * a relay that meters 300 a minute per person across every tab. This reads the
2618
+ * same objects with the same filters, **all of them in one POST** — chunked at
2619
+ * `MAX_FILTERS_PER_QUERY` the way {@link conversationsOf} is, since each object
2620
+ * asks up to four filters — then one people lookup for the whole set.
2621
+ *
2622
+ * So a refresh is `ceil(filters / 128)` requests and a people lookup, where it
2623
+ * was one request per object and a lookup each: two for any set of up to 32
2624
+ * objects, whatever their number.
2625
+ *
2626
+ * ## Same filters, same objects
2627
+ *
2628
+ * Each object's filters are exactly the ones {@link resolveForeignObject}
2629
+ * sends, so each keeps its own `limit` — one busy file cannot starve another's
2630
+ * comments, which is why this is not one filter naming every address. The
2631
+ * answers come back pooled, and every object is picked back out of the pool on
2632
+ * its filters' own criteria, the rule `childrenFrom` already follows for the
2633
+ * children that share a request with their parent. The result is keyed by the
2634
+ * reference as given, and each object is what `resolveForeignObject` returns
2635
+ * for it.
2636
+ *
2637
+ * A reference that is not an address, or whose app has no manifest or no
2638
+ * projection for its kind, is `null` — as it is from the single form. An event
2639
+ * reference (`nevent`, a bare id) is not an address and is `null` here; that
2640
+ * is {@link resolveForeignEvent}'s.
2641
+ *
2642
+ * **A failed read rejects the whole call**, as the single form throws. There is
2643
+ * no partial answer to give: the objects arrive pooled, so a chunk that failed
2644
+ * could have held any of them.
2645
+ */
2646
+ export async function resolveForeignObjects(
2647
+ references: readonly string[],
2648
+ query: QueryFn,
2649
+ /** Defaults to asking the relay. The browser passes a cached lookup. */
2650
+ lookupPeople?: PeopleFn,
2651
+ /** See {@link ProjectionCache}. Omitting it still reads each app's manifest once per call. */
2652
+ cache?: ProjectionCache,
2653
+ ): Promise<Record<string, ForeignObject | null>> {
2654
+ const results: Record<string, ForeignObject | null> = {}
2655
+ const asked: { reference: string; pointer: AddressPointer }[] = []
2656
+ for (const reference of new Set(references)) {
2657
+ const pointer = addressPointerOf(reference)
2658
+ results[reference] = null
2659
+ if (pointer) asked.push({ reference, pointer })
2660
+ }
2661
+ if (asked.length === 0) return results
2662
+
2663
+ // One manifest per app, never per object — the reason `conversationsOf`
2664
+ // groups the same way. A cache would share these too, but a caller without
2665
+ // one should not pay per object for what every object of an app shares.
2666
+ const byApp = new Map<string, AddressPointer>()
2667
+ for (const { pointer } of asked) byApp.set(manifestKeyOf(pointer), pointer)
2668
+ const manifests = new Map<string, ResolvedManifest>()
2669
+ await Promise.all(
2670
+ [...byApp].map(async ([key, pointer]) => {
2671
+ const resolved = await resolveManifest(pointer, query, cache)
2672
+ if (resolved) manifests.set(key, resolved)
2673
+ }),
2674
+ )
2675
+
2676
+ const plans = asked.flatMap(({ reference, pointer }) => {
2677
+ const resolved = manifests.get(manifestKeyOf(pointer))
2678
+ const plan = resolved && planObject(reference, pointer, resolved, 0)
2679
+ return plan ? [{ reference, plan }] : []
2680
+ })
2681
+ if (plans.length === 0) return results
2682
+
2683
+ // Two spellings of one object — its `naddr` and its plain address — are two
2684
+ // answers (each keeps its own `openUrl`) and one set of filters.
2685
+ const filters: Record<string, unknown>[] = []
2686
+ const planned = new Set<string>()
2687
+ for (const { plan } of plans) {
2688
+ if (planned.has(plan.address)) continue
2689
+ planned.add(plan.address)
2690
+ filters.push(...plan.filters)
2691
+ }
2692
+ const chunks: Record<string, unknown>[][] = []
2693
+ for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
2694
+ chunks.push(filters.slice(start, start + MAX_FILTERS_PER_QUERY))
2695
+ }
2696
+ const events = (await Promise.all(chunks.map((chunk) => query(chunk)))).flat()
2697
+
2698
+ const assembled = plans.map(({ reference, plan }) => ({ reference, built: assembleObject(plan, events) }))
2699
+ const wanted = [...new Set(assembled.flatMap(({ built }) => peopleOf(built)))]
2700
+ const reachable = assembled.some(({ built }) => !built.object.unreachable)
2701
+ const people = reachable ? await (lookupPeople ?? peopleViaRelay(query))(wanted) : {}
2702
+ for (const { reference, built } of assembled) {
2703
+ if (built.object.unreachable) {
2704
+ results[reference] = built.object
2705
+ continue
2706
+ }
2707
+ // Each object carries the people it names, as the single form's does —
2708
+ // not the whole set's, which would make an object's shape depend on what
2709
+ // it happened to be resolved beside.
2710
+ const own: People = {}
2711
+ for (const key of peopleOf(built)) if (key in people) own[key] = people[key]
2712
+ results[reference] = withPeople(built, own)
2713
+ }
2714
+ return results
2715
+ }
2716
+
2717
+ /** An `naddr` or a `<kind>:<pubkey>:<d>`, or null for anything else. */
2718
+ function addressPointerOf(reference: string): AddressPointer | null {
2541
2719
  try {
2542
2720
  // Either form: a body carries `naddr1…`, an `a` tag carries the plain
2543
2721
  // address, and both name the same object (FEE-2).
2544
- pointer = referenceToPointer(naddr)
2722
+ return referenceToPointer(reference)
2545
2723
  } catch {
2546
2724
  return null
2547
2725
  }
2548
- const address = pointerToAddress(pointer)
2726
+ }
2549
2727
 
2550
- const resolved = await resolveManifest(pointer, query, cache)
2551
- if (!resolved) return null
2552
- const { manifest, viaRecommendation } = resolved
2728
+ /**
2729
+ * What one addressed object is read with, and what assembling it needs after.
2730
+ *
2731
+ * Split from the read so {@link resolveForeignObjects} can send many objects'
2732
+ * filters in one request and assemble each from the pooled answer, while
2733
+ * {@link resolveForeignObject} sends one object's and assembles it from its
2734
+ * own. Both go through here, so the two cannot drift apart.
2735
+ */
2736
+ interface ObjectPlan {
2737
+ naddr: string
2738
+ pointer: AddressPointer
2739
+ address: string
2740
+ resolved: ResolvedManifest
2741
+ projection: { widget: string | string[]; slots: Record<string, SlotSpec | SlotSpec[]> }
2742
+ records: RecordsRule
2743
+ commentKinds: number[]
2744
+ childFilter: ReturnType<typeof childFilterFor>
2745
+ filters: Record<string, unknown>[]
2746
+ openUrl?: string
2747
+ }
2748
+
2749
+ /** Null when the owning app has no projection for the kind. */
2750
+ function planObject(
2751
+ naddr: string,
2752
+ pointer: AddressPointer,
2753
+ resolved: ResolvedManifest,
2754
+ depth: number,
2755
+ ): ObjectPlan | null {
2756
+ const { manifest } = resolved
2757
+ const address = pointerToAddress(pointer)
2553
2758
  // Substituted here rather than in the component: `<bech32>` is a NIP-89
2554
2759
  // detail, and the widget's job is to draw a link, not to know the spec.
2555
2760
  const openUrl = resolved.webTemplate?.replace('<bech32>', naddr.replace(/^nostr:/, ''))
@@ -2576,46 +2781,79 @@ export async function resolveForeignObject(
2576
2781
  one, and with the manifest memoised it is the whole cost of a tick.
2577
2782
  */
2578
2783
  const childFilter = childFilterFor({ projection, manifest, pointer, depth })
2579
- const events = await query([
2784
+ const filters = [
2580
2785
  { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [pointer.identifier], limit: 1 },
2581
2786
  // Only when the app actually declares a change kind — see `foldRuleOf`.
2582
2787
  ...(manifest.records ? [{ kinds: [manifest.records.changeKind], '#a': [address], limit: 500 }] : []),
2583
2788
  { kinds: commentKinds, '#a': [address], limit: CONVERSATION_LIMIT },
2584
2789
  ...(childFilter ? [childFilter.filter] : []),
2585
- ])
2790
+ ]
2791
+ return { naddr, pointer, address, resolved, projection, records, commentKinds, childFilter, filters, openUrl }
2792
+ }
2793
+
2794
+ /** An object and its children, before the people lookup that needs both. */
2795
+ interface AssembledObject {
2796
+ object: ForeignObject
2797
+ children?: ForeignObject[]
2798
+ }
2799
+
2800
+ /**
2801
+ * Build a planned object out of whatever the relay answered.
2802
+ *
2803
+ * **Every event is matched on the criteria of the filter that asked for it**,
2804
+ * because the answer may hold more than this object's own events: the root
2805
+ * shares its request with its children (SHI-13), and in
2806
+ * {@link resolveForeignObjects} with every other object in the set. So the root
2807
+ * is matched on its author as well as its kind and `d` — two apps' objects may
2808
+ * share both — and a fold runs only when the manifest declares change events,
2809
+ * since the substitute rule's `changeKind` is a placeholder that was never
2810
+ * asked for (`foldRuleOf`).
2811
+ *
2812
+ * Deduplicated by id first. The relay concatenates what each filter matched
2813
+ * rather than merging it (measured, see `conversationsOf`), so an event two
2814
+ * filters match — a comment naming two files in the set, a `kind:9` that is a
2815
+ * Topic's child and its comment — would otherwise be drawn twice.
2816
+ */
2817
+ function assembleObject(plan: ObjectPlan, answered: SignedEvent[]): AssembledObject {
2818
+ const { naddr, pointer, address, resolved, projection, records, commentKinds, childFilter, openUrl } = plan
2819
+ const { manifest, viaRecommendation } = resolved
2820
+ const seen = new Set<string>()
2821
+ const events = answered.filter((e) => !seen.has(e.id) && !!seen.add(e.id))
2586
2822
 
2587
2823
  const root = events.find(
2588
- (e) => e.kind === pointer.kind && tagValue(e, 'd') === pointer.identifier,
2824
+ (e) => e.kind === pointer.kind && e.pubkey === pointer.pubkey && tagValue(e, 'd') === pointer.identifier,
2589
2825
  )
2590
2826
  if (!root) {
2591
2827
  // We know which app owns this and how it would be drawn; we just cannot see
2592
2828
  // the object. Say so rather than returning null and looking like a typo.
2593
2829
  return {
2594
- ref: address,
2595
- address,
2596
- naddr: naddr.replace(/^nostr:/, ''),
2597
- // Nothing was read, so there is no event to name. The reference is the
2598
- // address; that is all this case ever knows.
2599
- eventId: '',
2600
- kind: pointer.kind,
2601
- widget: projection.widget,
2602
- appName: manifest.name,
2603
- slots: {},
2604
- meta: [],
2605
- comments: [],
2606
- actions: [],
2607
- viaRecommendation,
2608
- // Offered even here. "You cannot see this object" is exactly when
2609
- // somebody wants to open it in the app that can.
2610
- openUrl,
2611
- unreachable: true,
2830
+ object: {
2831
+ ref: address,
2832
+ address,
2833
+ naddr: naddr.replace(/^nostr:/, ''),
2834
+ // Nothing was read, so there is no event to name. The reference is the
2835
+ // address; that is all this case ever knows.
2836
+ eventId: '',
2837
+ kind: pointer.kind,
2838
+ widget: projection.widget,
2839
+ appName: manifest.name,
2840
+ slots: {},
2841
+ meta: [],
2842
+ comments: [],
2843
+ actions: [],
2844
+ viaRecommendation,
2845
+ // Offered even here. "You cannot see this object" is exactly when
2846
+ // somebody wants to open it in the app that can.
2847
+ openUrl,
2848
+ unreachable: true,
2849
+ },
2612
2850
  }
2613
2851
  }
2614
2852
 
2615
2853
  const folded = foldChanges(
2616
- events.filter(
2617
- (e) => e.kind === records.changeKind && tagValue(e, records.targetTag) === address,
2618
- ),
2854
+ manifest.records
2855
+ ? events.filter((e) => e.kind === records.changeKind && tagValue(e, records.targetTag) === address)
2856
+ : [],
2619
2857
  records,
2620
2858
  )
2621
2859
 
@@ -2672,16 +2910,24 @@ export async function resolveForeignObject(
2672
2910
  viaRecommendation,
2673
2911
  })
2674
2912
 
2675
- // After the object, because who to ask about is not known until it is built.
2676
- // Folded into the same resolve rather than left to the renderer so the
2677
- // widget's skeleton covers the wait and a key is never briefly on screen.
2678
- // Children are included so one lookup covers the whole tree — a message list
2679
- // is mostly other people, and a second trip per child would show a column of
2680
- // keys while it ran.
2681
- const forPeople = [object, ...(children ?? [])]
2682
- const people = await (lookupPeople ?? peopleViaRelay(query))([
2683
- ...new Set(forPeople.flatMap(pubkeysIn)),
2684
- ])
2913
+ return { object, ...(children ? { children } : {}) }
2914
+ }
2915
+
2916
+ /**
2917
+ * Who an assembled object names — asked after the object, because who to ask
2918
+ * about is not known until it is built.
2919
+ *
2920
+ * Folded into the same resolve rather than left to the renderer so the
2921
+ * widget's skeleton covers the wait and a key is never briefly on screen.
2922
+ * Children are included so one lookup covers the whole tree — a message list
2923
+ * is mostly other people, and a second trip per child would show a column of
2924
+ * keys while it ran.
2925
+ */
2926
+ function peopleOf({ object, children }: AssembledObject): string[] {
2927
+ return [...new Set([object, ...(children ?? [])].flatMap(pubkeysIn))]
2928
+ }
2929
+
2930
+ function withPeople({ object, children }: AssembledObject, people: People): ForeignObject {
2685
2931
  return { ...object, people, ...(children ? { children: children.map((c) => ({ ...c, people })) } : {}) }
2686
2932
  }
2687
2933