@gmickel/gno 1.34.5 → 1.35.0

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);
+}

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

@@ -0,0 +1,300 @@
+/**
+ * Identity-aware no-follow directory scanning and mutable snapshot maps.
+ *
+ * @module src/serve/watch-snapshot-scan
+ */
+
+import type {
+  ScanFailure,
+  SnapshotEntryFingerprint,
+  SnapshotMapHooks,
+  WatcherDirHandle,
+  WatcherSnapshot,
+  WatcherSnapshotClock,
+  WatcherSnapshotFs,
+  WatcherSnapshotStat,
+} from "./watch-snapshot-types";
+
+import { createDefaultWatcherFs } from "./watch-snapshot-handles";
+import {
+  fingerprintFromStat,
+  isMissingFsError,
+  isWatcherSourceKind,
+  joinWatcherRelPath,
+} from "./watch-snapshot-types";
+
+export { createPathBackedWatcherFs } from "./watch-snapshot-handles";
+
+export const defaultClock: WatcherSnapshotClock = {
+  nowMs: () => performance.now(),
+};
+
+export const defaultFs: WatcherSnapshotFs = createDefaultWatcherFs();
+
+/** Mutable hierarchical maps with incremental entry accounting. */
+export interface MutableSnapshotMaps {
+  directories: Map<string, Map<string, SnapshotEntryFingerprint>>;
+  entryCount: number;
+  unprovenSubtrees: Set<string>;
+}
+
+export function cloneDirectoryMaps(
+  source: WatcherSnapshot
+): MutableSnapshotMaps {
+  const directories = new Map<string, Map<string, SnapshotEntryFingerprint>>();
+  for (const [dir, entries] of source.directories) {
+    directories.set(dir, new Map(entries));
+  }
+  return {
+    directories,
+    entryCount: source.entryCount,
+    unprovenSubtrees: new Set(source.unprovenSubtrees ?? []),
+  };
+}
+
+export function freezeSnapshot(state: MutableSnapshotMaps): WatcherSnapshot {
+  const frozen = new Map<
+    string,
+    ReadonlyMap<string, SnapshotEntryFingerprint>
+  >();
+  for (const [dir, entries] of state.directories) {
+    frozen.set(dir, entries);
+  }
+  return {
+    directories: frozen,
+    entryCount: state.entryCount,
+    unprovenSubtrees: new Set(state.unprovenSubtrees),
+  };
+}
+
+/** Replace one directory's entry map; O(1) entryCount update. */
+export function setDirectoryEntries(
+  state: MutableSnapshotMaps,
+  dirRel: string,
+  entries: Map<string, SnapshotEntryFingerprint>
+): void {
+  const previous = state.directories.get(dirRel);
+  const previousSize = previous?.size ?? 0;
+  state.directories.set(dirRel, entries);
+  state.entryCount += entries.size - previousSize;
+}
+
+/**
+ * Hierarchical O(subtree-size) removal using stored child relationships.
+ * Single pass: collect non-directory paths and delete maps — no full-map
+ * prefix scan and no separate collect-then-remove phases.
+ */
+export function removeSubtreeFromMaps(
+  state: MutableSnapshotMaps,
+  dirRel: string,
+  hooks?: SnapshotMapHooks
+): string[] {
+  const removedCandidates: string[] = [];
+  const stack: string[] = [dirRel];
+
+  while (stack.length > 0) {
+    const dir = stack.pop() as string;
+    hooks?.onDirectoryMapVisit?.();
+    const entries = state.directories.get(dir);
+    if (!entries) {
+      continue;
+    }
+    for (const [name, fingerprint] of entries) {
+      const childRel = joinWatcherRelPath(dir, name);
+      if (fingerprint.kind === "directory") {
+        stack.push(childRel);
+      } else if (isWatcherSourceKind(fingerprint.kind)) {
+        // Only file/symlink sources are indexable; ignore FIFO/socket/device.
+        removedCandidates.push(childRel);
+      }
+    }
+    state.entryCount -= entries.size;
+    state.directories.delete(dir);
+  }
+
+  return removedCandidates;
+}
+
+/**
+ * Hierarchical collect of file/symlink source paths under a stored directory.
+ * O(subtree-size) via child relationships — not a full-map prefix scan.
+ * Special `other` entries are never collected (never indexed as sources).
+ */
+export function collectSnapshotFilesUnder(
+  directories: ReadonlyMap<
+    string,
+    ReadonlyMap<string, SnapshotEntryFingerprint>
+  >,
+  dirRel: string,
+  hooks?: SnapshotMapHooks
+): string[] {
+  const out: string[] = [];
+  const stack: string[] = [dirRel];
+  while (stack.length > 0) {
+    const dir = stack.pop() as string;
+    hooks?.onDirectoryMapVisit?.();
+    const entries = directories.get(dir);
+    if (!entries) {
+      continue;
+    }
+    for (const [name, fingerprint] of entries) {
+      const childRel = joinWatcherRelPath(dir, name);
+      if (fingerprint.kind === "directory") {
+        stack.push(childRel);
+      } else if (isWatcherSourceKind(fingerprint.kind)) {
+        out.push(childRel);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Open a collection-relative directory by walking components from the root
+ * handle. Never opens a full joined path that could traverse intermediate
+ * symlinks.
+ */
+export async function openDirByRel(
+  rootAbs: string,
+  dirRel: string,
+  fs: WatcherSnapshotFs
+): Promise<
+  | { status: "ok"; handle: WatcherDirHandle }
+  | { status: "missing" }
+  | ScanFailure
+> {
+  if (!fs.supportsAnchoredHandles) {
+    return {
+      status: "scan_failed",
+      cause: new Error(
+        "Anchored no-follow directory handles unavailable; refusing path-based scan"
+      ),
+    };
+  }
+
+  let handle: WatcherDirHandle;
+  try {
+    handle = await fs.openDir(rootAbs);
+  } catch (cause) {
+    if (isMissingFsError(cause)) {
+      return { status: "missing" };
+    }
+    return { status: "scan_failed", cause };
+  }
+
+  if (dirRel === "") {
+    return { status: "ok", handle };
+  }
+
+  const segments = dirRel.split("/");
+  for (const segment of segments) {
+    let child: WatcherDirHandle;
+    try {
+      // Reject non-directory / symlink components by requiring openChildDir.
+      child = await fs.openChildDir(handle, segment);
+    } catch (cause) {
+      await fs.closeDir(handle);
+      if (isMissingFsError(cause)) {
+        return { status: "missing" };
+      }
+      return { status: "scan_failed", cause };
+    }
+    await fs.closeDir(handle);
+    handle = child;
+  }
+  return { status: "ok", handle };
+}
+
+/**
+ * Enumerate direct children via an anchored directory handle.
+ * Child metadata is resolved relative to the handle — a path swap after open
+ * cannot redirect lstat outside the pinned directory.
+ *
+ * `maxEntries` is the remaining entry budget for this directory map. Enumeration
+ * and stats stop after observing `maxEntries + 1` children so overflow is proven
+ * without materializing an unbounded name/stat map.
+ */
+export async function readDirectChildren(
+  rootAbs: string,
+  dirRel: string,
+  fs: WatcherSnapshotFs,
+  maxEntries: number
+): Promise<
+  | { status: "present"; entries: Map<string, SnapshotEntryFingerprint> }
+  | { status: "missing" }
+  | ScanFailure
+> {
+  if (!fs.supportsAnchoredHandles) {
+    return {
+      status: "scan_failed",
+      cause: new Error(
+        "Anchored no-follow directory handles unavailable; refusing path-based scan"
+      ),
+    };
+  }
+  if (!Number.isInteger(maxEntries) || maxEntries < 0) {
+    return {
+      status: "scan_failed",
+      cause: new Error("maxEntries must be a non-negative integer"),
+    };
+  }
+
+  const opened = await openDirByRel(rootAbs, dirRel, fs);
+  if (opened.status !== "ok") {
+    return opened;
+  }
+  const { handle } = opened;
+
+  try {
+    let listed;
+    try {
+      // Cap names at remaining budget; maxEntries+1th name → overflow.
+      listed = await fs.readDir(handle, maxEntries);
+    } catch (cause) {
+      if (isMissingFsError(cause)) {
+        return { status: "missing" };
+      }
+      return { status: "scan_failed", cause };
+    }
+    if (listed.status === "overflow") {
+      return { status: "overflow" };
+    }
+
+    const names = listed.names;
+    const entries = new Map<string, SnapshotEntryFingerprint>();
+    // Stable order keeps overflow selection deterministic across platforms.
+    names.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+    for (const name of names) {
+      if (name === "" || name === "." || name === "..") {
+        continue;
+      }
+      if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+        return {
+          status: "scan_failed",
+          cause: new Error(`Invalid directory entry name: ${name}`),
+        };
+      }
+      // Defense in depth: never stat/map more than the remaining budget.
+      if (entries.size >= maxEntries) {
+        return { status: "overflow" };
+      }
+      let stat: WatcherSnapshotStat;
+      try {
+        stat = await fs.lstatChild(handle, name);
+      } catch (cause) {
+        // Observed-then-missing (ENOENT/ENOTDIR after readdir listed the name)
+        // must fail closed: silently skipping would accept a partial directory
+        // image and can prove false removals against the previous snapshot.
+        return { status: "scan_failed", cause };
+      }
+      const fingerprinted = fingerprintFromStat(stat);
+      if (!fingerprinted.ok) {
+        return { status: "unreliable_metadata" };
+      }
+      entries.set(name, fingerprinted.fingerprint);
+    }
+    return { status: "present", entries };
+  } finally {
+    await fs.closeDir(handle);
+  }
+}