@milaboratories/pl-tree 1.14.3 → 1.15.0

package/src/delta_sync.ts

@@ -0,0 +1,221 @@
+import type { PlTransaction, SignedResourceId } from "@milaboratories/pl-client";
+import { isNotNullSignedResourceId } from "@milaboratories/pl-client";
+import type { ExtendedResourceData } from "./state";
+import { TreeStateUpdateError } from "./state";
+import type { TreeLoadingRequest, TreeLoadingStat } from "./sync";
+import { collectStatsForResource } from "./sync";
+
+/** Emit everything at or below this depth from a resolution seed, whatever its change token
+ * says. It bounds descent as well as emission: under a token the walk otherwise ends at the
+ * first unchanged resource (api.proto, changed_since_token), so without this a round returns
+ * the seeds alone and a newly attached subtree costs one sequential round trip per level.
+ *
+ * Deep enough to clear a subtree in one round, which is the trade: real server-side walk and
+ * downlink for those levels, against a round trip each at ~1.4s on a slow link. Not free -
+ * lower it if resolution rounds ever dominate a poll. */
+const RESOLUTION_DEPTH = 32;
+
+/** Every id a body points at. Exactly what `updateFromResourceData` refcounts, and it throws
+ * `orphan resource` for any that resolves to nothing. */
+function referencesOf(resource: ExtendedResourceData): SignedResourceId[] {
+  const refs: SignedResourceId[] = [];
+  if (isNotNullSignedResourceId(resource.error)) refs.push(resource.error);
+  for (const field of resource.fields) {
+    if (isNotNullSignedResourceId(field.value)) refs.push(field.value);
+    if (isNotNullSignedResourceId(field.error)) refs.push(field.error);
+  }
+  return refs;
+}
+
+/**
+ * One delta poll: hand the backend this transaction's change token, take only what is newer.
+ *
+ * The caller commits the token, and only after the whole batch applies - advancing it past a
+ * partial apply loses the dropped resources for good.
+ *
+ * Removals arrive as a rewrite of the referring resource, never as absence, and the refcount
+ * GC does the rest. There is deliberately no periodic full reconcile; the blind spot is a
+ * removal under a resource the mirror marked final, which streaming and BFS share.
+ */
+export async function loadDeltaTreeState(
+  tx: PlTransaction,
+  loadingRequest: TreeLoadingRequest,
+  stats?: TreeLoadingStat,
+  logger?: { warn: (msg: string) => void },
+): Promise<ExtendedResourceData[]> {
+  const {
+    seedResources,
+    finalResources,
+    roots,
+    knownResources,
+    pruningFunction,
+    fieldFilter,
+    traverseStopRules,
+    changedSinceToken,
+  } = loadingRequest;
+
+  // Stop rules are never sent. The backend ignores them under a usable token anyway, but a
+  // token-less poll then walks unpruned where streaming would have pruned. Sending them only
+  // when the token is absent would change the request shape between polls, which a token
+  // holder must not do - so the cost is warned about instead.
+  if (traverseStopRules !== undefined && changedSinceToken === undefined) {
+    logger?.warn(
+      "delta poll: traverseStopRules supplied but not sent, and this poll carries no token," +
+        " so the backend walk is unpruned where the streaming path would have pruned it",
+    );
+  }
+
+  // Seed at every non-final resource, not the roots. Required, not an optimisation: the
+  // backend ends a walk at the first unchanged resource, so a root-seeded poll never reaches a
+  // change under a quiet parent - measured at 0 of 3 changes delivered. algorithm_equivalence
+  // fails on its KV step if this is ever narrowed back to the roots.
+  //
+  // The seed set changes every poll and the token is deliberately NOT discarded for it, though
+  // api.proto counts it as a shape input. Safe because every seed is a resource the mirror
+  // already holds, so a change can only widen the result, and widening hides nothing.
+  // Discarding per poll would make every poll a full read and defeat the mechanism.
+  //
+  // The roots stand in when the frontier is empty: resourceTree needs at least one seed.
+  const seeds = seedResources.length > 0 ? seedResources : [...roots];
+  if (seeds.length === 0) return [];
+
+  const collected = new Map<SignedResourceId, ExtendedResourceData>();
+  // References neither the mirror nor this batch can satisfy; applying with one outstanding
+  // invalidates the whole tree. Maintained incrementally as frames arrive: rescanning
+  // everything collected once per round would be quadratic in a poll that needs several.
+  const missing = new Set<SignedResourceId>();
+  // Same ids, in arrival order, so a round consumes only what is new rather than walking the
+  // whole set. An id enters both exactly once: `collected` is checked before the add and never
+  // cleared, so nothing re-enters after it resolves.
+  const pending: SignedResourceId[] = [];
+  const collect = (resource: ExtendedResourceData) => {
+    collected.set(resource.id, resource);
+    missing.delete(resource.id);
+    for (const ref of referencesOf(resource))
+      if (!collected.has(ref) && !knownResources.has(ref) && !missing.has(ref)) {
+        missing.add(ref);
+        pending.push(ref);
+      }
+  };
+
+  let warnedStopMarker = false;
+  const consume = async (walkSeeds: SignedResourceId[], unconditionalDepth?: number) => {
+    if (stats) {
+      stats.roundTrips++;
+      stats.streamRounds++;
+      stats.deltaSeedsSent += walkSeeds.length;
+    }
+
+    for await (const frame of tx.resourceTree(walkSeeds, {
+      includeKv: true,
+      fieldFilter,
+      changedSinceToken,
+      unconditionalDepth,
+    })) {
+      // A body-less frame. The client reads that as a stop marker, and a stop marker can only
+      // follow traverse_stop_rules, which this path never sends. Nothing here needs it, so it
+      // is skipped - but not silently: reaching this means the backend put a meaning on a
+      // body-less frame that this client does not know, and a quiet skip would leave no trace
+      // of it. Warn once per poll rather than per frame, since a contract change would emit
+      // one of these for every resource visited.
+      if (frame.frameKind === "stopMarker") {
+        if (!warnedStopMarker) {
+          warnedStopMarker = true;
+          logger?.warn(
+            `delta poll: ignoring a body-less frame for ${frame.id}; this poll sent no ` +
+              `traverse stop rules, so the backend is using body-less frames for something ` +
+              `this client does not interpret`,
+          );
+        }
+        continue;
+      }
+
+      if (stats) stats.resourceFrames++;
+
+      // updateFromResourceData throws on any body for a held final resource and invalidates
+      // the tree. A token-less poll walks unpruned and emits exactly those, which is what the
+      // first poll after a restored snapshot does. Both sibling algorithms skip the same way.
+      // Safe for references: finalResources is a subset of knownResources.
+      if (finalResources.has(frame.id)) {
+        if (stats) stats.finalResourcesSkipped++;
+        continue;
+      }
+
+      // An explicit literal rather than two rest-spreads of the frame. Measured ~15% off the
+      // per-frame cost: a spread copies every property twice and gives the object a hidden
+      // class of its own, where this is the shape the streaming path already produces.
+      const resource: ExtendedResourceData = {
+        id: frame.id,
+        type: frame.type,
+        kind: frame.kind,
+        data: frame.data,
+        resourceReady: frame.resourceReady,
+        error: frame.error,
+        originalResourceId: frame.originalResourceId,
+        final: frame.final,
+        inputsLocked: frame.inputsLocked,
+        outputsLocked: frame.outputsLocked,
+        fields:
+          pruningFunction !== undefined
+            ? pruningFunction(frame as unknown as ExtendedResourceData)
+            : frame.fields,
+        kv: frame.kv,
+      };
+      if (stats) stats.prunedFields += frame.fields.length - resource.fields.length;
+
+      collect(resource);
+      collectStatsForResource(resource, stats);
+    }
+  };
+
+  await consume(seeds);
+
+  // Captured before the resolution rounds. They fetch unconditionally by design, so counting
+  // afterwards lets a modest unheld subtree inflate the total past a small mirror and report a
+  // refused token that was never refused.
+  const collectedFromPoll = collected.size;
+
+  // A body may reference a resource the response did not carry - a field repointed at one we
+  // never held. Ids already asked for are never re-requested, so the loop terminates: the tree
+  // is finite and `fetched` only grows.
+  //
+  // Deliberately unbounded on rounds. A round-count cap would turn a legal tree shape into a
+  // desktop error, since how deep the references chain is a property of what the backend
+  // allowed rather than of anything wrong here, and the streaming path's stop-marker follow-up
+  // loop has always run on the same assumption.
+  const fetched = new Set<SignedResourceId>();
+  while (missing.size > 0) {
+    const round = pending.splice(0).filter((id) => !fetched.has(id) && missing.has(id));
+    if (round.length === 0) {
+      // Asked for all of these and none arrived; a soft-deleted referent gets here, since
+      // those frames are dropped client-side. TreeStateUpdateError specifically: the poll loop
+      // rebuilds and discards the token for that class, where a plain Error is only logged and
+      // the identical request fails forever.
+      throw new TreeStateUpdateError(
+        `delta poll: ${missing.size} referenced resource(s) could not be resolved, first ${missing.values().next().value}`,
+      );
+    }
+    for (const id of round) fetched.add(id);
+
+    if (stats) stats.deltaResolutionRounds++;
+    await consume(round, RESOLUTION_DEPTH);
+  }
+
+  // A refused token is answered with the full tree and no error, so this is the only tell.
+  // Reported, not acted on: the response is a correct superset, and the token stored after
+  // this poll comes from the current instance, so it self-heals next poll.
+  if (
+    changedSinceToken !== undefined &&
+    knownResources.size > 0 &&
+    collectedFromPoll >= knownResources.size
+  ) {
+    if (stats) stats.deltaSuspectedFullAnswers++;
+    logger?.warn(
+      `delta poll: sent a token but received ${collectedFromPoll} resources against a mirror of ` +
+        `${knownResources.size}; the backend may have refused the token (instance change or ` +
+        `rewound numbering), in which case this poll cost a full tree read`,
+    );
+  }
+
+  return [...collected.values()];
+}

