@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.
@@ -973,32 +973,44 @@ async function resolveAspectApp(aspect, query, cache,
973
973
  // a comment in it by its `nevent`. An app may publish one string for both,
974
974
  // as Peek does, or two.
975
975
  entity = 'naddr') {
976
- const key = `aspect:${aspect}:${entity}`;
976
+ return throughCache(cache, `aspect:${aspect}:${entity}`, async () => {
977
+ const handlers = await query([{ kinds: [KIND_HANDLER_INFORMATION], limit: HANDLER_SWEEP_LIMIT }]);
978
+ for (const candidate of [...handlers].sort((a, b) => b.created_at - a.created_at)) {
979
+ const manifest = parseManifest(candidate);
980
+ if (manifest?.aspect !== aspect)
981
+ continue;
982
+ const template = webTemplate(candidate, entity);
983
+ // Declaring the aspect and publishing nowhere to open a file is a manifest
984
+ // this consumer has no use for yet; keep looking rather than answer with
985
+ // an app that cannot be linked to.
986
+ if (!template)
987
+ continue;
988
+ return {
989
+ manifest,
990
+ address: `${candidate.kind}:${candidate.pubkey}:${tagValue(candidate, 'd') ?? ''}`,
991
+ viaRecommendation: false,
992
+ webTemplate: template,
993
+ };
994
+ }
995
+ return null;
996
+ });
997
+ }
998
+ /**
999
+ * The memo, then a shared read, then the network — in that order. A cache
1000
+ * without `share` (hand-written, or older) keeps the old behaviour exactly:
1001
+ * look up, read, remember.
1002
+ */
1003
+ async function throughCache(cache, key, read) {
977
1004
  const now = Date.now();
978
1005
  const memo = cache?.lookup(key, now);
979
1006
  if (memo)
980
1007
  return memo.value;
981
- const handlers = await query([{ kinds: [KIND_HANDLER_INFORMATION], limit: HANDLER_SWEEP_LIMIT }]);
982
- let answer = null;
983
- for (const candidate of [...handlers].sort((a, b) => b.created_at - a.created_at)) {
984
- const manifest = parseManifest(candidate);
985
- if (manifest?.aspect !== aspect)
986
- continue;
987
- const template = webTemplate(candidate, entity);
988
- // Declaring the aspect and publishing nowhere to open a file is a manifest
989
- // this consumer has no use for yet; keep looking rather than answer with
990
- // an app that cannot be linked to.
991
- if (!template)
992
- continue;
993
- answer = {
994
- manifest,
995
- address: `${candidate.kind}:${candidate.pubkey}:${tagValue(candidate, 'd') ?? ''}`,
996
- viaRecommendation: false,
997
- webTemplate: template,
998
- };
999
- break;
1000
- }
1001
- cache?.remember(key, answer, now);
1008
+ if (!cache)
1009
+ return read();
1010
+ if (cache.share)
1011
+ return cache.share(key, now, read);
1012
+ const answer = await read();
1013
+ cache.remember(key, answer, now);
1002
1014
  return answer;
1003
1015
  }
1004
1016
  /**
@@ -1010,10 +1022,54 @@ entity = 'naddr') {
1010
1022
  * reference per tick, for ever — is neither.
1011
1023
  */
1012
1024
  export const MANIFEST_TTL_MS = 5 * 60_000;
