@milaboratories/pl-tree 1.14.4 → 1.15.1

package/src/synchronized_tree.ts

@@ -16,8 +16,19 @@ import {
 } from "@milaboratories/pl-client";
 import type { ExtendedResourceData } from "./state";
 import { PlTreeState, TreeStateUpdateError } from "./state";
-import type { PruningFunction, TraversalMode, TreeLoadingStat } from "./sync";
-import { constructTreeLoadingRequest, initialTreeLoadingStat, loadTreeState } from "./sync";
+import type {
+  PruningFunction,
+  TraversalMode,
+  TreeLoadingAlgorithmName,
+  TreeLoadingStat,
+} from "./sync";
+import {
+  constructTreeLoadingRequest,
+  initialTreeLoadingStat,
+  loadTreeState,
+  resolveTreeLoadingAlgorithm,
+  supportsResourceTreeTraversal,
+} from "./sync";
 import type { PersistedTree } from "./persisted_tree";
 import { captureTreeState, restoreTreeState } from "./persisted_tree";
 import * as tp from "node:timers/promises";
@@ -61,7 +72,10 @@ export type SynchronizedTreeOps = {
   /** ResourceTree field filter for modern backend path. */
   fieldFilter?: Filter;
 
-  /** ResourceTree traversal stop rules for modern backend path. */
+  /** ResourceTree traversal stop rules for the streaming path.
+   * @deprecated the backend ignores these under a change token, and the delta algorithm - what
+   * `auto` now picks on a capable backend - never sends them. They still prune a
+   * `backend-streaming` walk and a token-less delta poll's fallback. */
   traverseStopRules?: Filter;
 
   /** Interval after last sync to sleep before the next one */
@@ -185,6 +199,15 @@ export class SynchronizedTreeState {
   private readonly fieldFilter?: Filter;
   private readonly traverseStopRules?: Filter;
   private readonly traversalMode: TraversalMode;
+  /** Resolved once from {@link traversalMode} and the server's capabilities, and used by every
+   * poll of this tree. Selecting per poll was only sound while no algorithm kept state between
+   * polls; pinning it here is what lets one do so. Only ever reassigned by the one-way
+   * demotion in {@link loadAndApply} when the backend advertises delta but issues no token. */
+  private algorithm: TreeLoadingAlgorithmName;
+  /** Change token the last successful delta apply was dated at, handed to the next poll so
+   * the backend sends only what moved since. Undefined until the first delta poll commits
+   * one, and again whenever {@link discardDeltaToken} drops it. */
+  private deltaToken: Uint8Array | undefined;
   private readonly logStat?: StatLoggingMode;
   private readonly hooks: PollingComputableHooks;
   private readonly abortController = new AbortController();
@@ -225,6 +248,12 @@ export class SynchronizedTreeState {
     this.fieldFilter = fieldFilter;
     this.traverseStopRules = traverseStopRules;
     this.traversalMode = traversalMode ?? "auto";
+    this.algorithm = resolveTreeLoadingAlgorithm(
+      this.traversalMode,
+      pl.serverInfo.capabilities ?? [],
+      logger,
+    );
+    logger?.info(`tree loading algorithm: ${this.algorithm} (traversalMode=${this.traversalMode})`);
     this.pollingInterval = pollingInterval;
     this.effectivePollingInterval = pollingInterval;
     this.finalPredicate = finalPredicateOverride ?? pl.finalPredicate;
@@ -430,6 +459,7 @@ export class SynchronizedTreeState {
       pruningFunction: this.pruning,
       fieldFilter: this.fieldFilter,
       traverseStopRules: this.traverseStopRules,
+      changedSinceToken: this.deltaToken,
     });
     // A shared-type-seed tree with no currently-discovered roots is legitimately empty:
     // there is nothing to traverse, and tx.resourceTree([]) would throw "at least one seed
@@ -437,21 +467,63 @@ export class SynchronizedTreeState {
     // adds roots later via setRoots(), which schedules the next refresh. Explicit-root trees
     // never hit this (their root set is non-empty by construction).
     if (request.seedResources.length === 0 && request.finalResources.size === 0) return;
-    const data = await this.pl.withReadTx(
+    const { data, nextToken } = await this.pl.withReadTx(
       "ReadingTree",
       async (tx) => {
-        return await loadTreeState(
+        // Started, not awaited, before the walk. The token dates the transaction rather than
+        // the response, so it is not an input to the request - the request carries the
+        // PREVIOUS poll's token. Awaiting it here would block on the tx-open response before
+        // sending the tree request, costing a whole round trip that streaming does not pay,
+        // because requests pipeline on one bidi stream and withReadTx does not await the open.
+        const tokenPromise =
+          this.algorithm === "backend-delta" ? tx.getNextSinceToken() : undefined;
+        const data = await loadTreeState(
           tx,
           request,
           stats,
           this.pl.serverInfo.capabilities ?? [],
-          this.traversalMode,
+          this.algorithm,
           this.logger,
         );
+        return { data, nextToken: await tokenPromise };
       },
       txOps,
     );
     this.state.updateFromResourceData(data, { allowOrphanInputs: true, stat: stats });
+
+    // Only with the whole batch applied: advancing past a partial apply loses the dropped
+    // resources for good. A throw above leaves the old token, so the next poll re-reads it.
+    if (nextToken !== undefined) this.deltaToken = nextToken;
+    else if (this.algorithm === "backend-delta") this.demoteFromDelta();
+  }
+
+  /** Give up on delta for the life of this tree, once, when the backend advertises
+   * `treeChangedSince:v1` but hands out no token.
+   *
+   * Without this the tree stays on delta with `deltaToken` permanently unset, and every poll
+   * is then a token-less delta poll: a full tree read that also sends no stop rules, so it
+   * transfers the subtrees the streaming path prunes away. Nothing else detects it -
+   * `deltaSuspectedFullAnswers` only fires when a token WAS sent - so it would run at the
+   * poll interval, forever, silently. Streaming is the correct destination: it is what `auto`
+   * would have picked without the capability, and it restores the stop rules. */
+  private demoteFromDelta() {
+    this.algorithm = supportsResourceTreeTraversal(this.pl.serverInfo.capabilities ?? [])
+      ? "backend-streaming"
+      : "client-bfs";
+    this.logger?.warn(
+      `tree: backend advertises treeChangedSince:v1 but issued no change token; ` +
+        `falling back to ${this.algorithm} for the life of this tree`,
+    );
+  }
+
+  /** Discards the change token, so the next delta poll asks for the full tree. Required
+   * whenever the mirror stops being a faithful record of what the token says we hold: a
+   * rebuild after {@link TreeStateUpdateError}, or a root-set change, which reshapes the
+   * traversal the token was earned under. */
+  private discardDeltaToken(reason: string) {
+    if (this.deltaToken === undefined) return;
+    this.deltaToken = undefined;
+    this.logger?.info(`tree delta token discarded (${reason}); next poll reads the full tree`);
   }
 
   /** Discovery sync for shared-type seeds: re-polls `ListUserResources` (gRPC-only) and
@@ -477,8 +549,16 @@ export class SynchronizedTreeState {
       for (const id of ids) discovered.add(id);
     }
 
+    const rootsChanged =
+      discovered.size !== this.discoveredRoots.length ||
+      this.discoveredRoots.some((id) => !discovered.has(id));
+
     this.discoveredRoots = [...discovered];
     this.state.setRoots(this.currentRootSet());
+
+    // A root arriving brings a subtree the token would skip as unchanged, and one leaving
+    // takes its subtree with it. Either way the token no longer describes what we hold.
+    if (rootsChanged) this.discardDeltaToken("root set changed");
   }
 
   /** If true this tree state is permanently terminaed. */
@@ -557,6 +637,8 @@ export class SynchronizedTreeState {
           this.state.invalidateTree("stat update error");
           // creating new tree with the full current root set (re-discovered on next iteration)
           this.state = new PlTreeState(this.currentRootSet(), this.finalPredicate);
+          // The new mirror holds nothing, so the old token would skip everything.
+          this.discardDeltaToken("tree rebuilt after update error");
 
           // scheduling state update without delay
           continue;