@gmickel/gno 1.34.4 → 1.34.6

package/src/serve/watch-snapshot-ops.ts

@@ -0,0 +1,399 @@
+/**
+ * Build and diff orchestration for watcher snapshots.
+ * Hint reconciliation lives in `watch-snapshot-resolve`.
+ *
+ * @module src/serve/watch-snapshot-ops
+ */
+
+import type {
+  DiffWorkResult,
+  SnapshotEntryFingerprint,
+  WatcherSnapshot,
+  WatcherSnapshotBuildResult,
+  WatcherSnapshotDiffResult,
+  WatcherSnapshotFs,
+  WatcherSnapshotOptions,
+} from "./watch-snapshot-types";
+
+import {
+  cloneDirectoryMaps,
+  defaultClock,
+  defaultFs,
+  freezeSnapshot,
+  readDirectChildren,
+  removeSubtreeFromMaps,
+  setDirectoryEntries,
+  type MutableSnapshotMaps,
+} from "./watch-snapshot-scan";
+import {
+  WATCHER_SNAPSHOT_ENTRY_CEILING,
+  fingerprintsEqual,
+  isWatcherSourceKind,
+  joinWatcherRelPath,
+  normalizeWatcherRelPath,
+  sortPathList,
+} from "./watch-snapshot-types";
+
+/**
+ * Build a full no-follow hierarchical snapshot of `rootAbs`.
+ * On overflow, scan failure, or unreliable metadata the last proven snapshot
+ * is untouched (this function simply does not return one).
+ */
+export async function buildWatcherSnapshot(
+  rootAbs: string,
+  options: WatcherSnapshotOptions = {}
+): Promise<WatcherSnapshotBuildResult> {
+  const fs = options.fs ?? defaultFs;
+  const clock = options.clock ?? defaultClock;
+  const ceiling = options.entryCeiling ?? WATCHER_SNAPSHOT_ENTRY_CEILING;
+  const started = clock.nowMs();
+
+  const state: MutableSnapshotMaps = {
+    directories: new Map(),
+    entryCount: 0,
+  };
+  // Cursor-index queue avoids O(n) shift on large directory sets.
+  const queue: string[] = [""];
+  let head = 0;
+
+  while (head < queue.length) {
+    const dirRel = queue[head] as string;
+    head += 1;
+    // Remaining slots before this directory map is installed.
+    const remaining = ceiling - state.entryCount;
+    if (remaining < 0) {
+      return {
+        status: "fallback",
+        reason: "overflow",
+        durationMs: clock.nowMs() - started,
+      };
+    }
+    const scanned = await readDirectChildren(rootAbs, dirRel, fs, remaining);
+    if (scanned.status === "missing") {
+      if (dirRel === "") {
+        return {
+          status: "fallback",
+          reason: "scan_failed",
+          durationMs: clock.nowMs() - started,
+          cause: new Error("Collection root is missing"),
+        };
+      }
+      // Nested directory vanished mid-scan: fail closed rather than prove removals.
+      return {
+        status: "fallback",
+        reason: "scan_failed",
+        durationMs: clock.nowMs() - started,
+        cause: new Error(`Directory vanished during snapshot: ${dirRel}`),
+      };
+    }
+    if (scanned.status !== "present") {
+      return {
+        status: "fallback",
+        reason: scanned.status,
+        durationMs: clock.nowMs() - started,
+        cause: scanned.status === "scan_failed" ? scanned.cause : undefined,
+      };
+    }
+
+    setDirectoryEntries(state, dirRel, scanned.entries);
+    if (state.entryCount > ceiling) {
+      return {
+        status: "fallback",
+        reason: "overflow",
+        durationMs: clock.nowMs() - started,
+      };
+    }
+
+    for (const [name, fingerprint] of scanned.entries) {
+      // No-follow: never recurse through symlinks (even if they point inside root).
+      if (fingerprint.kind === "directory") {
+        queue.push(joinWatcherRelPath(dirRel, name));
+      }
+    }
+  }
+
+  return {
+    status: "ok",
+    snapshot: freezeSnapshot(state),
+    durationMs: clock.nowMs() - started,
+  };
+}
+
+/**
+ * Diff one or more dirty directories against the last proven snapshot.
+ *
+ * - Compares direct children only
+ * - Recurses into changed or new real directories
+ * - Expands removals hierarchically from the old snapshot (O(subtree))
+ * - Emits explicit `removals` separate from present/changed `candidates`
+ * - Never mutates `previous`; overflow/failure leaves it as the last proven state
+ */
+export async function diffWatcherSnapshot(
+  rootAbs: string,
+  previous: WatcherSnapshot,
+  dirtyDirectories: readonly string[],
+  options: WatcherSnapshotOptions = {}
+): Promise<WatcherSnapshotDiffResult> {
+  const fs = options.fs ?? defaultFs;
+  const clock = options.clock ?? defaultClock;
+  const ceiling = options.entryCeiling ?? WATCHER_SNAPSHOT_ENTRY_CEILING;
+  const mapHooks = options.mapHooks;
+  const started = clock.nowMs();
+
+  const normalizedDirs: string[] = [];
+  for (const raw of dirtyDirectories) {
+    const normalized = normalizeWatcherRelPath(raw === "" ? "." : raw);
+    // `normalizeWatcherRelPath(".")` → `""`; empty string is the root and is
+    // already valid. Accept explicit "" without going through normalize of "".
+    if (raw === "") {
+      normalizedDirs.push("");
+      continue;
+    }
+    if (normalized === null) {
+      // Invalid dirty directory: ignore as a no-op rather than failing the batch.
+      // Callers should resolve hints first; this guard keeps the primitive safe.
+      continue;
+    }
+    normalizedDirs.push(normalized);
+  }
+
+  if (normalizedDirs.length === 0) {
+    return {
+      status: "ok",
+      candidates: [],
+      removals: [],
+      nextSnapshot: previous,
+      discoveryMs: clock.nowMs() - started,
+    };
+  }
+
+  const nextState = cloneDirectoryMaps(previous);
+  const candidates = new Set<string>();
+  const removals = new Set<string>();
+  const visited = new Set<string>();
+
+  const recordSubtreeRemovals = (dirRel: string): void => {
+    // One hierarchical collect+remove pass — no prior full-map scan.
+    for (const path of removeSubtreeFromMaps(nextState, dirRel, mapHooks)) {
+      removals.add(path);
+    }
+  };
+
+  const diffDirectory = async (dirRel: string): Promise<DiffWorkResult> => {
+    if (visited.has(dirRel)) {
+      return { status: "ok" };
+    }
+    visited.add(dirRel);
+
+    // Replacement frees prior slots for this directory map before the new scan.
+    const previousSize = nextState.directories.get(dirRel)?.size ?? 0;
+    const remaining = ceiling - nextState.entryCount + previousSize;
+    if (remaining < 0) {
+      return { status: "overflow" };
+    }
+    const scanned = await readDirectChildren(rootAbs, dirRel, fs, remaining);
+    if (scanned.status === "missing") {
+      // Open-time ENOENT/ENOTDIR is never directory-deletion proof.
+      // A nested dirty target may have raced into a file/symlink/other after
+      // resolve, and recursive open may disagree with a parent listing that
+      // still observed a directory — both are inconsistent scans. Deletion is
+      // proven only when a successful containing-parent listing observes the
+      // child absent (handled via oldFp && !newFp below).
+      return {
+        status: "scan_failed",
+        cause: new Error(
+          dirRel === ""
+            ? "Collection root is missing"
+            : `Directory open failed (missing or not a directory): ${dirRel}`
+        ),
+      };
+    }
+    if (scanned.status !== "present") {
+      return scanned;
+    }
+
+    const oldEntries =
+      nextState.directories.get(dirRel) ??
+      new Map<string, SnapshotEntryFingerprint>();
+    const newEntries = scanned.entries;
+    setDirectoryEntries(nextState, dirRel, new Map(newEntries));
+
+    if (nextState.entryCount > ceiling) {
+      return { status: "overflow" };
+    }
+
+    const names = new Set([...oldEntries.keys(), ...newEntries.keys()]);
+    for (const name of names) {
+      const oldFp = oldEntries.get(name);
+      const newFp = newEntries.get(name);
+      const childRel = joinWatcherRelPath(dirRel, name);
+
+      if (oldFp && !newFp) {
+        // Removed entry: expand prior subtree for directories; files/symlinks directly.
+        // `other` was never an indexable source — drop fingerprint only.
+        if (oldFp.kind === "directory") {
+          recordSubtreeRemovals(childRel);
+        } else if (isWatcherSourceKind(oldFp.kind)) {
+          removals.add(childRel);
+        }
+        continue;
+      }
+
+      if (newFp && !oldFp) {
+        // Added entry. Candidates are file/symlink only — ignore new FIFO/etc.
+        if (newFp.kind === "directory") {
+          const built = await scanNewSubtree(
+            rootAbs,
+            childRel,
+            fs,
+            nextState,
+            candidates,
+            ceiling
+          );
+          if (built.status !== "ok") {
+            return built;
+          }
+        } else if (isWatcherSourceKind(newFp.kind)) {
+          candidates.add(childRel);
+        }
+        // new `other`: fingerprint retained for future transitions; no candidate.
+        continue;
+      }
+
+      if (oldFp && newFp && !fingerprintsEqual(oldFp, newFp)) {
+        // Changed entry — handle kind transitions with the other-kind contract.
+        if (oldFp.kind === "directory" && newFp.kind !== "directory") {
+          // Directory → file/symlink/other: expand nested indexable removals.
+          recordSubtreeRemovals(childRel);
+          if (isWatcherSourceKind(newFp.kind)) {
+            candidates.add(childRel);
+          }
+          // directory → other: no candidate for the special entry.
+          continue;
+        }
+
+        if (oldFp.kind !== "directory" && newFp.kind === "directory") {
+          // File/symlink → directory: old source is removable.
+          // Other → directory: prior other was never indexed — no removal.
+          if (isWatcherSourceKind(oldFp.kind)) {
+            removals.add(childRel);
+          }
+          const built = await scanNewSubtree(
+            rootAbs,
+            childRel,
+            fs,
+            nextState,
+            candidates,
+            ceiling
+          );
+          if (built.status !== "ok") {
+            return built;
+          }
+          continue;
+        }
+
+        if (newFp.kind === "directory") {
+          // Directory → directory (metadata change): recurse.
+          const nested = await diffDirectory(childRel);
+          if (nested.status !== "ok") {
+            return nested;
+          }
+          continue;
+        }
+
+        // Both non-directory.
+        if (
+          isWatcherSourceKind(oldFp.kind) &&
+          isWatcherSourceKind(newFp.kind)
+        ) {
+          // file↔symlink or metadata change on an indexable source.
+          candidates.add(childRel);
+        } else if (isWatcherSourceKind(oldFp.kind) && newFp.kind === "other") {
+          // file/symlink → other: remove old path; special entry is not a candidate.
+          removals.add(childRel);
+        } else if (oldFp.kind === "other" && isWatcherSourceKind(newFp.kind)) {
+          // other → file/symlink: new source is a candidate.
+          candidates.add(childRel);
+        }
+        // other → other (metadata): fingerprint only.
+      }
+      // Equal fingerprints: leave alone (do not recurse into unchanged dirs).
+    }
+
+    return { status: "ok" };
+  };
+
+  for (const dir of normalizedDirs) {
+    const result = await diffDirectory(dir);
+    if (result.status !== "ok") {
+      return {
+        status: "fallback",
+        reason: result.status,
+        discoveryMs: clock.nowMs() - started,
+        cause: result.status === "scan_failed" ? result.cause : undefined,
+      };
+    }
+  }
+
+  if (nextState.entryCount > ceiling) {
+    return {
+      status: "fallback",
+      reason: "overflow",
+      discoveryMs: clock.nowMs() - started,
+    };
+  }
+
+  return {
+    status: "ok",
+    candidates: sortPathList(candidates),
+    removals: sortPathList(removals),
+    nextSnapshot: freezeSnapshot(nextState),
+    discoveryMs: clock.nowMs() - started,
+  };
+}
+
+async function scanNewSubtree(
+  rootAbs: string,
+  dirRel: string,
+  fs: WatcherSnapshotFs,
+  state: MutableSnapshotMaps,
+  candidates: Set<string>,
+  ceiling: number
+): Promise<DiffWorkResult> {
+  const queue = [dirRel];
+  let head = 0;
+  while (head < queue.length) {
+    const current = queue[head] as string;
+    head += 1;
+    const previousSize = state.directories.get(current)?.size ?? 0;
+    const remaining = ceiling - state.entryCount + previousSize;
+    if (remaining < 0) {
+      return { status: "overflow" };
+    }
+    const scanned = await readDirectChildren(rootAbs, current, fs, remaining);
+    if (scanned.status === "missing") {
+      // New directory vanished while scanning — fail closed.
+      return {
+        status: "scan_failed",
+        cause: new Error(`New directory vanished during scan: ${current}`),
+      };
+    }
+    if (scanned.status !== "present") {
+      return scanned;
+    }
+    setDirectoryEntries(state, current, new Map(scanned.entries));
+    if (state.entryCount > ceiling) {
+      return { status: "overflow" };
+    }
+    for (const [name, fingerprint] of scanned.entries) {
+      const childRel = joinWatcherRelPath(current, name);
+      if (fingerprint.kind === "directory") {
+        queue.push(childRel);
+      } else if (isWatcherSourceKind(fingerprint.kind)) {
+        candidates.add(childRel);
+      }
+      // Nested `other` under a new directory: fingerprint only, never a candidate.
+    }
+  }
+  return { status: "ok" };
+}