1025
+ /**
1026
+ * ## One read per manifest, however many resolves ask at once (PER-8)
1027
+ *
1028
+ * The memo only helps a resolve that starts after another has *finished*. A
1029
+ * consumer that resolves a set together — Peek's Screener does
1030
+ * `Promise.all(files.map(resolveObject))` every minute — starts every one of
1031
+ * them against the same cold entry, so each fetched the recommendation and the
1032
+ * manifest itself, and did it again every time the entry expired. Measured on
1033
+ * production: 133 of an idle tab's 385 requests in five minutes were manifest
1034
+ * lookups, against a meter that refused 74 of them.
1035
+ *
1036
+ * So a read in flight is shared: the second asker for a key joins the first
1037
+ * one's promise. A failure is shared the same way and **not** remembered — the
1038
+ * burst that caused it costs one request instead of one each, and the next
1039
+ * resolve asks afresh. Remembering it would blank every reference to that app
1040
+ * for the whole window over what may have been one refused request.
1041
+ */
1013
1042
  export function createProjectionCache(ttlMs = MANIFEST_TTL_MS) {
1014
1043
  const entries = new Map();
1044
+ const flights = new Map();
1045
+ // Bumped by `clear`, so a read that was in flight when a manifest was
1046
+ // republished does not write its stale answer back afterwards.
1047
+ let generation = 0;
1015
1048
  return {
1016
- clear: () => entries.clear(),
1049
+ clear: () => {
1050
+ generation += 1;
1051
+ entries.clear();
1052
+ flights.clear();
1053
+ },
1054
+ share(key, now, read) {
1055
+ const running = flights.get(key);
1056
+ if (running)
1057
+ return running;
1058
+ const began = generation;
1059
+ const flight = read().then((value) => {
1060
+ if (flights.get(key) === flight)
1061
+ flights.delete(key);
1062
+ if (began === generation)
1063
+ entries.set(key, { at: now, value });
1064
+ return value;
1065
+ }, (error) => {
1066
+ if (flights.get(key) === flight)
1067
+ flights.delete(key);
1068
+ throw error;
1069
+ });
1070
+ flights.set(key, flight);
1071
+ return flight;
1072
+ },
1017
1073
  lookup(key, now) {
1018
1074
  const found = entries.get(key);
1019
1075
  if (!found)
@@ -1065,14 +1121,7 @@ export async function resolveManifest(pointer, query, cache) {
1065
1121
  ? { ...bareFileManifest(), webTemplate: opener.webTemplate }
1066
1122
  : bareFileManifest();
1067
1123
  }
1068
- const key = `${pointer.kind}:${pointer.pubkey}`;
1069
- const now = Date.now();
1070
- const memo = cache?.lookup(key, now);
1071
- if (memo)
1072
- return memo.value;
1073
- const answer = await resolveManifestUncached(pointer, query);
1074
- cache?.remember(key, answer, now);
1075
- return answer;
1124
+ return throughCache(cache, `${pointer.kind}:${pointer.pubkey}`, () => resolveManifestUncached(pointer, query));
1076
1125
  }
1077
1126
  async function resolveManifestUncached(pointer, query) {
1078
1127
  const parse = parseManifest;
@@ -1721,20 +1770,140 @@ depth = 0,
1721
1770
  * omitting it is exactly the old behaviour.
1722
1771
  */
1723
1772
  cache) {
1724
- let pointer;
1773
+ const pointer = addressPointerOf(naddr);
1774
+ if (!pointer)
1775
+ return null;
1776
+ const resolved = await resolveManifest(pointer, query, cache);
1777
+ if (!resolved)
1778
+ return null;
1779
+ const plan = planObject(naddr, pointer, resolved, depth);
1780
+ if (!plan)
1781
+ return null;
1782
+ const assembled = assembleObject(plan, await query(plan.filters));
1783
+ if (assembled.object.unreachable)
1784
+ return assembled.object;
1785
+ return withPeople(assembled, await (lookupPeople ?? peopleViaRelay(query))(peopleOf(assembled)));
1786
+ }
1787
+ /**
1788
+ * Many addressed objects in one round trip — PER-10.
1789
+ *
1790
+ * {@link resolveForeignObject} costs one request per object once the manifest
1791
+ * is cached, and a consumer holding a set re-reads the whole set on every
1792
+ * refresh: Peek's Screener asked once per followed file, every minute, and an
1793
+ * idle Desk spent 144 of 194 requests in five minutes on exactly that, against
1794
+ * a relay that meters 300 a minute per person across every tab. This reads the
1795
+ * same objects with the same filters, **all of them in one POST** — chunked at
1796
+ * `MAX_FILTERS_PER_QUERY` the way {@link conversationsOf} is, since each object
1797
+ * asks up to four filters — then one people lookup for the whole set.
1798
+ *
1799
+ * So a refresh is `ceil(filters / 128)` requests and a people lookup, where it
1800
+ * was one request per object and a lookup each: two for any set of up to 32
1801
+ * objects, whatever their number.
1802
+ *
1803
+ * ## Same filters, same objects
1804
+ *
1805
+ * Each object's filters are exactly the ones {@link resolveForeignObject}
1806
+ * sends, so each keeps its own `limit` — one busy file cannot starve another's
1807
+ * comments, which is why this is not one filter naming every address. The
1808
+ * answers come back pooled, and every object is picked back out of the pool on
1809
+ * its filters' own criteria, the rule `childrenFrom` already follows for the
1810
+ * children that share a request with their parent. The result is keyed by the
1811
+ * reference as given, and each object is what `resolveForeignObject` returns
1812
+ * for it.
1813
+ *
1814
+ * A reference that is not an address, or whose app has no manifest or no
1815
+ * projection for its kind, is `null` — as it is from the single form. An event
1816
+ * reference (`nevent`, a bare id) is not an address and is `null` here; that
1817
+ * is {@link resolveForeignEvent}'s.
1818
+ *
1819
+ * **A failed read rejects the whole call**, as the single form throws. There is
1820
+ * no partial answer to give: the objects arrive pooled, so a chunk that failed
1821
+ * could have held any of them.
1822
+ */
1823
+ export async function resolveForeignObjects(references, query,
1824
+ /** Defaults to asking the relay. The browser passes a cached lookup. */
1825
+ lookupPeople,
1826
+ /** See {@link ProjectionCache}. Omitting it still reads each app's manifest once per call. */
1827
+ cache) {
1828
+ const results = {};
1829
+ const asked = [];
1830
+ for (const reference of new Set(references)) {
1831
+ const pointer = addressPointerOf(reference);
1832
+ results[reference] = null;
1833
+ if (pointer)
1834
+ asked.push({ reference, pointer });
1835
+ }
1836
+ if (asked.length === 0)
1837
+ return results;
1838
+ // One manifest per app, never per object — the reason `conversationsOf`
1839
+ // groups the same way. A cache would share these too, but a caller without
1840
+ // one should not pay per object for what every object of an app shares.
1841
+ const byApp = new Map();
1842
+ for (const { pointer } of asked)
1843
+ byApp.set(manifestKeyOf(pointer), pointer);
1844
+ const manifests = new Map();
1845
+ await Promise.all([...byApp].map(async ([key, pointer]) => {
1846
+ const resolved = await resolveManifest(pointer, query, cache);
1847
+ if (resolved)
1848
+ manifests.set(key, resolved);
1849
+ }));
1850
+ const plans = asked.flatMap(({ reference, pointer }) => {
1851
+ const resolved = manifests.get(manifestKeyOf(pointer));
1852
+ const plan = resolved && planObject(reference, pointer, resolved, 0);
1853
+ return plan ? [{ reference, plan }] : [];
1854
+ });
1855
+ if (plans.length === 0)
1856
+ return results;
1857
+ // Two spellings of one object — its `naddr` and its plain address — are two
1858
+ // answers (each keeps its own `openUrl`) and one set of filters.
1859
+ const filters = [];
1860
+ const planned = new Set();
1861
+ for (const { plan } of plans) {
1862
+ if (planned.has(plan.address))
1863
+ continue;
1864
+ planned.add(plan.address);
1865
+ filters.push(...plan.filters);
1866
+ }
1867
+ const chunks = [];
1868
+ for (let start = 0; start < filters.length; start += MAX_FILTERS_PER_QUERY) {
1869
+ chunks.push(filters.slice(start, start + MAX_FILTERS_PER_QUERY));
1870
+ }
1871
+ const events = (await Promise.all(chunks.map((chunk) => query(chunk)))).flat();
1872
+ const assembled = plans.map(({ reference, plan }) => ({ reference, built: assembleObject(plan, events) }));
1873
+ const wanted = [...new Set(assembled.flatMap(({ built }) => peopleOf(built)))];
1874
+ const reachable = assembled.some(({ built }) => !built.object.unreachable);
1875
+ const people = reachable ? await (lookupPeople ?? peopleViaRelay(query))(wanted) : {};
1876
+ for (const { reference, built } of assembled) {
1877
+ if (built.object.unreachable) {
1878
+ results[reference] = built.object;
1879
+ continue;
1880
+ }
1881
+ // Each object carries the people it names, as the single form's does —
1882
+ // not the whole set's, which would make an object's shape depend on what
1883
+ // it happened to be resolved beside.
1884
+ const own = {};
1885
+ for (const key of peopleOf(built))
1886
+ if (key in people)
1887
+ own[key] = people[key];
1888
+ results[reference] = withPeople(built, own);
1889
+ }
1890
+ return results;
1891
+ }
1892
+ /** An `naddr` or a `<kind>:<pubkey>:<d>`, or null for anything else. */
1893
+ function addressPointerOf(reference) {
1725
1894
  try {
1726
1895
  // Either form: a body carries `naddr1…`, an `a` tag carries the plain
1727
1896
  // address, and both name the same object (FEE-2).
1728
- pointer = referenceToPointer(naddr);
1897
+ return referenceToPointer(reference);
1729
1898
  }
1730
1899
  catch {
1731
1900
  return null;
1732
1901
  }
1902
+ }
1903
+ /** Null when the owning app has no projection for the kind. */
1904
+ function planObject(naddr, pointer, resolved, depth) {
1905
+ const { manifest } = resolved;
1733
1906
  const address = pointerToAddress(pointer);
1734
- const resolved = await resolveManifest(pointer, query, cache);
1735
- if (!resolved)
1736
- return null;
1737
- const { manifest, viaRecommendation } = resolved;
1738
1907
  // Substituted here rather than in the component: `<bech32>` is a NIP-89
1739
1908
  // detail, and the widget's job is to draw a link, not to know the spec.
1740
1909
  const openUrl = resolved.webTemplate?.replace('<bech32>', naddr.replace(/^nostr:/, ''));
@@ -1760,39 +1929,67 @@ cache) {
1760
1929
  one, and with the manifest memoised it is the whole cost of a tick.
1761
1930
  */
1762
1931
  const childFilter = childFilterFor({ projection, manifest, pointer, depth });
1763
- const events = await query([
1932
+ const filters = [
1764
1933
  { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [pointer.identifier], limit: 1 },
1765
1934
  // Only when the app actually declares a change kind — see `foldRuleOf`.
1766
1935
  ...(manifest.records ? [{ kinds: [manifest.records.changeKind], '#a': [address], limit: 500 }] : []),
1767
1936
  { kinds: commentKinds, '#a': [address], limit: CONVERSATION_LIMIT },
1768
1937
  ...(childFilter ? [childFilter.filter] : []),
1769
- ]);
1770
- const root = events.find((e) => e.kind === pointer.kind && tagValue(e, 'd') === pointer.identifier);
1938
+ ];
1939
+ return { naddr, pointer, address, resolved, projection, records, commentKinds, childFilter, filters, openUrl };
1940
+ }
1941
+ /**
1942
+ * Build a planned object out of whatever the relay answered.
1943
+ *
1944
+ * **Every event is matched on the criteria of the filter that asked for it**,
1945
+ * because the answer may hold more than this object's own events: the root
1946
+ * shares its request with its children (SHI-13), and in
1947
+ * {@link resolveForeignObjects} with every other object in the set. So the root
1948
+ * is matched on its author as well as its kind and `d` — two apps' objects may
1949
+ * share both — and a fold runs only when the manifest declares change events,
1950
+ * since the substitute rule's `changeKind` is a placeholder that was never
1951
+ * asked for (`foldRuleOf`).
1952
+ *
1953
+ * Deduplicated by id first. The relay concatenates what each filter matched
1954
+ * rather than merging it (measured, see `conversationsOf`), so an event two
1955
+ * filters match — a comment naming two files in the set, a `kind:9` that is a
1956
+ * Topic's child and its comment — would otherwise be drawn twice.
1957
+ */
1958
+ function assembleObject(plan, answered) {
1959
+ const { naddr, pointer, address, resolved, projection, records, commentKinds, childFilter, openUrl } = plan;
1960
+ const { manifest, viaRecommendation } = resolved;
1961
+ const seen = new Set();
1962
+ const events = answered.filter((e) => !seen.has(e.id) && !!seen.add(e.id));
1963
+ const root = events.find((e) => e.kind === pointer.kind && e.pubkey === pointer.pubkey && tagValue(e, 'd') === pointer.identifier);
1771
1964
  if (!root) {
1772
1965
  // We know which app owns this and how it would be drawn; we just cannot see
1773
1966
  // the object. Say so rather than returning null and looking like a typo.
1774
1967
  return {
1775
- ref: address,
1776
- address,
1777
- naddr: naddr.replace(/^nostr:/, ''),
1778
- // Nothing was read, so there is no event to name. The reference is the
1779
- // address; that is all this case ever knows.
1780
- eventId: '',
1781
- kind: pointer.kind,
1782
- widget: projection.widget,
1783
- appName: manifest.name,
1784
- slots: {},
1785
- meta: [],
1786
- comments: [],
1787
- actions: [],
1788
- viaRecommendation,
1789
- // Offered even here. "You cannot see this object" is exactly when
1790
- // somebody wants to open it in the app that can.
1791
- openUrl,
1792
- unreachable: true,
1968
+ object: {
1969
+ ref: address,
1970
+ address,
1971
+ naddr: naddr.replace(/^nostr:/, ''),
1972
+ // Nothing was read, so there is no event to name. The reference is the
1973
+ // address; that is all this case ever knows.
1974
+ eventId: '',
1975
+ kind: pointer.kind,
1976
+ widget: projection.widget,
1977
+ appName: manifest.name,
1978
+ slots: {},
1979
+ meta: [],
1980
+ comments: [],
1981
+ actions: [],
1982
+ viaRecommendation,
1983
+ // Offered even here. "You cannot see this object" is exactly when
1984
+ // somebody wants to open it in the app that can.
1985
+ openUrl,
1986
+ unreachable: true,
1987
+ },
1793
1988
  };
1794
1989
  }
1795
- const folded = foldChanges(events.filter((e) => e.kind === records.changeKind && tagValue(e, records.targetTag) === address), records);
1990
+ const folded = foldChanges(manifest.records
1991
+ ? events.filter((e) => e.kind === records.changeKind && tagValue(e, records.targetTag) === address)
1992
+ : [], records);
1796
1993
  /*
1797
1994
  Matched on the comment filter's own criteria — the kind **and** the `a` tag.
1798
1995
 
@@ -1844,16 +2041,22 @@ cache) {
1844
2041
  webTemplate: resolved.webTemplate,
1845
2042
  viaRecommendation,
1846
2043
  });
1847
- // After the object, because who to ask about is not known until it is built.
1848
- // Folded into the same resolve rather than left to the renderer so the
1849
- // widget's skeleton covers the wait and a key is never briefly on screen.
1850
- // Children are included so one lookup covers the whole tree — a message list
1851
- // is mostly other people, and a second trip per child would show a column of
1852
- // keys while it ran.
1853
- const forPeople = [object, ...(children ?? [])];
1854
- const people = await (lookupPeople ?? peopleViaRelay(query))([
1855
- ...new Set(forPeople.flatMap(pubkeysIn)),
1856
- ]);
2044
+ return { object, ...(children ? { children } : {}) };
2045
+ }
2046
+ /**
2047
+ * Who an assembled object names — asked after the object, because who to ask
2048
+ * about is not known until it is built.
2049
+ *
2050
+ * Folded into the same resolve rather than left to the renderer so the
2051
+ * widget's skeleton covers the wait and a key is never briefly on screen.
2052
+ * Children are included so one lookup covers the whole tree — a message list
2053
+ * is mostly other people, and a second trip per child would show a column of
2054
+ * keys while it ran.
2055
+ */
2056
+ function peopleOf({ object, children }) {
2057
+ return [...new Set([object, ...(children ?? [])].flatMap(pubkeysIn))];
2058
+ }
2059
+ function withPeople({ object, children }, people) {
1857
2060
  return { ...object, people, ...(children ? { children: children.map((c) => ({ ...c, people })) } : {}) };
1858
2061
  }
1859
2062
  /**