@gmickel/gno 1.34.6 → 1.35.0

package/src/serve/watch-service.ts

@@ -347,6 +347,7 @@ export class CollectionWatchService {
             scheduleFlush(buildQueueHost(this.#hostState()), name);
           }
         },
+        getSyncOptions: () => this.#syncOptions,
         buildSnapshot: this.#buildSnapshot,
       },
       collection

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

@@ -0,0 +1,51 @@
+/**
+ * Source-availability boundaries shared by watcher snapshot operations.
+ *
+ * @module src/serve/watch-snapshot-availability
+ */
+
+// node:path — Bun has no path join helper.
+import { join } from "node:path";
+
+import type { WatcherSnapshotFs } from "./watch-snapshot-types";
+
+import {
+  isUnprovenDirectoryResult,
+  type DirectoryAvailabilityPort,
+} from "../ingestion/source-availability";
+import { readDirectChildren } from "./watch-snapshot-scan";
+
+export async function directoryAllowsDescent(
+  rootAbs: string,
+  dirRel: string,
+  classifier: DirectoryAvailabilityPort | undefined
+): Promise<boolean> {
+  if (!classifier || classifier.mode === "any") {
+    return true;
+  }
+  const absPath = dirRel === "" ? rootAbs : join(rootAbs, dirRel);
+  const classified = await classifier.classify(absPath);
+  return !isUnprovenDirectoryResult(classified);
+}
+
+export async function readAvailableDirectory(
+  rootAbs: string,
+  dirRel: string,
+  fs: WatcherSnapshotFs,
+  maxEntries: number,
+  classifier: DirectoryAvailabilityPort | undefined
+): Promise<
+  Awaited<ReturnType<typeof readDirectChildren>> | { status: "unproven" }
+> {
+  if (!classifier || classifier.mode === "any") {
+    return readDirectChildren(rootAbs, dirRel, fs, maxEntries);
+  }
+  if (!fs.readDirectChildrenSync) {
+    return { status: "unproven" };
+  }
+  const absPath = dirRel === "" ? rootAbs : join(rootAbs, dirRel);
+  const read = classifier.readDirectory(absPath, () =>
+    fs.readDirectChildrenSync!(rootAbs, dirRel, maxEntries)
+  );
+  return read.kind === "available" ? read.value : { status: "unproven" };
+}

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

