@milaboratories/pl-tree 1.13.7 → 1.14.1

package/src/state.ts

@@ -469,6 +469,14 @@ export class PlTreeState {
     this.resources.forEach((v) => cb(v));
   }
 
+  /** False once the tree has been invalidated (an inconsistent update, or termination of
+   *  its synchronization loop). {@link dumpState} deliberately reads through an invalid
+   *  tree, so anything persisting that dump must check this first: the contents of an
+   *  invalidated tree are not something to write to disk. */
+  public get isValid(): boolean {
+    return this._isValid;
+  }
+
   private checkValid() {
     if (!this._isValid) throw new Error(this.invalidationMessage ?? "tree is in invalid state");
   }

package/src/synchronized_tree.ts

@@ -3,6 +3,7 @@ import { PlTreeEntry, PlTreeRootsEntry } from "./accessors";
 import type {
   FinalResourceDataPredicate,
   PlClient,
+  ResourceSignature,
   ResourceType,
   SignedResourceId,
   TxOps,
@@ -17,6 +18,8 @@ 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 { PersistedTree } from "./persisted_tree";
+import { captureTreeState, restoreTreeState } from "./persisted_tree";
 import * as tp from "node:timers/promises";
 import type { MiLogger } from "@milaboratories/ts-helpers";
 
@@ -74,6 +77,19 @@ export type SynchronizedTreeOps = {
 
   /** Controls which tree-loading path to use.  Default `"auto"`. */
   traversalMode?: TraversalMode;
+
+  /** A previously persisted mirror to seed the tree with, before its first refresh, so that
+   * refresh transfers only what changed while the tree was gone.
+   *
+   * A snapshot that cannot be applied, or does not belong to this tree, is logged and dropped,
+   * leaving an ordinary cold open.
+   *
+   * A snapshot that applies but whose ids are dead is NOT handled here: its resources become
+   * this tree's seeds, so the first refresh fails and {@link init} rejects, where a cold open
+   * would have succeeded. Establishing that the signatures are still live is the caller's job
+   * (see {@link PersistedTree.witness}), as is deciding what to do when the first refresh is
+   * refused anyway. Ignored for trees with shared-type seeds, which rediscover their roots. */
+  restoreFrom?: PersistedTree;
 };
 
 /** An explicit resource to serve as a tree root. Several explicit seeds may be passed. */
@@ -116,7 +132,13 @@ const DISCOVERY_INTERVAL_MS = 3_000;
  * `resourcesUnchanged` is excluded by design, since a cycle that only re-fetched unchanged
  * state is exactly the idle case the backoff exists for. */
 function countedChanges(stat: TreeLoadingStat): number {
-  return stat.resourcesNew + stat.resourcesChanged + stat.resourcesMarkedFinal;
+  // `fieldsRemoved` is included despite being a per-field count, because it is the one change
+  // that never shows up in `resourcesChanged`: the removed-dynamic-field branch in
+  // `updateFromResourceData` does not set its `changed` flag, so a cycle that only dropped a
+  // field (and garbage-collected whatever it pointed at) otherwise reads as an idle cycle.
+  // That double-counts a resource that both changed and lost a field, which is harmless here:
+  // every caller compares this against an earlier value rather than reading it as a total.
+  return stat.resourcesNew + stat.resourcesChanged + stat.resourcesMarkedFinal + stat.fieldsRemoved;
 }
 
 /** The poll-cadence policy, as a pure function of the last cycle's outcome.
@@ -174,6 +196,15 @@ export class SynchronizedTreeState {
   /** Roots discovered for shared-type seeds on the last discovery poll. */
   private discoveredRoots: SignedResourceId[] = [];
 
+  /** Bumped once per refresh cycle that brought something new: a resource appeared, changed,
+   * or became final. Lets a holder tell whether the tree has moved since it last persisted
+   * it, without diffing state. Read through {@link changeGeneration}. */
+  private changeGenerationCounter = 0;
+
+  /** Whether a snapshot was actually applied. Read through
+   * {@link wasRestoredFromSnapshot}. */
+  private restoredFromSnapshot = false;
+
   private constructor(
     private readonly pl: PlClient,
     seeds: TreeSeed[],
@@ -218,6 +249,60 @@ export class SynchronizedTreeState {
     return new Set([...this.explicitRoots, ...this.discoveredRoots]);
   }
 
+  /** How many refresh cycles brought something new. Only ever increases. Equal values at two
+   * points in time mean nothing was added, changed or settled in between, which is what makes
+   * a periodic snapshot write skippable on an idle tree. */
+  public get changeGeneration(): number {
+    return this.changeGenerationCounter;
+  }
+
+  /** True only if a snapshot was actually applied as this tree's initial state. A snapshot can
+   * be supplied and still be refused (wrong roots, or state the update call will not accept),
+   * in which case this stays false and the tree started empty like any other. Passing
+   * `restoreFrom` is therefore not evidence of a warm start; this is. */
+  public get wasRestoredFromSnapshot(): boolean {
+    return this.restoredFromSnapshot;
+  }
+
+  /** Captures the current mirror for persistence.
+   *
+   * Must be called before {@link terminate}: terminating invalidates the tree, and capturing
+   * an invalidated tree is refused rather than silently written. */
+  public capture(witness: ResourceSignature): PersistedTree {
+    if (this.terminated) throw new Error("tree synchronization is terminated");
+    return captureTreeState(this.state, witness);
+  }
+
+  /** Installs a snapshot as this tree's state. Returns false if the snapshot was refused, in
+   * which case the tree is left as it was and the open proceeds cold.
+   *
+   * Only meaningful before the first refresh, which is why it is private and driven from
+   * {@link init}: replacing the state of a running tree would strand its observers. */
+  private restore(snapshot: PersistedTree): boolean {
+    if (this.sharedSeeds.length > 0) {
+      this.logger?.warn("ignoring tree snapshot: trees with shared-type seeds are not restored");
+      return false;
+    }
+
+    const roots = this.currentRootSet();
+    const snapshotRoots = new Set(snapshot.roots);
+    if (snapshotRoots.size !== roots.size || ![...snapshotRoots].every((r) => roots.has(r))) {
+      // A snapshot addressed to a different root is a mis-keyed file, not a stale one.
+      this.logger?.warn("ignoring tree snapshot: its roots are not this tree's roots");
+      return false;
+    }
+
+    const restored = restoreTreeState(snapshot, this.finalPredicate, {
+      roots,
+      logger: this.logger,
+    });
+    if (restored === undefined) return false;
+
+    this.state = restored;
+    this.restoredFromSnapshot = true;
+    return true;
+  }
+
   /** Resolves the single root for the backward-compatible single-root accessors, throwing
    * if the tree does not have exactly one root (guards legacy callers against multi-root). */
   private soleRoot(): SignedResourceId {
@@ -439,7 +524,9 @@ export class SynchronizedTreeState {
         // actual tree synchronization
         await this.refresh(stat);
 
-        this.updatePollingInterval(countedChanges(stat) > changesBefore);
+        const changed = countedChanges(stat) > changesBefore;
+        if (changed) this.changeGenerationCounter++;
+        this.updatePollingInterval(changed);
 
         // logging stats if we were asked to
         if (this.logStat && this.logger)
@@ -569,7 +656,13 @@ export class SynchronizedTreeState {
   ) {
     const tree = new SynchronizedTreeState(pl, normalizeSeeds(seeds), ops, logger);
 
-    const stat = ops.logStat ? initialTreeLoadingStat() : undefined;
+    // Seed from the snapshot before the first refresh, so that refresh is the one that
+    // transfers only what changed. A refused snapshot leaves an ordinary cold open.
+    const restored = ops.restoreFrom !== undefined && tree.restore(ops.restoreFrom);
+
+    // Always collected, even when not logging: the initial load's change count is what seeds
+    // the change generation, so a holder can tell a populated tree from an untouched one.
+    const stat = initialTreeLoadingStat();
 
     let ok = false;
 
@@ -581,10 +674,14 @@ export class SynchronizedTreeState {
       });
       ok = true;
     } finally {
+      if (countedChanges(stat) > 0) tree.changeGenerationCounter++;
+
       // logging stats if we were asked to (even if error occured)
-      if (stat && logger)
+      if (ops.logStat && logger)
         logger.info(
-          `Tree stat (initial load, ${ok ? "success" : "failure"}): ${JSON.stringify(stat)}`,
+          `Tree stat (initial load, ${ok ? "success" : "failure"}, ${
+            restored ? "restored from snapshot" : "cold"
+          }): ${JSON.stringify(stat)}`,
         );
     }