@gmickel/gno 1.34.4 → 1.34.6

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

@@ -0,0 +1,297 @@
+/**
+ * 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;
+}
+
+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,
+  };
+}
+
+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,
+  };
+}
+
+/** 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);
+  }
+}

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

@@ -0,0 +1,350 @@
+/**
+ * Watcher snapshot types, fingerprints, and pure path helpers.
+ *
+ * @module src/serve/watch-snapshot-types
+ */
+
+// node:path — Bun has no path utilities
+import { isAbsolute } from "node:path";
+
+/** Fixed service-wide maximum entries retained in one collection snapshot. */
+export const WATCHER_SNAPSHOT_ENTRY_CEILING = 100_000;
+
+/**
+ * Result of a bounded directory enumeration.
+ * Overflow means more than `maxNames` child names were observed; callers must
+ * not treat a partial name list as a successful directory image.
+ */
+export type WatcherReadDirResult =
+  | { status: "ok"; names: string[] }
+  | { status: "overflow" };
+
+export type SnapshotEntryKind = "file" | "directory" | "symlink" | "other";
+
+/**
+ * No-follow entry fingerprint used only for candidate discovery.
+ * Equality of fingerprints means "not a discovery candidate", never
+ * "content is unchanged".
+ */
+export interface SnapshotEntryFingerprint {
+  kind: SnapshotEntryKind;
+  device: bigint;
+  inode: bigint;
+  size: number;
+  mtimeNs: bigint;
+  ctimeNs: bigint;
+}
+
+/** Hierarchical snapshot indexed by directory (POSIX collection-relative). */
+export interface WatcherSnapshot {
+  /** dirRelPath → (entry name → fingerprint). `""` is the collection root. */
+  readonly directories: ReadonlyMap<
+    string,
+    ReadonlyMap<string, SnapshotEntryFingerprint>
+  >;
+  /** Total no-follow entries across every directory map. */
+  readonly entryCount: number;
+}
+
+/** Injectable lstat view. `unreliable` forces the correctness-preserving fallback. */
+export interface WatcherSnapshotStat {
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+  dev: number | bigint;
+  ino: number | bigint;
+  size: number | bigint;
+  mtimeNs?: bigint | number;
+  ctimeNs?: bigint | number;
+  mtimeMs?: number;
+  ctimeMs?: number;
+  /** When true, metadata cannot be trusted for discovery. */
+  unreliable?: boolean;
+}
+
+/**
+ * Opaque directory handle for anchored (openat-style) enumeration.
+ * Production pins a real directory inode; tests may use path-backed handles.
+ */
+export type WatcherDirHandle = {
+  readonly __watcherDirHandle: unique symbol;
+};
+
+/**
+ * Injectable filesystem surface for watcher snapshots.
+ *
+ * Production must set `supportsAnchoredHandles` and implement handle ops so
+ * child metadata is resolved relative to a stable directory fd (no path
+ * re-walk after the parent is opened). When handles are unavailable, scans
+ * return `scan_failed` / `unreliable_metadata` rather than claiming
+ * strict no-follow safety.
+ */
+export interface WatcherSnapshotFs {
+  /**
+   * True only when openDir/readDir/lstatChild/openChildDir/closeDir form a
+   * safe anchored scan path for this runtime/platform.
+   */
+  readonly supportsAnchoredHandles: boolean;
+
+  /** Open an absolute path as a real directory without following a final symlink. */
+  openDir(absPath: string): Promise<WatcherDirHandle>;
+
+  /**
+   * Enumerate direct child names via the open directory handle, capped at
+   * `maxNames`. Implementations must stop after observing `maxNames + 1`
+   * names (overflow) without storing or returning more, and must not claim
+   * success with a truncated list.
+   */
+  readDir(
+    handle: WatcherDirHandle,
+    maxNames: number
+  ): Promise<WatcherReadDirResult>;
+
+  /**
+   * No-follow lstat of a direct child relative to an open directory handle.
+   * Must not re-resolve intermediate path components outside the handle.
+   */
+  lstatChild(
+    handle: WatcherDirHandle,
+    name: string
+  ): Promise<WatcherSnapshotStat>;
+
+  /**
+   * Open a direct child as a real directory relative to the parent handle
+   * (no-follow). Rejects symlink children.
+   */
+  openChildDir(
+    handle: WatcherDirHandle,
+    name: string
+  ): Promise<WatcherDirHandle>;
+
+  /** Deterministic close; safe to call once per open. */
+  closeDir(handle: WatcherDirHandle): Promise<void>;
+}
+
+export interface WatcherSnapshotClock {
+  nowMs(): number;
+}
+
+/** Test/prod hooks for map-visit complexity instrumentation. */
+export interface SnapshotMapHooks {
+  /** Invoked once per directory-map visit during hierarchical subtree walks. */
+  onDirectoryMapVisit?: () => void;
+}
+
+export type SnapshotFallbackReason =
+  | "overflow"
+  | "scan_failed"
+  | "unreliable_metadata";
+
+export type WatcherSnapshotBuildResult =
+  | {
+      status: "ok";
+      snapshot: WatcherSnapshot;
+      durationMs: number;
+    }
+  | {
+      status: "fallback";
+      reason: SnapshotFallbackReason;
+      durationMs: number;
+      cause?: unknown;
+    };
+
+/** True when a snapshot entry kind can be an indexed document source. */
+export function isWatcherSourceKind(
+  kind: SnapshotEntryKind
+): kind is "file" | "symlink" {
+  return kind === "file" || kind === "symlink";
+}
+
+export type WatcherSnapshotDiffResult =
+  | {
+      status: "ok";
+      /**
+       * Present/changed file and symlink paths that still exist and need
+       * content-hash consideration (added, edited, or new under a directory).
+       * Never includes `other` (FIFO/socket/device) or directories.
+       * Does not include proven removals.
+       */
+      candidates: string[];
+      /**
+       * Proven removable source paths: deleted files/symlinks, prior files
+       * replaced by a directory or other special entry, and expanded nested
+       * files under removed or directory→non-directory transitions.
+       * Never includes `other` entries (they were never indexed as sources).
+       */
+      removals: string[];
+      nextSnapshot: WatcherSnapshot;
+      discoveryMs: number;
+    }
+  | {
+      status: "fallback";
+      reason: SnapshotFallbackReason;
+      discoveryMs: number;
+      cause?: unknown;
+    };
+
+export interface WatcherSnapshotOptions {
+  fs?: WatcherSnapshotFs;
+  clock?: WatcherSnapshotClock;
+  /** Override the service-wide ceiling (tests only). */
+  entryCeiling?: number;
+  /** Map-visit instrumentation (tests / complexity regression). */
+  mapHooks?: SnapshotMapHooks;
+}
+
+export type ScanFailure =
+  | { status: "overflow" }
+  | { status: "scan_failed"; cause: unknown }
+  | { status: "unreliable_metadata" };
+
+export type DiffWorkResult = { status: "ok" } | ScanFailure;
+
+export function toBigInt(value: number | bigint | undefined): bigint | null {
+  if (value === undefined) {
+    return null;
+  }
+  if (typeof value === "bigint") {
+    return value;
+  }
+  if (!Number.isFinite(value)) {
+    return null;
+  }
+  return BigInt(Math.trunc(value));
+}
+
+/**
+ * Require actual finite nanosecond timestamps. Millisecond fields alone are
+ * insufficient for the fast path (no ms→ns fabrication).
+ */
+export function nsFromStat(ns: bigint | number | undefined): bigint | null {
+  return toBigInt(ns);
+}
+
+export function kindOf(stat: WatcherSnapshotStat): SnapshotEntryKind {
+  if (stat.isSymbolicLink()) {
+    return "symlink";
+  }
+  if (stat.isDirectory()) {
+    return "directory";
+  }
+  if (stat.isFile()) {
+    return "file";
+  }
+  return "other";
+}
+
+export function fingerprintFromStat(
+  stat: WatcherSnapshotStat
+):
+  | { ok: true; fingerprint: SnapshotEntryFingerprint }
+  | { ok: false; reason: "unreliable_metadata" } {
+  if (stat.unreliable) {
+    return { ok: false, reason: "unreliable_metadata" };
+  }
+  const device = toBigInt(stat.dev);
+  const inode = toBigInt(stat.ino);
+  const sizeValue = toBigInt(stat.size);
+  const mtimeNs = nsFromStat(stat.mtimeNs);
+  const ctimeNs = nsFromStat(stat.ctimeNs);
+  if (
+    device === null ||
+    inode === null ||
+    sizeValue === null ||
+    mtimeNs === null ||
+    ctimeNs === null
+  ) {
+    return { ok: false, reason: "unreliable_metadata" };
+  }
+  // size may exceed Number.MAX_SAFE_INTEGER on huge files; clamp via Number is
+  // fine for discovery equality against the same platform read.
+  const size =
+    sizeValue > BigInt(Number.MAX_SAFE_INTEGER)
+      ? Number.MAX_SAFE_INTEGER
+      : Number(sizeValue);
+  return {
+    ok: true,
+    fingerprint: {
+      kind: kindOf(stat),
+      device,
+      inode,
+      size,
+      mtimeNs,
+      ctimeNs,
+    },
+  };
+}
+
+export function fingerprintsEqual(
+  left: SnapshotEntryFingerprint,
+  right: SnapshotEntryFingerprint
+): boolean {
+  return (
+    left.kind === right.kind &&
+    left.device === right.device &&
+    left.inode === right.inode &&
+    left.size === right.size &&
+    left.mtimeNs === right.mtimeNs &&
+    left.ctimeNs === right.ctimeNs
+  );
+}
+
+/**
+ * Normalize an untrusted watcher hint to a POSIX collection-relative path.
+ * Returns null for absolute, escaping, empty-invalid, or NUL-bearing values.
+ */
+export function normalizeWatcherRelPath(relPath: string): string | null {
+  if (relPath.includes("\0")) {
+    return null;
+  }
+  const normalized = relPath.replaceAll("\\", "/");
+  if (normalized.startsWith("/") || isAbsolute(relPath)) {
+    return null;
+  }
+  // Windows drive-shaped absolute escapes (`C:/...`) after slash normalization.
+  if (/^[A-Za-z]:(\/|$)/.test(normalized)) {
+    return null;
+  }
+  const segments: string[] = [];
+  for (const segment of normalized.split("/")) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      return null;
+    }
+    segments.push(segment);
+  }
+  return segments.join("/");
+}
+
+/** Parent directory of a POSIX relative path; `null` when path is the root. */
+export function parentWatcherDir(relPath: string): string | null {
+  if (relPath === "") {
+    return null;
+  }
+  const index = relPath.lastIndexOf("/");
+  return index === -1 ? "" : relPath.slice(0, index);
+}
+
+export function joinWatcherRelPath(dir: string, name: string): string {
+  return dir === "" ? name : `${dir}/${name}`;
+}
+
+export function createEmptyWatcherSnapshot(): WatcherSnapshot {
+  return { directories: new Map(), entryCount: 0 };
+}
+
+export function isMissingFsError(error: unknown): boolean {
+  const code =
+    error && typeof error === "object" && "code" in error
+      ? String(error.code)
+      : "";
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+export function sortPathList(paths: Iterable<string>): string[] {
+  return [...paths].sort((left, right) =>
+    left < right ? -1 : left > right ? 1 : 0
+  );
+}

package/src/serve/watch-snapshot.ts

@@ -0,0 +1,51 @@
+/**
+ * Watcher-owned hierarchical no-follow filesystem snapshot.
+ *
+ * Fingerprints identify ambiguous candidates only. They never prove that
+ * indexed content is unchanged; exact eligible paths still content-hash.
+ *
+ * Public contract only — implementation is split across focused modules.
+ * This facade re-exports the concrete public surface (not an unrelated barrel).
+ *
+ * @module src/serve/watch-snapshot
+ */
+
+export {
+  WATCHER_SNAPSHOT_ENTRY_CEILING,
+  createEmptyWatcherSnapshot,
+  fingerprintsEqual,
+  joinWatcherRelPath,
+  normalizeWatcherRelPath,
+  parentWatcherDir,
+} from "./watch-snapshot-types";
+
+export type {
+  SnapshotEntryFingerprint,
+  SnapshotEntryKind,
+  SnapshotFallbackReason,
+  SnapshotMapHooks,
+  WatcherDirHandle,
+  WatcherReadDirResult,
+  WatcherSnapshot,
+  WatcherSnapshotBuildResult,
+  WatcherSnapshotClock,
+  WatcherSnapshotDiffResult,
+  WatcherSnapshotFs,
+  WatcherSnapshotOptions,
+  WatcherSnapshotStat,
+} from "./watch-snapshot-types";
+
+export {
+  buildWatcherSnapshot,
+  diffWatcherSnapshot,
+} from "./watch-snapshot-ops";
+
+export {
+  reconcileWatcherHints,
+  resolveWatcherDirtyDirectory,
+} from "./watch-snapshot-resolve";
+
+export {
+  createPathBackedWatcherFs,
+  removeSubtreeFromMaps,
+} from "./watch-snapshot-scan";

package/src/store/index.ts

@@ -98,4 +98,4 @@ export type {
   StorePort,
   StoreResult,
 } from "./types";
-export { err, ok } from "./types";
+export { err, ok, WATCHER_ACTIVE_SOURCE_PATH_MAX } from "./types";