package/src/delta_sync_live.test.ts

@@ -0,0 +1,259 @@
+import { test, expect } from "vitest";
+import {
+  asSignedResourceId,
+  field,
+  hasCapability,
+  parseSignedResourceId,
+  TestHelpers,
+} from "@milaboratories/pl-client";
+import type { PlClient } from "@milaboratories/pl-client";
+import type { ExtendedResourceData } from "./state";
+import { TestStructuralResourceType1 } from "./test_utils";
+import { SynchronizedTreeState } from "./synchronized_tree";
+import { ConsoleLoggerAdapter } from "@milaboratories/ts-helpers";
+import type { TraversalMode } from "./sync";
+import tp from "timers/promises";
+
+/**
+ * Delta polling against a real backend, for correctness only. Cost (bytes and round trips per
+ * poll) is the benchmark's job, since stats are loop-internal with no public accessor.
+ *
+ * Everything here needs `treeChangedSince:v1`, which
+ * only a backend built from pl PR #2163 advertises, so each test skips rather than fails on
+ * one without it. The unit coverage in `delta_sync.test.ts` pins the client's own logic; what
+ * cannot be faked, and is what these are for, is the backend's own emission rule.
+ */
+/** Marks the test SKIPPED, not passed, when the backend cannot serve delta.
+ *
+ * These previously returned early, so on a backend without the capability the whole delta
+ * suite reported four green ticks over zero delta code. Skipped and passed are different
+ * signals and a run summary has to be able to tell them apart. */
+function skipUnlessDelta(pl: PlClient, ctx: { skip: (note?: string) => void }): boolean {
+  if (hasCapability(pl.serverInfo.capabilities ?? [], "treeChangedSince:v1")) return true;
+  ctx.skip("backend does not advertise treeChangedSince:v1 (needs pl PR #2163)");
+  return false;
+}
+
+const logger = new ConsoleLoggerAdapter(console);
+
+/** Whole-mirror comparison, so a retained-but-unreferenced resource or a dropped property
+ * shows up rather than only a differing count. */
+function canonicalShape(resources: ExtendedResourceData[]): string {
+  return resources
+    .map(
+      (r) =>
+        `${r.id}|${r.kind}|${r.final}|${r.inputsLocked}|${r.outputsLocked}|` +
+        `${r.fields
+          .map((f) => `${f.name}=${f.value}`)
+          .sort()
+          .join(",")}|kv:${r.kv
+          .map((kv) => kv.key)
+          .sort()
+          .join(",")}`,
+    )
+    .sort()
+    .join("\n");
+}
+
+/** A root with one child holding data, which is enough of a tree to poll. */
+async function seedTree(pl: PlClient) {
+  return await pl.withWriteTx(
+    "DeltaSeed",
+    async (tx) => {
+      const root = tx.createStruct(TestStructuralResourceType1);
+      const rootField = field(tx.clientRoot, "deltaRoot");
+      tx.createField(rootField, "Dynamic");
+      tx.setField(rootField, root);
+
+      const child = tx.createStruct(TestStructuralResourceType1);
+      const childField = field(root, "child");
+      tx.createField(childField, "Dynamic");
+      tx.setField(childField, child);
+
+      await tx.commit();
+      return { root: await root.globalId, child: await child.globalId };
+    },
+    { sync: true },
+  );
+}
+
+async function openTree(
+  pl: PlClient,
+  root: string,
+  traversalMode: TraversalMode,
+  extra: Record<string, unknown> = {},
+) {
+  return await SynchronizedTreeState.init(
+    pl,
+    root as never,
+    { stopPollingDelay: 50, pollingInterval: 10, traversalMode, ...extra } as never,
+    logger,
+  );
+}
+
+test("a delta poll delivers a change on a resource the mirror already holds", async (ctx) => {
+  await TestHelpers.withTempRoot(async (pl) => {
+    if (!skipUnlessDelta(pl, ctx)) return;
+
+    const { root, child } = await seedTree(pl);
+    const tree = await openTree(pl, root, "backend-delta");
+    try {
+      await tree.refreshState();
+
+      // Attach a new resource under the child, so the child's own state moves.
+      await pl.withWriteTx(
+        "DeltaMutate",
+        async (tx) => {
+          const grandchild = tx.createStruct(TestStructuralResourceType1);
+          const f = field(child as never, "grandchild");
+          tx.createField(f, "Dynamic");
+          tx.setField(f, grandchild);
+          await tx.commit();
+        },
+        { sync: true },
+      );
+
+      await tree.refreshState();
+
+      // The grandchild is a resource the mirror never held, referenced by a body the delta
+      // did carry: exactly the case the resolution round exists for.
+      const dump = tree.dumpState();
+      expect(dump.some((r) => r.fields.some((f) => f.name === "grandchild"))).toBe(true);
+    } finally {
+      await tree.terminate();
+    }
+  });
+});
+
+test("delta and streaming converge on the same mirror", async (ctx) => {
+  await TestHelpers.withTempRoot(async (pl) => {
+    if (!skipUnlessDelta(pl, ctx)) return;
+
+    const { root, child } = await seedTree(pl);
+
+    const delta = await openTree(pl, root, "backend-delta");
+    const streaming = await openTree(pl, root, "backend-streaming");
+    try {
+      await Promise.all([delta.refreshState(), streaming.refreshState()]);
+
+      await pl.withWriteTx(
+        "DeltaConverge",
+        async (tx) => {
+          const extra = tx.createStruct(TestStructuralResourceType1);
+          const f = field(child as never, "extra");
+          tx.createField(f, "Dynamic");
+          tx.setField(f, extra);
+          await tx.commit();
+        },
+        { sync: true },
+      );
+
+      // Poll both twice: delta needs the second to see the change settle, and streaming is
+      // idempotent, so this cannot favour either.
+      await Promise.all([delta.refreshState(), streaming.refreshState()]);
+      await Promise.all([delta.refreshState(), streaming.refreshState()]);
+
+      const shape = (t: SynchronizedTreeState) =>
+        t
+          .dumpState()
+          .map(
+            (r) =>
+              `${r.id}|${r.fields
+                .map((f) => `${f.name}=${f.value}`)
+                .sort()
+                .join(",")}`,
+          )
+          .sort();
+
+      expect(shape(delta)).toEqual(shape(streaming));
+    } finally {
+      await Promise.all([delta.terminate(), streaming.terminate()]);
+    }
+  });
+});
+
+test("a quiet parent: a change under an unchanged resource still arrives", async (ctx) => {
+  await TestHelpers.withTempRoot(async (pl) => {
+    if (!skipUnlessDelta(pl, ctx)) return;
+
+    const { root, child } = await seedTree(pl);
+    const tree = await openTree(pl, root, "backend-delta");
+    try {
+      await tree.refreshState();
+
+      // A KV write on the child does not rewrite the root, so the root stays quiet. With
+      // the child is its own seed, so the walk reaches it anyway. This is
+      // the assertion that justifies seeding the frontier rather than the roots.
+      await pl.withWriteTx(
+        "DeltaQuietParent",
+        async (tx) => {
+          tx.setKValue(child as never, "quiet", Buffer.from("value"));
+          await tx.commit();
+        },
+        { sync: true },
+      );
+
+      // Give the poll loop a couple of cycles: the change has to be reached, not just sent.
+      for (let i = 0; i < 3; i++) {
+        await tree.refreshState();
+        await tp.setTimeout(20);
+      }
+
+      const dump = tree.dumpState();
+      const childState = dump.find((r) => r.id === child);
+      expect(childState?.kv.some((kv) => kv.key === "quiet")).toBe(true);
+    } finally {
+      await tree.terminate();
+    }
+  });
+});
+
+test("a delta tree restored from a snapshot converges with streaming", async (ctx) => {
+  await TestHelpers.withTempRoot(async (pl) => {
+    if (!skipUnlessDelta(pl, ctx)) return;
+
+    const { root } = await seedTree(pl);
+
+    // Load through streaming, then hand that mirror to a delta tree via restoreFrom. This is
+    // the ordinary upgrade path and the one shape a cold open cannot produce: a POPULATED
+    // mirror whose first delta poll carries no token, so it is a full walk that also sends no
+    // stop rules. Bodies for resources the mirror holds as final must be skipped, or the apply
+    // throws; resources below them must not be retained unreferenced.
+    //
+    // The earlier version of this test opened a fresh delta tree after terminating the
+    // streaming one, which gave an EMPTY mirror and asserted nothing.
+    // The fixture must actually contain a final resource or the skip branch is never reached:
+    // DefaultFinalResourceDataPredicate marks none of the test resource types final, which is
+    // why an earlier version of this test passed with the skip disabled. Everything except the
+    // root goes final, so the root stays a seed and the tree can still poll.
+    const finalPredicateOverride = (r: { id: unknown }) => r.id !== root;
+
+    const warm = await openTree(pl, root, "backend-streaming", { finalPredicateOverride });
+    await warm.refreshState();
+    const witness = parseSignedResourceId(asSignedResourceId(root)).signature;
+    const snapshot = warm.capture(witness);
+    const streamingShape = canonicalShape(warm.dumpState());
+    await warm.terminate();
+
+    const delta = await SynchronizedTreeState.init(
+      pl,
+      root as never,
+      {
+        stopPollingDelay: 50,
+        pollingInterval: 10,
+        traversalMode: "backend-delta",
+        restoreFrom: snapshot,
+        finalPredicateOverride,
+      },
+      logger,
+    );
+    try {
+      expect(delta.wasRestoredFromSnapshot).toBe(true);
+      await delta.refreshState();
+      await delta.refreshState();
+      expect(canonicalShape(delta.dumpState())).toBe(streamingShape);
+    } finally {
+      await delta.terminate();
+    }
+  });
+}, 300_000);

