vfs: add symbolic link support

Add comprehensive symbolic link support to the Virtual File System:

- Add VirtualSymlink class for symlink entries
- Add createSymlinkStats() for symlink stat objects
- Add addSymlink(path, target) method to create symlinks
- Implement symlink resolution during path traversal
- statSync() follows symlinks, lstatSync() does not
- Add readlinkSync()/readlink() to read symlink targets
- realpathSync()/realpath() resolve symlink chains
- readdirSync() returns UV_DIRENT_LINK for symlinks
- Support relative and absolute symlink targets
- Handle symlink loops with ELOOP error (max depth: 40)
- Support symlinks in dynamic directories via scoped VFS

Author: mcollina

lib/internal/vfs/entries.js

@@ -13,7 +13,7 @@ const {
   },
 } = require('internal/errors');
 const { join } = require('path');
-const { createFileStats, createDirectoryStats } = require('internal/vfs/stats');
+const { createFileStats, createDirectoryStats, createSymlinkStats } = require('internal/vfs/stats');
 
 // Symbols for private properties
 const kContent = Symbol('kContent');
@@ -23,6 +23,7 @@ const kPopulated = Symbol('kPopulated');
 const kEntries = Symbol('kEntries');
 const kStats = Symbol('kStats');
 const kPath = Symbol('kPath');
+const kTarget = Symbol('kTarget');
 
 /**
  * Base class for virtual file system entries.
@@ -67,6 +68,14 @@ class VirtualEntry {
   isDirectory() {
     return false;
   }
+
+  /**
+   * Returns true if this entry is a symbolic link.
+   * @returns {boolean}
+   */
+  isSymbolicLink() {
+    return false;
+  }
 }
 
 /**
@@ -265,6 +274,38 @@ class VirtualDirectory extends VirtualEntry {
   }
 }
 
+/**
+ * Represents a virtual symbolic link.
+ */
+class VirtualSymlink extends VirtualEntry {
+  /**
+   * @param {string} path The absolute path of this symlink
+   * @param {string} target The symlink target (can be relative or absolute)
+   * @param {object} [options] Optional configuration
+   * @param {number} [options.mode] Symlink mode (default: 0o777)
+   */
+  constructor(path, target, options = {}) {
+    super(path);
+    this[kTarget] = target;
+    this[kStats] = createSymlinkStats(target.length, options);
+  }
+
+  /**
+   * @returns {boolean}
+   */
+  isSymbolicLink() {
+    return true;
+  }
+
+  /**
+   * Gets the symlink target path.
+   * @returns {string}
+   */
+  get target() {
+    return this[kTarget];
+  }
+}
+
 /**
  * Creates a scoped VFS interface for dynamic directory populate callbacks.
  * @param {VirtualDirectory} directory The parent directory
@@ -284,13 +325,19 @@ function createScopedVFS(directory, addEntry) {
       const dir = new VirtualDirectory(dirPath, populate, options);
       addEntry(name, dir);
     },
+    addSymlink(name, target, options) {
+      const linkPath = join(directory.path, name);
+      const symlink = new VirtualSymlink(linkPath, target, options);
+      addEntry(name, symlink);
+    },
   };
 }
 
 module.exports = {
   VirtualEntry,
   VirtualFile,
   VirtualDirectory,
+  VirtualSymlink,
   createScopedVFS,
   kContent,
   kContentProvider,
@@ -299,4 +346,5 @@ module.exports = {
   kEntries,
   kStats,
   kPath,
+  kTarget,
 };

lib/internal/vfs/errors.js

@@ -16,6 +16,7 @@ const {
   UV_EEXIST,
   UV_EROFS,
   UV_EINVAL,
+  UV_ELOOP,
 } = internalBinding('uv');
 
 /**
@@ -128,6 +129,22 @@ function createEINVAL(syscall, path) {
   return err;
 }
 
+/**
+ * Creates an ELOOP error for too many symbolic links.
+ * @param {string} syscall The system call name
+ * @param {string} path The path
+ * @returns {Error}
+ */
+function createELOOP(syscall, path) {
+  const err = new UVException({
+    errno: UV_ELOOP,
+    syscall,
+    path,
+  });
+  ErrorCaptureStackTrace(err, createELOOP);
+  return err;
+}
+
 module.exports = {
   createENOENT,
   createENOTDIR,
@@ -136,4 +153,5 @@ module.exports = {
   createEEXIST,
   createEROFS,
   createEINVAL,
+  createELOOP,
 };

lib/internal/vfs/stats.js

@@ -11,6 +11,7 @@ const {
   fs: {
     S_IFDIR,
     S_IFREG,
+    S_IFLNK,
   },
 } = internalBinding('constants');
 
@@ -136,8 +137,60 @@ function createDirectoryStats(options = {}) {
   return getStatsFromBinding(statsArray);
 }
 
+/**
+ * Creates a Stats object for a virtual symbolic link.
+ * @param {number} size The symlink size (length of target path)
+ * @param {object} [options] Optional stat properties
+ * @param {number} [options.mode] Symlink mode (default: 0o777)
+ * @param {number} [options.uid] User ID (default: process.getuid() or 0)
+ * @param {number} [options.gid] Group ID (default: process.getgid() or 0)
+ * @param {number} [options.atimeMs] Access time in ms
+ * @param {number} [options.mtimeMs] Modification time in ms
+ * @param {number} [options.ctimeMs] Change time in ms
+ * @param {number} [options.birthtimeMs] Birth time in ms
+ * @returns {Stats}
+ */
+function createSymlinkStats(size, options = {}) {
+  const now = DateNow();
+  const mode = (options.mode ?? 0o777) | S_IFLNK;
+  const uid = options.uid ?? (process.getuid?.() ?? 0);
+  const gid = options.gid ?? (process.getgid?.() ?? 0);
+  const atimeMs = options.atimeMs ?? now;
+  const mtimeMs = options.mtimeMs ?? now;
+  const ctimeMs = options.ctimeMs ?? now;
+  const birthtimeMs = options.birthtimeMs ?? now;
+  const blocks = MathCeil(size / 512);
+
+  const atime = msToTimeSpec(atimeMs);
+  const mtime = msToTimeSpec(mtimeMs);
+  const ctime = msToTimeSpec(ctimeMs);
+  const birthtime = msToTimeSpec(birthtimeMs);
+
+  statsArray[0] = 0;              // dev
+  statsArray[1] = mode;           // mode
+  statsArray[2] = 1;              // nlink
+  statsArray[3] = uid;            // uid
+  statsArray[4] = gid;            // gid
+  statsArray[5] = 0;              // rdev
+  statsArray[6] = kDefaultBlockSize; // blksize
+  statsArray[7] = 0;              // ino
+  statsArray[8] = size;           // size
+  statsArray[9] = blocks;         // blocks
+  statsArray[10] = atime.sec;     // atime_sec
+  statsArray[11] = atime.nsec;    // atime_nsec
+  statsArray[12] = mtime.sec;     // mtime_sec
+  statsArray[13] = mtime.nsec;    // mtime_nsec
+  statsArray[14] = ctime.sec;     // ctime_sec
+  statsArray[15] = ctime.nsec;    // ctime_nsec
+  statsArray[16] = birthtime.sec; // birthtime_sec
+  statsArray[17] = birthtime.nsec; // birthtime_nsec
+
+  return getStatsFromBinding(statsArray);
+}
+
 module.exports = {
   createFileStats,
   createDirectoryStats,
+  createSymlinkStats,
   kDefaultBlockSize,
 };