fix(tsp): cache sender resolution on the inbound path (#137)

An inbound TSP frame is awaited by the transport before it acks and before it
takes the next frame (R1.6), so whatever the handler does happens serially on
the one socket that also carries replies. `unpackInboundTsp` resolves the
sender's DID there — up to two network round-trips **per frame**, uncached.

A redelivery burst turns that into hundreds of serial fetches while an
in-flight request waits behind them. That is not hypothetical: a client that
starts acking a backlog it had never acked gets exactly one such burst on its
first connect, and a TSP reply timeout is a hard failure with no fallback, so
the request in flight does not degrade — it fails. The observed symptom was a
vault list that would not load over TSP immediately after an upgrade, and
worked once the backlog had drained.

Caching collapses a burst from one resolution per frame to one per peer.

TTL'd rather than invalidated on failure. Eviction would need the unpack result
plumbed back through a resolver that cannot see it, and redelivery already
supplies the retry: a frame refused against a stale key is redelivered — the
ack is withheld precisely because the handler threw — so a rotation costs at
most one TTL of refusals on a message that was going to be re-sent anyway.
Bounded, so a chatty socket cannot grow it without limit.

The cache is split over an injected resolver so it is testable as itself. The
obvious alternative — a test re-implementing the TTL and the bound and
asserting against its own copy — passes whatever the real policy does, which is
the one thing a cache test must not do. The bound is likewise asserted through
behaviour (the newest entry still hits, the oldest re-resolves) rather than by
exporting the Map.

Signed-off-by: Glenn Gore <glenn.g@affinidi.com>

Author: stormer78

packages/core/src/vta/tsp-vid.ts

@@ -176,3 +176,77 @@ export async function resolveTspEndpoint(
 export function resolveVtaTspEndpoint(vtaDid: string): Promise<TspRemoteEndpoint> {
   return resolveTspEndpoint(vtaDid, resolveDidDocument);
 }
+
+/** How long a resolved endpoint is reused. Short enough that a key rotation
+ *  heals on its own — an inbound frame is redelivered until acked, so a frame
+ *  refused against a stale key succeeds on a later delivery once this lapses —
+ *  and long enough that a delivery burst resolves once rather than per frame. */
+const ENDPOINT_TTL_MS = 5 * 60_000;
+/** Bound: one entry per peer, and a wallet talks to a handful. */
+const ENDPOINT_CACHE_MAX = 32;
+
+const endpointCache = new Map<string, { at: number; endpoint: TspRemoteEndpoint }>();
+
+/**
+ * {@link resolveVtaTspEndpoint} with a short-lived cache.
+ *
+ * For the **inbound** path this is not an optimisation, it is what keeps the
+ * socket moving. An inbound TSP frame is awaited by the transport before it
+ * acks (R1.6) and before it takes the next frame, so whatever happens per
+ * frame is serial on the one socket that also carries replies. Resolving a DID
+ * there costs up to two network round-trips *each*, and a redelivery burst —
+ * guaranteed on the first connect after a client starts acking a backlog it
+ * had never acked — turns that into hundreds of serial fetches while an
+ * in-flight request waits behind them. A TSP reply timeout is a hard failure
+ * with no fallback, so the request does not degrade, it fails.
+ *
+ * Caching collapses a burst from one resolution per frame to one per peer.
+ *
+ * Deliberately TTL'd rather than invalidated on failure: eviction would need
+ * the unpack result plumbed back through a resolver that cannot see it, and
+ * redelivery already provides the retry. A rotation costs at most `TTL` of
+ * refusals for a frame that is being redelivered anyway.
+ */
+export function resolveVtaTspEndpointCached(vid: string): Promise<TspRemoteEndpoint> {
+  return resolveTspEndpointCachedWith(vid, resolveVtaTspEndpoint);
+}
+
+/**
+ * The caching half of {@link resolveVtaTspEndpointCached}, over an injected
+ * resolver.
+ *
+ * Split out so the cache policy is testable as itself. The obvious
+ * alternative — a test that re-implements the TTL and the bound and asserts
+ * against its own copy — passes whatever the real policy does, which is the
+ * one thing a cache test must not do.
+ */
+export async function resolveTspEndpointCachedWith(
+  vid: string,
+  resolve: (vid: string) => Promise<TspRemoteEndpoint>,
+  now: () => number = Date.now,
+): Promise<TspRemoteEndpoint> {
+  const hit = endpointCache.get(vid);
+  if (hit && now() - hit.at < ENDPOINT_TTL_MS) return hit.endpoint;
+
+  const endpoint = await resolve(vid);
+  endpointCache.set(vid, { at: now(), endpoint });
+  if (endpointCache.size > ENDPOINT_CACHE_MAX) {
+    // Oldest insertion first — Map preserves it, and a wallet's peer set is
+    // small enough that the eviction policy barely matters; the bound is what
+    // matters.
+    const oldest = endpointCache.keys().next().value;
+    if (oldest !== undefined) endpointCache.delete(oldest);
+  }
+  return endpoint;
+}
+
+/** The reuse window, exported so a test states the policy's own number rather
+ *  than a copy of it. */
+export const TSP_ENDPOINT_TTL_MS = ENDPOINT_TTL_MS;
+
+/** Drop cached endpoints. For tests, and for a caller that knows a peer's keys
+ *  have moved and does not want to wait out the TTL. */
+export function clearTspEndpointCache(vid?: string): void {
+  if (vid === undefined) endpointCache.clear();
+  else endpointCache.delete(vid);
+}

packages/core/tests/tsp.endpoint-cache.mjs

@@ -0,0 +1,84 @@
+// The inbound path resolves a sender per frame, serially, on the socket that
+// also carries replies — so a burst that resolves per frame starves an
+// in-flight request into a hard TSP timeout. These test the real cache, over
+// an injected resolver, rather than a re-implementation of its policy.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  resolveTspEndpointCachedWith,
+  clearTspEndpointCache,
+  TSP_ENDPOINT_TTL_MS,
+} from "../dist/vta/index.js";
+
+/** A resolver that counts calls, so "did the cache work" is observable. */
+function counting(endpointFor = (vid) => ({ vid })) {
+  const state = { calls: 0 };
+  return [
+    async (vid) => {
+      state.calls++;
+      return endpointFor(vid);
+    },
+    state,
+  ];
+}
+
+test("a burst of frames from one peer resolves that peer once", async () => {
+  clearTspEndpointCache();
+  const [resolve, state] = counting();
+  // The shape of a redelivered backlog: many frames, one sender.
+  for (let i = 0; i < 200; i++) {
+    await resolveTspEndpointCachedWith("did:web:vta.example", resolve);
+  }
+  assert.equal(state.calls, 1, "200 frames must not be 200 DID resolutions");
+});
+
+test("an entry lapses, so a rotated key heals without explicit eviction", async () => {
+  clearTspEndpointCache();
+  let key = "old";
+  const [resolve] = counting(() => ({ key }));
+  let clock = 0;
+  const now = () => clock;
+
+  assert.equal((await resolveTspEndpointCachedWith("did:web:v.example", resolve, now)).key, "old");
+  key = "new";
+  // Inside the window the stale entry stands — and a frame refused against it
+  // is redelivered rather than lost, which is what makes a TTL sufficient on
+  // its own and eviction-on-failure unnecessary.
+  clock = TSP_ENDPOINT_TTL_MS - 1;
+  assert.equal((await resolveTspEndpointCachedWith("did:web:v.example", resolve, now)).key, "old");
+
+  clock = TSP_ENDPOINT_TTL_MS;
+  assert.equal((await resolveTspEndpointCachedWith("did:web:v.example", resolve, now)).key, "new");
+});
+
+test("clearing one peer leaves the others cached", async () => {
+  clearTspEndpointCache();
+  const [resolve, state] = counting();
+  await resolveTspEndpointCachedWith("did:web:a.example", resolve);
+  await resolveTspEndpointCachedWith("did:web:b.example", resolve);
+  assert.equal(state.calls, 2);
+
+  clearTspEndpointCache("did:web:a.example");
+  await resolveTspEndpointCachedWith("did:web:b.example", resolve);
+  assert.equal(state.calls, 2, "b must still be cached");
+  await resolveTspEndpointCachedWith("did:web:a.example", resolve);
+  assert.equal(state.calls, 3, "a must have been dropped");
+});
+
+test("the cache is bounded, so a chatty socket cannot grow it without limit", async () => {
+  clearTspEndpointCache();
+  const [resolve] = counting();
+  for (let i = 0; i < 100; i++) {
+    await resolveTspEndpointCachedWith(`did:web:peer-${i}.example`, resolve);
+  }
+  // Re-resolving the most recent peer must still be a hit; the oldest must have
+  // been evicted. Asserted through behaviour rather than by reading the Map,
+  // which is deliberately not exported.
+  const [resolve2, state2] = counting();
+  await resolveTspEndpointCachedWith("did:web:peer-99.example", resolve2);
+  assert.equal(state2.calls, 0, "the newest entry must survive");
+  await resolveTspEndpointCachedWith("did:web:peer-0.example", resolve2);
+  assert.equal(state2.calls, 1, "the oldest entry must have been evicted");
+});

packages/extension/src/offscreen.ts

@@ -39,6 +39,7 @@ import {
   resolveVtaServices,
   type VtaServices,
   resolveVtaTspEndpoint,
+  resolveVtaTspEndpointCached,
   unpackInboundTsp,
   RestChannel,
   TspChannel,
@@ -2071,7 +2072,13 @@ async function onInboundTspFrame(
       // operator-enrolled control plane. Whether the sender is one we accept
       // is decided downstream, on the document's proof — not here, and not on
       // the strength of the transport.
-      resolveSender: resolveVtaTspEndpoint,
+      //
+      // The **cached** form, because this runs serially per frame on the socket
+      // that also carries replies: an uncached resolution here is up to two
+      // network round-trips per inbound frame, and a redelivery burst starves
+      // an in-flight request into a hard TSP timeout. See
+      // `resolveVtaTspEndpointCached`.
+      resolveSender: resolveVtaTspEndpointCached,
     });
   } catch (err) {
     // Logged, not swallowed: a frame that repeatedly fails to verify is a