@gmickel/gno 1.34.5 → 1.35.0

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

@@ -0,0 +1,510 @@
+/**
+ * Libc FFI boundary for anchored watcher directory handles.
+ *
+ * Loads system libc with platform-correct sonames, parses dirent records
+ * using d_reclen/d_namlen bounds, and clears errno around readdir.
+ *
+ * @module src/serve/watch-snapshot-libc
+ */
+
+// bun:ffi — no Bun high-level openat/fdopendir; libc is required for fd-relative ops
+import { type Pointer, dlopen, FFIType, ptr, toArrayBuffer } from "bun:ffi";
+// node:fs — flag constants for openat; no Bun equivalent
+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;
+  readdir: (dirp: Pointer) => Pointer | null;
+  closedir: (dirp: Pointer) => number;
+  errnoPtr: () => Pointer;
+};
+
+/** Platform dirent field layout (little-endian). */
+export type DirentLayout = {
+  /** Offset of d_reclen (uint16). Both Darwin and Linux: 16. */
+  dReclenOffset: number;
+  /**
+   * Offset of d_namlen (uint16) when present.
+   * Darwin: 18. Linux glibc has no d_namlen (null).
+   */
+  dNamlenOffset: number | null;
+  /** Offset of d_name char array. Darwin: 21. Linux glibc: 19. */
+  dNameOffset: number;
+};
+
+export type LoadedLibc = {
+  /** Strong reference so FFI symbols stay live for the process lifetime. */
+  library: ReturnType<typeof dlopen>;
+  symbols: LibcSymbols;
+  dirent: DirentLayout;
+  openChildFlags: number;
+  openDirFlags: 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;
+
+/**
+ * Deterministic libc soname candidates.
+ * Never rely solely on `libc.<suffix>` (Linux libc.so is often a linker script).
+ */
+export function libcLoadCandidates(
+  platform: string = process.platform
+): string[] {
+  if (platform === "darwin") {
+    return ["libSystem.B.dylib", "libc.dylib"];
+  }
+  if (platform === "linux") {
+    return ["libc.so.6", "libc.so"];
+  }
+  return [];
+}
+
+function direntLayoutFor(platform: string): DirentLayout {
+  if (platform === "darwin") {
+    // struct dirent: d_ino(8) d_seekoff(8) d_reclen(2) d_namlen(2) d_type(1) d_name[]
+    return { dReclenOffset: 16, dNamlenOffset: 18, dNameOffset: 21 };
+  }
+  // glibc struct dirent: d_ino(8) d_off(8) d_reclen(2) d_type(1) d_name[]
+  return { dReclenOffset: 16, dNamlenOffset: null, dNameOffset: 19 };
+}
+
+function openLibcSymbols(
+  path: string,
+  errnoName: string
+): ReturnType<typeof dlopen> | null {
+  try {
+    return dlopen(path, {
+      openat: {
+        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 },
+      readdir: { args: [FFIType.ptr], returns: FFIType.ptr },
+      closedir: { args: [FFIType.ptr], returns: FFIType.i32 },
+      [errnoName]: { args: [], returns: FFIType.ptr },
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function loadLibc(): LoadedLibc | null {
+  if (cachedLibc !== undefined) {
+    return cachedLibc;
+  }
+  if (process.platform === "win32") {
+    cachedLibc = null;
+    return null;
+  }
+
+  const platform = process.platform;
+  const errnoName = platform === "darwin" ? "__error" : "__errno_location";
+  const candidates = libcLoadCandidates(platform);
+
+  let library: ReturnType<typeof dlopen> | null = null;
+  for (const candidate of candidates) {
+    library = openLibcSymbols(candidate, errnoName);
+    if (library) {
+      break;
+    }
+  }
+  if (!library) {
+    cachedLibc = null;
+    return 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);
+  const readdir = asLibcFn<LibcSymbols["readdir"]>(raw.readdir);
+  const closedir = asLibcFn<LibcSymbols["closedir"]>(raw.closedir);
+  const errnoFn = asLibcFn<LibcSymbols["errnoPtr"]>(raw[errnoName]);
+  if (
+    !openat ||
+    !fstatat ||
+    !dup ||
+    !close ||
+    !fdopendir ||
+    !readdir ||
+    !closedir ||
+    !errnoFn
+  ) {
+    cachedLibc = null;
+    return null;
+  }
+
+  const O_RDONLY = fsConstants.O_RDONLY;
+  const O_DIRECTORY = fsConstants.O_DIRECTORY;
+  const O_NOFOLLOW = fsConstants.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,
+      readdir,
+      closedir,
+      errnoPtr: errnoFn,
+    },
+    dirent: direntLayoutFor(platform),
+    openChildFlags: openDirFlags,
+    openDirFlags,
+    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 {
+  if (typeof value !== "function") {
+    return null;
+  }
+  return value as T;
+}
+
+export function errnoError(
+  errno: number,
+  syscall: string,
+  path: string
+): NodeJS.ErrnoException {
+  const error = new Error(
+    `${syscall} failed (errno ${errno}): ${path}`
+  ) as NodeJS.ErrnoException;
+  error.errno = errno;
+  error.syscall = syscall;
+  error.path = path;
+  // Map common POSIX errno values used on darwin/linux.
+  if (errno === 2) {
+    error.code = "ENOENT";
+  } else if (errno === 13) {
+    error.code = "EACCES";
+  } else if (errno === 20) {
+    error.code = "ENOTDIR";
+  } else if (errno === 40 || errno === 62) {
+    // Linux ELOOP=40, Darwin ELOOP=62
+    error.code = "ELOOP";
+  } else if (errno === 17) {
+    error.code = "EEXIST";
+  } else {
+    error.code = "EIO";
+  }
+  return error;
+}
+
+export function readErrno(libc: LoadedLibc): number {
+  const p = libc.symbols.errnoPtr();
+  if (!p) {
+    return 0;
+  }
+  const view = new Int32Array(toArrayBuffer(p, 0, 4));
+  return view[0] ?? 0;
+}
+
+/** Clear thread errno so readdir EOF (null + errno 0) is distinguishable from error. */
+export function clearErrno(libc: LoadedLibc): void {
+  const p = libc.symbols.errnoPtr();
+  if (!p) {
+    return;
+  }
+  const view = new Int32Array(toArrayBuffer(p, 0, 4));
+  view[0] = 0;
+}
+
+/**
+ * Parse d_name from a dirent pointer using platform reclen/namlen bounds.
+ * Returns null for malformed records (caller treats as scan failure).
+ */
+export function parseDirentName(
+  ent: Pointer,
+  layout: DirentLayout
+): string | null {
+  // Header must cover through d_name start (includes reclen and optional namlen).
+  if (layout.dNameOffset < 18) {
+    return null;
+  }
+  let header: DataView;
+  try {
+    header = new DataView(toArrayBuffer(ent, 0, layout.dNameOffset));
+  } catch {
+    return null;
+  }
+
+  const reclen = header.getUint16(layout.dReclenOffset, true);
+  // Record must at least hold the fixed header + one byte of d_name room.
+  if (reclen < layout.dNameOffset + 1) {
+    return null;
+  }
+  const maxNameBytes = reclen - layout.dNameOffset;
+  // POSIX NAME_MAX is typically 255; reject absurd reclen-derived lengths.
+  if (maxNameBytes > 1024) {
+    return null;
+  }
+
+  let nameLen: number;
+  if (layout.dNamlenOffset !== null) {
+    const namlen = header.getUint16(layout.dNamlenOffset, true);
+    if (namlen > maxNameBytes) {
+      return null;
+    }
+    nameLen = namlen;
+  } else {
+    let bytes: Uint8Array;
+    try {
+      bytes = new Uint8Array(
+        toArrayBuffer(ent, layout.dNameOffset, maxNameBytes)
+      );
+    } catch {
+      return null;
+    }
+    let end = 0;
+    while (end < bytes.length && bytes[end] !== 0) {
+      end += 1;
+    }
+    // Linux dirents are NUL-terminated within d_reclen; missing NUL → malformed.
+    if (end === bytes.length) {
+      return null;
+    }
+    return Buffer.from(bytes.subarray(0, end)).toString();
+  }
+
+  if (nameLen === 0) {
+    return "";
+  }
+  try {
+    const nameBytes = new Uint8Array(
+      toArrayBuffer(ent, layout.dNameOffset, nameLen)
+    );
+    return Buffer.from(nameBytes).toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Enumerate child names via fdopendir/readdir, stopping after `maxNames + 1`
+ * observed entries so overflow is proven without materializing an unbounded list.
+ */
+export function readDirNames(
+  libc: LoadedLibc,
+  dirfd: number,
+  maxNames: number
+): { status: "ok"; names: string[] } | { status: "overflow" } {
+  if (!Number.isInteger(maxNames) || maxNames < 0) {
+    throw Object.assign(new Error("maxNames must be a non-negative integer"), {
+      code: "EINVAL",
+    });
+  }
+  // fdopendir consumes the fd on success — operate on a dup so the handle stays live.
+  const dupFd = libc.symbols.dup(dirfd);
+  if (dupFd < 0) {
+    throw errnoError(readErrno(libc), "dup", "");
+  }
+  const dirp = libc.symbols.fdopendir(dupFd);
+  if (!dirp) {
+    libc.symbols.close(dupFd);
+    throw errnoError(readErrno(libc), "fdopendir", "");
+  }
+  const names: string[] = [];
+  try {
+    while (true) {
+      clearErrno(libc);
+      const ent = libc.symbols.readdir(dirp);
+      if (!ent) {
+        const err = readErrno(libc);
+        if (err !== 0) {
+          throw errnoError(err, "readdir", "");
+        }
+        break;
+      }
+      const name = parseDirentName(ent, libc.dirent);
+      if (name === null) {
+        throw Object.assign(new Error("Malformed dirent record"), {
+          code: "EIO",
+          syscall: "readdir",
+        });
+      }
+      if (name === "" || name === "." || name === "..") {
+        continue;
+      }
+      // maxNames+1th name proves overflow; do not store it or continue.
+      if (names.length >= maxNames) {
+        return { status: "overflow" };
+      }
+      names.push(name);
+    }
+  } finally {
+    libc.symbols.closedir(dirp);
+  }
+  return { status: "ok", names };
+}
+
+export function openatOrThrow(
+  libc: LoadedLibc,
+  dirfd: number,
+  name: string,
+  flags: number,
+  syscall: string
+): number {
+  if (name.includes("\0") || name.includes("/") || name.includes("\\")) {
+    throw Object.assign(new Error(`Invalid directory entry name: ${name}`), {
+      code: "EINVAL",
+    });
+  }
+  const nameBuf = Buffer.from(`${name}\0`);
+  const fd = libc.symbols.openat(dirfd, ptr(nameBuf), flags);
+  if (fd < 0) {
+    throw errnoError(readErrno(libc), syscall, name);
+  }
+  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,
+  };
+}