vfs: make the reserved root readable through fs

The reserved root `${os.devNull}/vfs`, which holds the mount points of
all virtual file systems, could not be read: fs calls on it fell through
to the real file system, so nothing could list what was mounted.

While any file system is mounted, serve the root as a read-only
directory. It lists every mount point by its layer id, a recursive
listing descends into each mounted file system, and paths under it that
no mount serves report ENOENT. Creating, removing or changing entries in
it fails with EROFS. When nothing is mounted it does not exist, as
before.

A mount point cannot be removed or renamed, nor replaced by a rename:
rmdir() and rename() fail with EBUSY, and a recursive rm() empties the
file system and then fails the same way. Before, rmdir() of an empty
mount point reported success without doing anything.

The callback and promise forms of readdir() with `withFileTypes` now
report each Dirent's parentPath as a host path, as readdirSync() did,
instead of the provider-relative one, and split recursive names such as
`dir/file.txt` into their directory and base name. A recursive listing
joins subdirectories with the host separator rather than `/`, which
mixed separators on Windows. realpath() of a mount point no longer
returns it with a trailing separator.

Signed-off-by: Philipp Dunkel <pip@pipobscure.com>

Author: pipobscure

doc/api/vfs.md

@@ -203,6 +203,11 @@ const mountPoint = myVfs.mount();
 fs.readFileSync(`${mountPoint}/data.txt`, 'utf8'); // 'Hello'
 ```
 
+Like any mount point, the mount point cannot be removed or renamed, nor
+replaced by renaming something else onto it: [`fs.rmdir()`][] and
+[`fs.rename()`][] fail with `EBUSY`. A recursive [`fs.rm()`][] of the mount
+point empties the file system before failing the same way.
+
 Each `VirtualFileSystem` instance may be mounted at most once at a
 time. Attempting to mount an already-mounted instance throws
 `ERR_INVALID_STATE`. Because each instance mounts inside its own
@@ -380,6 +385,33 @@ The promise namespace mirrors `fs.promises` and includes `readFile`,
 `access`, `rm`, `truncate`, `link`, `mkdtemp`, `chmod`, `chown`, `lchown`,
 `utimes`, `lutimes`, `open`, `lchmod`, and `watch`.
 
+## The reserved root directory
+
+While any virtual file system is mounted, the directory that holds the mount
+points, `path.join(os.devNull, 'vfs')`, can be read through [`node:fs`][]. It
+contains a directory for every mounted file system, named like the last segment
+of its [`vfs.mountPoint`][].
+
+```cjs
+const vfs = require('node:vfs');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const root = path.join(os.devNull, 'vfs');
+const assets = vfs.create();
+assets.writeFileSync('/logo.svg', '<svg/>');
+const mountPoint = assets.mount();
+
+fs.readdirSync(root); // e.g. [ '0' ]
+path.join(root, fs.readdirSync(root)[0]) === mountPoint; // true
+fs.readdirSync(root, { recursive: true }); // e.g. [ '0', '0/logo.svg' ]
+```
+
+The root directory itself is read-only. Creating, removing, or changing its
+entries fails with `EROFS`, while the file systems its entries lead to can be
+written to as usual. When nothing is mounted, the root directory does not exist.
+
 ## Module loader integration
 
 Once a `VirtualFileSystem` is mounted, paths under the mount point
@@ -711,6 +743,9 @@ fields use synthetic but stable values:
 [`ffi.dlopen()`]: ffi.md#ffidlopenpath-definitions
 [`fs.BigIntStats`]: fs.md#class-fsstats
 [`fs.Stats`]: fs.md#class-fsstats
+[`fs.rename()`]: fs.md#fsrenameoldpath-newpath-callback
+[`fs.rm()`]: fs.md#fsrmpath-options-callback
+[`fs.rmdir()`]: fs.md#fsrmdirpath-options-callback
 [`import.meta.resolve()`]: esm.md#importmetaresolvespecifier
 [`new ffi.DynamicLibrary()`]: ffi.md#new-dynamiclibrarypath
 [`node:fs`]: fs.md

lib/internal/vfs/errors.js

@@ -19,6 +19,7 @@ const {
   UV_EINVAL,
   UV_ELOOP,
   UV_EACCES,
+  UV_EBUSY,
   UV_EXDEV,
 } = internalBinding('uv');
 
@@ -180,6 +181,16 @@ function createEACCES(syscall, path) {
   return err;
 }
 
+function createEBUSY(syscall, path) {
+  const err = new UVException({
+    errno: UV_EBUSY,
+    syscall,
+    path,
+  });
+  ErrorCaptureStackTrace(err, createEBUSY);
+  return err;
+}
+
 function createEXDEV(syscall, path) {
   const err = new UVException({
     errno: UV_EXDEV,
@@ -201,5 +212,6 @@ module.exports = {
   createEINVAL,
   createELOOP,
   createEACCES,
+  createEBUSY,
   createEXDEV,
 };

lib/internal/vfs/file_system.js

@@ -3,6 +3,8 @@
 const {
   MathRandom,
   ObjectFreeze,
+  StringPrototypeLastIndexOf,
+  StringPrototypeSlice,
   StringPrototypeStartsWith,
   Symbol,
   SymbolDispose,
@@ -21,6 +23,7 @@ const { join: joinPath } = pathPosix;
 const {
   getLayerRoot,
   getRelativePath,
+  getVfsRoot,
 } = require('internal/vfs/router');
 const {
   openVirtualFd,
@@ -30,6 +33,7 @@ const {
 const {
   createENOENT,
   createEBADF,
+  createEBUSY,
   createEISDIR,
 } = require('internal/vfs/errors');
 const { VirtualReadStream, VirtualWriteStream } = require('internal/vfs/streams');
@@ -47,6 +51,7 @@ const kNormalizedMountPoint = Symbol('kNormalizedMountPoint');
 const kMounted = Symbol('kMounted');
 const kPromises = Symbol('kPromises');
 const kLayerId = Symbol('kLayerId');
+const kReservedRoot = Symbol('kReservedRoot');
 
 let nextLayerId = 0;
 
@@ -74,6 +79,12 @@ function randomSuffix() {
   return suffix;
 }
 
+// The root of a file system is its mount point, and like any mount point it
+// cannot be removed or renamed, nor replaced by a rename.
+function checkNotRoot(providerPath, syscall, path) {
+  if (providerPath === '/') throw createEBUSY(syscall, path);
+}
+
 let registerVFS;
 let deregisterVFS;
 
@@ -116,10 +127,20 @@ class VirtualFileSystem {
     }
 
     this[kProvider] = provider ?? new MemoryProvider();
+    this[kPromises] = null;
+    if (options[kReservedRoot] === true) {
+      // Serves the reserved root directory itself. It is not a layer, so it
+      // takes no layer id and leaves the numbering of real mounts alone.
+      const root = getVfsRoot();
+      this[kMountPoint] = root;
+      this[kNormalizedMountPoint] = normalizeMountedPath(root);
+      this[kMounted] = true;
+      this[kLayerId] = -1;
+      return;
+    }
     this[kMountPoint] = null;
     this[kNormalizedMountPoint] = null;
     this[kMounted] = false;
-    this[kPromises] = null;
     this[kLayerId] = nextLayerId++;
   }
 
@@ -254,6 +275,8 @@ class VirtualFileSystem {
    */
   #toMountedPath(providerPath) {
     if (this[kMounted] && this[kMountPoint]) {
+      // path.join() would keep the trailing separator of the provider root.
+      if (providerPath === '/') return this[kMountPoint];
       return path.join(this[kMountPoint], providerPath);
     }
     return providerPath;
@@ -337,28 +360,36 @@ class VirtualFileSystem {
   readdirSync(dirPath, options) {
     const providerPath = this.#toProviderPath(dirPath);
     const result = this[kProvider].readdirSync(providerPath, options);
+    return this.#toMountedDirents(dirPath, result, options);
+  }
 
-    // Rewrite Dirent parentPath from provider-relative to VFS path.
-    if (options?.withFileTypes === true) {
-      const recursive = options?.recursive === true;
-      for (let i = 0; i < result.length; i++) {
-        const dirent = result[i];
-        if (recursive) {
-          // In recursive mode, name may contain slashes (e.g. 'a/b.txt').
-          const slashIdx = dirent.name.lastIndexOf('/');
-          if (slashIdx !== -1) {
-            const subdir = dirent.name.slice(0, slashIdx);
-            dirent.parentPath = joinPath(dirPath, subdir);
-            dirent.name = dirent.name.slice(slashIdx + 1);
-          } else {
-            dirent.parentPath = dirPath;
-          }
-        } else {
-          dirent.parentPath = dirPath;
+  /**
+   * Rewrites the Dirents of a listing of `dirPath` from provider-relative to
+   * VFS paths, so that each `parentPath` is the directory the entry is in.
+   * @param {string} dirPath The listed directory, as given by the caller
+   * @param {string[]|Dirent[]} result The provider's listing
+   * @param {object} [options] The readdir options
+   * @returns {string[]|Dirent[]}
+   */
+  #toMountedDirents(dirPath, result, options) {
+    if (options?.withFileTypes !== true) return result;
+    const recursive = options?.recursive === true;
+    // A mounted VFS is addressed by host paths, so, like fs, join with the
+    // host's separator; an unmounted one uses POSIX paths throughout.
+    const join = this[kMounted] ? path.join : joinPath;
+    for (let i = 0; i < result.length; i++) {
+      const dirent = result[i];
+      dirent.parentPath = dirPath;
+      if (recursive) {
+        // In recursive mode, name may contain slashes (e.g. 'a/b.txt').
+        const slashIdx = StringPrototypeLastIndexOf(dirent.name, '/');
+        if (slashIdx !== -1) {
+          const subdir = StringPrototypeSlice(dirent.name, 0, slashIdx);
+          dirent.parentPath = join(dirPath, subdir);
+          dirent.name = StringPrototypeSlice(dirent.name, slashIdx + 1);
         }
       }
     }
-
     return result;
   }
 
@@ -380,6 +411,7 @@ class VirtualFileSystem {
    */
   rmdirSync(dirPath) {
     const providerPath = this.#toProviderPath(dirPath);
+    checkNotRoot(providerPath, 'rmdir', dirPath);
     this[kProvider].rmdirSync(providerPath);
   }
 
@@ -400,6 +432,8 @@ class VirtualFileSystem {
   renameSync(oldPath, newPath) {
     const oldProviderPath = this.#toProviderPath(oldPath);
     const newProviderPath = this.#toProviderPath(newPath);
+    checkNotRoot(oldProviderPath, 'rename', oldPath);
+    checkNotRoot(newProviderPath, 'rename', newPath);
     this[kProvider].renameSync(oldProviderPath, newProviderPath);
   }
 
@@ -768,7 +802,8 @@ class VirtualFileSystem {
     }
 
     this[kProvider].readdir(this.#toProviderPath(dirPath), options)
-      .then((entries) => callback(null, entries), (err) => callback(err));
+      .then((entries) => callback(null, this.#toMountedDirents(dirPath, entries, options)),
+            (err) => callback(err));
   }
 
   /**
@@ -1128,6 +1163,8 @@ class VirtualFileSystem {
     const toProviderPath = (p) => this.#toProviderPath(p);
     const toProviderPrefix = (p) => this.#toProviderPrefix(p);
     const toMountedPath = (p) => this.#toMountedPath(p);
+    const toMountedDirents = (p, result, options) =>
+      this.#toMountedDirents(p, result, options);
 
     return ObjectFreeze({
       async readFile(filePath, options) {
@@ -1157,7 +1194,8 @@ class VirtualFileSystem {
 
       async readdir(dirPath, options) {
         const providerPath = toProviderPath(dirPath);
-        return provider.readdir(providerPath, options);
+        const result = await provider.readdir(providerPath, options);
+        return toMountedDirents(dirPath, result, options);
       },
 
       async mkdir(dirPath, options) {
@@ -1168,6 +1206,7 @@ class VirtualFileSystem {
 
       async rmdir(dirPath) {
         const providerPath = toProviderPath(dirPath);
+        checkNotRoot(providerPath, 'rmdir', dirPath);
         return provider.rmdir(providerPath);
       },
 
@@ -1179,6 +1218,8 @@ class VirtualFileSystem {
       async rename(oldPath, newPath) {
         const oldProviderPath = toProviderPath(oldPath);
         const newProviderPath = toProviderPath(newPath);
+        checkNotRoot(oldProviderPath, 'rename', oldPath);
+        checkNotRoot(newProviderPath, 'rename', newPath);
         return provider.rename(oldProviderPath, newProviderPath);
       },
 
@@ -1234,7 +1275,7 @@ class VirtualFileSystem {
           for (let i = 0; i < entries.length; i++) {
             await this.rm(joinPath(filePath, entries[i]), options);
           }
-          await provider.rmdir(toProviderPath(filePath));
+          await this.rmdir(filePath);
         } else {
           await provider.unlink(toProviderPath(filePath));
         }
@@ -1309,5 +1350,6 @@ class VirtualFileSystem {
 module.exports = {
   VirtualFileSystem,
   kLayerId,
+  kReservedRoot,
   normalizeMountedPath,
 };