package/src/sync.test.ts

@@ -6,7 +6,12 @@ import {
   TestHelpers,
 } from "@milaboratories/pl-client";
 import { PlTreeState } from "./state";
-import { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from "./sync";
+import {
+  constructTreeLoadingRequest,
+  initialTreeLoadingStat,
+  loadTreeState,
+  resolveTreeLoadingAlgorithm,
+} from "./sync";
 import type { TraversalMode } from "./sync";
 import { Computable } from "@milaboratories/computable";
 import { TestStructuralResourceType1 } from "./test_utils";
@@ -541,3 +546,71 @@ test("orphan-invariant-preserved: error referent streamed alongside stop marker"
   expect(ids).toEqual(["NG:0x1", "NG:0xE"]);
   // No throw means the invariant held throughout loadTreeState
 });
+
+//
+// Algorithm selection. These pin the contract that a capable backend is polled with a token
+// by default, and that an unavailable preference degrades rather than throwing.
+//
+
+test("auto prefers delta, then streaming, then BFS", () => {
+  expect(resolveTreeLoadingAlgorithm("auto", ["treeChangedSince:v1", "treeFilter:v2"])).toBe(
+    "backend-delta",
+  );
+  // Delta needs no treeFilter:v2 of its own.
+  expect(resolveTreeLoadingAlgorithm("auto", ["treeChangedSince:v1"])).toBe("backend-delta");
+  expect(resolveTreeLoadingAlgorithm("auto", ["treeFilter:v2"])).toBe("backend-streaming");
+  expect(resolveTreeLoadingAlgorithm("auto", [])).toBe("client-bfs");
+});
+
+test("an explicit mode is honoured over what auto would pick", () => {
+  const capable = ["treeChangedSince:v1", "treeFilter:v2"];
+  expect(resolveTreeLoadingAlgorithm("client-bfs", capable)).toBe("client-bfs");
+  expect(resolveTreeLoadingAlgorithm("backend-streaming", capable)).toBe("backend-streaming");
+  expect(resolveTreeLoadingAlgorithm("backend-delta", capable)).toBe("backend-delta");
+});
+
+test("backend-delta degrades to the best available path, with a warning, never a throw", () => {
+  const warnings: string[] = [];
+  const logger = { warn: (m: string) => warnings.push(m) };
+
+  expect(resolveTreeLoadingAlgorithm("backend-delta", ["treeFilter:v2"], logger)).toBe(
+    "backend-streaming",
+  );
+  expect(resolveTreeLoadingAlgorithm("backend-delta", [], logger)).toBe("client-bfs");
+
+  expect(warnings).toHaveLength(2);
+  for (const w of warnings) expect(w).toContain("treeChangedSince:v1");
+});
+
+test("loadTreeState routes into the delta path and passes the token through", async () => {
+  const received: { seeds?: string[]; token?: Uint8Array; stopRules?: unknown } = {};
+  const tx = {
+    resourceTree: (seeds: string[], opts: Record<string, unknown>) => {
+      received.seeds = seeds;
+      received.token = opts.changedSinceToken as Uint8Array;
+      received.stopRules = opts.traverseStopRules;
+      return (async function* () {})();
+    },
+  } as unknown as Parameters<typeof loadTreeState>[0];
+
+  const request = {
+    seedResources: ["NG:0x1"],
+    finalResources: new Set<string>(),
+    roots: ["NG:0x1"],
+    knownResources: new Set<string>(["NG:0x1"]),
+    changedSinceToken: new Uint8Array([9]),
+  } as unknown as Parameters<typeof loadTreeState>[1];
+
+  const stat = initialTreeLoadingStat();
+  // Via the mode, not by calling loadDeltaTreeState directly: this is the only test that
+  // proves the dispatch in loadTreeState reaches delta at all.
+  await loadTreeState(tx, request, stat, ["treeChangedSince:v1"], "auto", { warn: () => {} });
+
+  expect(received.seeds).toEqual(["NG:0x1"]);
+  expect(received.token).toEqual(new Uint8Array([9]));
+  expect(received.stopRules).toBeUndefined();
+  // True for delta as well as streaming: it marks a backend path, which is what state.ts
+  // reads to decide the BFS-only wasted-fetch attribution.
+  expect(stat.usedStreaming).toBe(true);
+  expect(stat.deltaSeedsSent).toBe(1);
+});