@@ -1,8 +1,8 @@
 /**
  * Production anchored directory handles (openat / fdopendir).
  *
- * Uses Bun FFI for fd-relative open/enumerate and node:fs structure ops for
- * open(O_DIRECTORY|O_NOFOLLOW) + fstat bigint metadata. No new dependencies.
+ * Uses Bun FFI for fd-relative open/enumerate/no-follow metadata and node:fs
+ * structure ops for directory open + fstat confirmation. No new dependencies.
  *
  * Windows and runtimes without a safe anchored path report
  * `supportsAnchoredHandles: false` so callers fall back rather than claiming
@@ -18,13 +18,19 @@ import { join } from "node:path";
 
 import type { LoadedLibc } from "./watch-snapshot-libc";
 import type {
+  SnapshotEntryFingerprint,
   WatcherDirHandle,
   WatcherSnapshotFs,
   WatcherSnapshotStat,
 } from "./watch-snapshot-types";
 
-import { loadLibc, openatOrThrow, readDirNames } from "./watch-snapshot-libc";
-import { isMissingFsError } from "./watch-snapshot-types";
+import {
+  loadLibc,
+  openatOrThrow,
+  readDirNames,
+  statatNoFollowOrThrow,
+} from "./watch-snapshot-libc";
+import { fingerprintFromStat, isMissingFsError } from "./watch-snapshot-types";
 
 type NativeDir = {
   fd: number;
@@ -48,32 +54,118 @@ function requireNative(handle: WatcherDirHandle): NativeDir {
   return native;
 }
 
-function mapStats(stat: {
-  isFile(): boolean;
-  isDirectory(): boolean;
-  isSymbolicLink(): boolean;
-  dev: bigint | number;
-  ino: bigint | number;
-  size: bigint | number;
-  mtimeNs?: bigint | number;
-  ctimeNs?: bigint | number;
-}): WatcherSnapshotStat {
-  return {
-    isFile: () => stat.isFile(),
-    isDirectory: () => stat.isDirectory(),
-    isSymbolicLink: () => stat.isSymbolicLink(),
-    dev: stat.dev,
-    ino: stat.ino,
-    size: stat.size,
-    mtimeNs: stat.mtimeNs,
-    ctimeNs: stat.ctimeNs,
-  };
+function openNativeDirByRel(
+  libc: LoadedLibc,
+  rootAbs: string,
+  dirRel: string
+): number {
+  let fd = openSync(rootAbs, libc.openDirFlags);
+  try {
+    for (const segment of dirRel.split("/").filter(Boolean)) {
+      const child = openatOrThrow(
+        libc,
+        fd,
+        segment,
+        libc.openChildFlags,
+        "openat"
+      );
+      closeSync(fd);
+      fd = child;
+    }
+    return fd;
+  } catch (cause) {
+    closeSync(fd);
+    throw cause;
+  }
+}
+
+function readDirectChildrenNative(
+  libc: LoadedLibc,
+  rootAbs: string,
+  dirRel: string,
+  maxEntries: number
+): ReturnType<NonNullable<WatcherSnapshotFs["readDirectChildrenSync"]>> {
+  if (!Number.isInteger(maxEntries) || maxEntries < 0) {
+    return {
+      status: "scan_failed",
+      cause: new Error("maxEntries must be a non-negative integer"),
+    };
+  }
+
+  let fd: number;
+  try {
+    fd = openNativeDirByRel(libc, rootAbs, dirRel);
+  } catch (cause) {
+    return isMissingFsError(cause)
+      ? { status: "missing" }
+      : { status: "scan_failed", cause };
+  }
+
+  try {
+    const listed = readDirNames(libc, fd, maxEntries);
+    if (listed.status === "overflow") {
+      return listed;
+    }
+    const entries = new Map<string, SnapshotEntryFingerprint>();
+    listed.names.sort((left, right) =>
+      left < right ? -1 : left > right ? 1 : 0
+    );
+    for (const name of listed.names) {
+      if (name.includes("/") || name.includes("\\") || name.includes("\0")) {
+        return {
+          status: "scan_failed",
+          cause: new Error(`Invalid directory entry name: ${name}`),
+        };
+      }
+      if (entries.size >= maxEntries) {
+        return { status: "overflow" };
+      }
+      try {
+        const fingerprinted = fingerprintFromStat(
+          statatNoFollowOrThrow(libc, fd, name)
+        );
+        if (!fingerprinted.ok) {
+          return { status: "unreliable_metadata" };
+        }
+        entries.set(name, fingerprinted.fingerprint);
+      } catch (cause) {
+        return { status: "scan_failed", cause };
+      }
+    }
+    return { status: "present", entries };
+  } catch (cause) {
+    return isMissingFsError(cause)
+      ? { status: "missing" }
+      : { status: "scan_failed", cause };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function lstatChildByRelNative(
+  libc: LoadedLibc,
+  rootAbs: string,
+  parentRel: string,
+  name: string
+): WatcherSnapshotStat {
+  const parentFd = openNativeDirByRel(libc, rootAbs, parentRel);
+  try {
+    return statatNoFollowOrThrow(libc, parentFd, name);
+  } finally {
+    closeSync(parentFd);
+  }
 }
 
 function createNativeAnchoredFs(libc: LoadedLibc): WatcherSnapshotFs {
   return {
     supportsAnchoredHandles: true,
 
+    readDirectChildrenSync: (rootAbs, dirRel, maxEntries) =>
+      readDirectChildrenNative(libc, rootAbs, dirRel, maxEntries),
+
+    lstatChildByRelSync: (rootAbs, parentRel, name) =>
+      lstatChildByRelNative(libc, rootAbs, parentRel, name),
+
     async openDir(absPath: string): Promise<WatcherDirHandle> {
       const fd = openSync(absPath, libc.openDirFlags);
       return asHandle({ fd });
@@ -89,19 +181,7 @@ function createNativeAnchoredFs(libc: LoadedLibc): WatcherSnapshotFs {
       name: string
     ): Promise<WatcherSnapshotStat> {
       const native = requireNative(handle);
-      const fd = openatOrThrow(
-        libc,
-        native.fd,
-        name,
-        libc.openLstatFlags,
-        "openat"
-      );
-      try {
-        const stat = fstatSync(fd, { bigint: true });
-        return mapStats(stat);
-      } finally {
-        closeSync(fd);
-      }
+      return statatNoFollowOrThrow(libc, native.fd, name);
     },
 
     async openChildDir(

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

@@ -14,6 +14,12 @@ import { constants as fsConstants } from "node:fs";
 
 export type LibcSymbols = {
   openat: (dirfd: number, path: Pointer, flags: number) => number;
+  fstatat: (
+    dirfd: number,
+    path: Pointer,
+    statBuffer: Pointer,
+    flags: number
+  ) => number;
   dup: (fd: number) => number;
   close: (fd: number) => number;
   fdopendir: (fd: number) => Pointer | null;
@@ -42,7 +48,33 @@ export type LoadedLibc = {
   dirent: DirentLayout;
   openChildFlags: number;
   openDirFlags: number;
-  openLstatFlags: number;
+  atSymlinkNoFollow: number;
+  statLayout: NativeStatLayout;
+};
+
+type NativeStatLayout = {
+  size: number;
+  devOffset: number;
+  devBytes: 4 | 8;
+  modeOffset: number;
+  modeBytes: 2 | 4;
+  inoOffset: number;
+  sizeOffset: number;
+  mtimeSecOffset: number;
+  mtimeNsecOffset: number;
+  ctimeSecOffset: number;
+  ctimeNsecOffset: number;
+};
+
+export type FdRelativeStat = {
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+  dev: bigint | number;
+  ino: bigint;
+  size: bigint;
+  mtimeNs: bigint;
+  ctimeNs: bigint;
 };
 
 let cachedLibc: LoadedLibc | null | undefined;
@@ -82,6 +114,10 @@ function openLibcSymbols(
         args: [FFIType.i32, FFIType.cstring, FFIType.i32],
         returns: FFIType.i32,
       },
+      fstatat: {
+        args: [FFIType.i32, FFIType.cstring, FFIType.ptr, FFIType.i32],
+        returns: FFIType.i32,
+      },
       dup: { args: [FFIType.i32], returns: FFIType.i32 },
       close: { args: [FFIType.i32], returns: FFIType.i32 },
       fdopendir: { args: [FFIType.i32], returns: FFIType.ptr },
@@ -121,6 +157,7 @@ export function loadLibc(): LoadedLibc | null {
 
   const raw = library.symbols as Record<string, unknown>;
   const openat = asLibcFn<LibcSymbols["openat"]>(raw.openat);
+  const fstatat = asLibcFn<LibcSymbols["fstatat"]>(raw.fstatat);
   const dup = asLibcFn<LibcSymbols["dup"]>(raw.dup);
   const close = asLibcFn<LibcSymbols["close"]>(raw.close);
   const fdopendir = asLibcFn<LibcSymbols["fdopendir"]>(raw.fdopendir);
@@ -129,6 +166,7 @@ export function loadLibc(): LoadedLibc | null {
   const errnoFn = asLibcFn<LibcSymbols["errnoPtr"]>(raw[errnoName]);
   if (
     !openat ||
+    !fstatat ||
     !dup ||
     !close ||
     !fdopendir ||
@@ -144,32 +182,15 @@ export function loadLibc(): LoadedLibc | null {
   const O_DIRECTORY = fsConstants.O_DIRECTORY;
   const O_NOFOLLOW = fsConstants.O_NOFOLLOW;
 
-  let openLstatFlags: number;
-  if (platform === "darwin") {
-    // Darwin O_SYMLINK opens the symlink inode itself (lstat-like).
-    // Without it, O_RDONLY would follow — refuse rather than silent follow.
-    // O_NONBLOCK is required: plain O_RDONLY|O_SYMLINK can block forever on a
-    // FIFO with no writer (and similarly hang on some device nodes).
-    const O_SYMLINK = (fsConstants as { O_SYMLINK?: number }).O_SYMLINK;
-    if (O_SYMLINK === undefined || O_SYMLINK === 0) {
-      cachedLibc = null;
-      return null;
-    }
-    const O_NONBLOCK = fsConstants.O_NONBLOCK ?? 0;
-    openLstatFlags = O_RDONLY | O_SYMLINK | O_NONBLOCK;
-  } else {
-    // Linux O_PATH|O_NOFOLLOW is the portable no-follow open for any type.
-    // O_PATH does not block on FIFOs/sockets; no extra O_NONBLOCK needed.
-    const O_PATH = (fsConstants as { O_PATH?: number }).O_PATH ?? 0o10_000_000;
-    openLstatFlags = O_RDONLY | O_PATH | O_NOFOLLOW;
-  }
-
   const openDirFlags = O_RDONLY | O_DIRECTORY | O_NOFOLLOW;
+  const atSymlinkNoFollow = platform === "darwin" ? 0x20 : 0x100;
+  const statLayout = nativeStatLayout(platform, process.arch);
 
   cachedLibc = {
     library,
     symbols: {
       openat,
+      fstatat,
       dup,
       close,
       fdopendir,
@@ -180,11 +201,43 @@ export function loadLibc(): LoadedLibc | null {
     dirent: direntLayoutFor(platform),
     openChildFlags: openDirFlags,
     openDirFlags,
-    openLstatFlags,
+    atSymlinkNoFollow,
+    statLayout,
   };
   return cachedLibc;
 }
 
+function nativeStatLayout(platform: string, arch: string): NativeStatLayout {
+  if (platform === "darwin") {
+    return {
+      size: 144,
+      devOffset: 0,
+      devBytes: 4,
+      modeOffset: 4,
+      modeBytes: 2,
+      inoOffset: 8,
+      sizeOffset: 96,
+      mtimeSecOffset: 48,
+      mtimeNsecOffset: 56,
+      ctimeSecOffset: 64,
+      ctimeNsecOffset: 72,
+    };
+  }
+  return {
+    size: 144,
+    devOffset: 0,
+    devBytes: 8,
+    modeOffset: arch === "x64" ? 24 : 16,
+    modeBytes: 4,
+    inoOffset: 8,
+    sizeOffset: 48,
+    mtimeSecOffset: 88,
+    mtimeNsecOffset: 96,
+    ctimeSecOffset: 104,
+    ctimeNsecOffset: 112,
+  };
+}
+
 function asLibcFn<T extends (...args: never[]) => unknown>(
   value: unknown
 ): T | null {
@@ -389,3 +442,69 @@ export function openatOrThrow(
   }
   return fd;
 }
+
+/**
+ * Read no-follow metadata for one direct child without opening its content.
+ * This avoids materializing dataless File Provider files while retaining the
+ * parent-fd anchoring and symlink identity required by watcher snapshots.
+ */
+export function statatNoFollowOrThrow(
+  libc: LoadedLibc,
+  dirfd: number,
+  name: string
+): FdRelativeStat {
+  if (name.includes("\0") || name.includes("/") || name.includes("\\")) {
+    throw Object.assign(new Error(`Invalid directory entry name: ${name}`), {
+      code: "EINVAL",
+    });
+  }
+  const nameBuffer = Buffer.from(`${name}\0`);
+  const statBuffer = Buffer.alloc(libc.statLayout.size);
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    const result = libc.symbols.fstatat(
+      dirfd,
+      ptr(nameBuffer),
+      ptr(statBuffer),
+      libc.atSymlinkNoFollow
+    );
+    if (result >= 0) {
+      break;
+    }
+    const errno = readErrno(libc);
+    // Darwin/Bun can transiently surface ENOENT during large fd-relative stat
+    // batches. Retry the same anchored lookup once. A child that truly
+    // disappeared still fails on the second probe, so callers retain the
+    // scan-failed authority boundary instead of accepting a partial image.
+    if (errno !== 2 || attempt > 0) {
+      throw errnoError(errno, "fstatat", name);
+    }
+  }
+
+  const layout = libc.statLayout;
+  const mode =
+    layout.modeBytes === 2
+      ? statBuffer.readUInt16LE(layout.modeOffset)
+      : statBuffer.readUInt32LE(layout.modeOffset);
+  const fileType = mode & 0o170_000;
+  const dev =
+    layout.devBytes === 4
+      ? statBuffer.readUInt32LE(layout.devOffset)
+      : statBuffer.readBigUInt64LE(layout.devOffset);
+  const mtimeNs =
+    statBuffer.readBigInt64LE(layout.mtimeSecOffset) * 1_000_000_000n +
+    statBuffer.readBigInt64LE(layout.mtimeNsecOffset);
+  const ctimeNs =
+    statBuffer.readBigInt64LE(layout.ctimeSecOffset) * 1_000_000_000n +
+    statBuffer.readBigInt64LE(layout.ctimeNsecOffset);
+
+  return {
+    isFile: () => fileType === 0o100_000,
+    isDirectory: () => fileType === 0o040_000,
+    isSymbolicLink: () => fileType === 0o120_000,
+    dev,
+    ino: statBuffer.readBigUInt64LE(layout.inoOffset),
+    size: statBuffer.readBigInt64LE(layout.sizeOffset),
+    mtimeNs,
+    ctimeNs,
+  };
+}