package/src/serve/watch-snapshot-resolve.ts

@@ -0,0 +1,246 @@
+/**
+ * Untrusted watcher hint → dirty directory resolution + reconcile orchestration.
+ *
+ * Resolves path components one at a time from an anchored root handle so
+ * intermediate symlinks are never descended and outside children are never
+ * lstat'd through a link-out prefix.
+ *
+ * @module src/serve/watch-snapshot-resolve
+ */
+
+// node:path — Bun has no path utilities
+import { resolve, sep } from "node:path";
+
+import type {
+  WatcherDirHandle,
+  WatcherSnapshot,
+  WatcherSnapshotDiffResult,
+  WatcherSnapshotOptions,
+} from "./watch-snapshot-types";
+
+import { diffWatcherSnapshot } from "./watch-snapshot-ops";
+import { defaultClock, defaultFs } from "./watch-snapshot-scan";
+import {
+  isMissingFsError,
+  joinWatcherRelPath,
+  normalizeWatcherRelPath,
+  parentWatcherDir,
+} from "./watch-snapshot-types";
+
+/**
+ * Resolve an untrusted hint to the dirty directory that should be diffed.
+ * Missing paths climb to the nearest surviving in-root ancestor.
+ *
+ * A missing collection root is not a deletion proof: returns scan_failed
+ * fallback so callers do not emit removal candidates or advance snapshots.
+ *
+ * Symlink (or non-directory) components stop descent: the containing directory
+ * is returned so the parent listing observes the link/file without following it.
+ */
+export async function resolveWatcherDirtyDirectory(
+  rootAbs: string,
+  hint: string,
+  options: WatcherSnapshotOptions = {}
+): Promise<
+  | { status: "ok"; directory: string }
+  | { status: "invalid" }
+  | { status: "fallback"; reason: "scan_failed"; cause?: unknown }
+> {
+  const normalized = normalizeWatcherRelPath(hint);
+  if (normalized === null) {
+    return { status: "invalid" };
+  }
+
+  // Reject absolute-after-join escapes: only allow paths under rootAbs lexically.
+  const rootResolved = resolve(rootAbs);
+  if (normalized !== "") {
+    const absCandidate = resolve(rootResolved, ...normalized.split("/"));
+    const rel = absCandidate.startsWith(rootResolved + sep)
+      ? absCandidate.slice(rootResolved.length + sep.length)
+      : absCandidate === rootResolved
+        ? ""
+        : null;
+    if (rel === null) {
+      return { status: "invalid" };
+    }
+  }
+
+  const fs = options.fs ?? defaultFs;
+  if (!fs.supportsAnchoredHandles) {
+    return {
+      status: "fallback",
+      reason: "scan_failed",
+      cause: new Error(
+        "Anchored no-follow directory handles unavailable; refusing path-based hint resolution"
+      ),
+    };
+  }
+
+  let rootHandle: WatcherDirHandle;
+  try {
+    rootHandle = await fs.openDir(rootResolved);
+  } catch (cause) {
+    if (isMissingFsError(cause)) {
+      return {
+        status: "fallback",
+        reason: "scan_failed",
+        cause: new Error("Collection root is missing"),
+      };
+    }
+    return { status: "fallback", reason: "scan_failed", cause };
+  }
+
+  const opened: WatcherDirHandle[] = [rootHandle];
+  const closeAll = async (): Promise<void> => {
+    for (let i = opened.length - 1; i >= 0; i -= 1) {
+      const handle = opened[i];
+      if (handle) {
+        await fs.closeDir(handle);
+      }
+    }
+    opened.length = 0;
+  };
+
+  try {
+    if (normalized === "") {
+      return { status: "ok", directory: "" };
+    }
+
+    const segments = normalized.split("/");
+    let parentHandle = rootHandle;
+    let parentRel = "";
+
+    for (let index = 0; index < segments.length; index += 1) {
+      const segment = segments[index] as string;
+      let stat;
+      try {
+        stat = await fs.lstatChild(parentHandle, segment);
+      } catch (cause) {
+        if (isMissingFsError(cause)) {
+          // Missing component: dirty directory is the nearest surviving ancestor.
+          return { status: "ok", directory: parentRel };
+        }
+        return {
+          status: "fallback",
+          reason: "scan_failed",
+          cause: new Error(`Failed to inspect hint segment: ${segment}`),
+        };
+      }
+
+      const childRel = joinWatcherRelPath(parentRel, segment);
+      const isLast = index === segments.length - 1;
+
+      // Never descend through symlink / file / other — parent listing is dirty.
+      if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        return { status: "ok", directory: parentRel };
+      }
+
+      // Real directory.
+      if (isLast) {
+        return { status: "ok", directory: childRel };
+      }
+
+      try {
+        const childHandle = await fs.openChildDir(parentHandle, segment);
+        opened.push(childHandle);
+        parentHandle = childHandle;
+        parentRel = childRel;
+      } catch (cause) {
+        if (isMissingFsError(cause)) {
+          return { status: "ok", directory: parentRel };
+        }
+        return { status: "fallback", reason: "scan_failed", cause };
+      }
+    }
+
+    return { status: "ok", directory: parentRel };
+  } finally {
+    await closeAll();
+  }
+}
+
+/** True when `dirRel` is a directory edge under its parent in `snapshot`. */
+function directoryHasParentEdge(
+  snapshot: WatcherSnapshot,
+  dirRel: string
+): boolean {
+  if (dirRel === "") {
+    return true;
+  }
+  const parent = parentWatcherDir(dirRel);
+  if (parent === null) {
+    return true;
+  }
+  const base = dirRel.slice(parent === "" ? 0 : parent.length + 1);
+  return snapshot.directories.get(parent)?.get(base)?.kind === "directory";
+}
+
+/**
+ * Choose the dirty directory for a resolved on-disk directory hint.
+ * New-relative-to-snapshot directories climb to the nearest known container so
+ * parent edges are recorded (no orphan maps).
+ */
+function dirtyDirectoryForResolvedHint(
+  previous: WatcherSnapshot,
+  dirRel: string
+): string {
+  if (dirRel === "" || directoryHasParentEdge(previous, dirRel)) {
+    return dirRel;
+  }
+  let climb: string | null = parentWatcherDir(dirRel);
+  while (climb !== null) {
+    if (
+      climb === "" ||
+      directoryHasParentEdge(previous, climb) ||
+      previous.directories.has(climb)
+    ) {
+      return climb;
+    }
+    climb = parentWatcherDir(climb);
+  }
+  return "";
+}
+
+/**
+ * Resolve dirty directories from untrusted hints, then diff against `previous`.
+ * Invalid hints are skipped; all-invalid yields an empty ok diff.
+ * Scan/metadata failure never advances the snapshot.
+ */
+export async function reconcileWatcherHints(
+  rootAbs: string,
+  previous: WatcherSnapshot,
+  hints: readonly string[],
+  options: WatcherSnapshotOptions = {}
+): Promise<WatcherSnapshotDiffResult> {
+  const clock = options.clock ?? defaultClock;
+  const started = clock.nowMs();
+  const dirty = new Set<string>();
+
+  for (const hint of hints) {
+    const resolved = await resolveWatcherDirtyDirectory(rootAbs, hint, options);
+    if (resolved.status === "invalid") {
+      continue;
+    }
+    if (resolved.status === "fallback") {
+      return {
+        status: "fallback",
+        reason: "scan_failed",
+        discoveryMs: clock.nowMs() - started,
+        cause: resolved.cause,
+      };
+    }
+    dirty.add(dirtyDirectoryForResolvedHint(previous, resolved.directory));
+  }
+
+  if (dirty.size === 0) {
+    return {
+      status: "ok",
+      candidates: [],
+      removals: [],
+      nextSnapshot: previous,
+      discoveryMs: clock.nowMs() - started,
+    };
+  }
+
+  return diffWatcherSnapshot(rootAbs, previous, [...dirty], options);
+}