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 the last segment of its path, 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.

Add vfs.vfsBase(), which returns the path of that directory, so that a
program can read it without spelling the path out.

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

@@ -152,6 +152,29 @@ $ node --experimental-vfs --require ./provider.js \
        --vfs-load archive.customfmt
 ```
 
+## `vfs.vfsBase()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {string} The absolute path of the [reserved root directory][].
+
+Returns the directory that holds the mount points of every mounted virtual file
+system, which is `path.join(os.devNull, 'vfs')`. Reading it lists what is
+mounted; see [The reserved root directory][reserved root directory].
+
+```cjs
+const vfs = require('node:vfs');
+const fs = require('node:fs');
+
+const myVfs = vfs.create();
+const mountPoint = myVfs.mount();
+
+fs.readdirSync(vfs.vfsBase()); // The name of every mount point in it
+mountPoint.startsWith(vfs.vfsBase()); // true
+```
+
 ## Class: `VirtualFileSystem`
 
 <!-- YAML
@@ -187,9 +210,11 @@ After mounting, files in the VFS can be accessed through the
 using paths under the returned mount point.
 
 Mount points always live inside a reserved namespace that cannot have child file system entries,
-so virtual paths never conflate with (or shadow) real paths. The virtual path scheme is subject to
-change and users should not manually construct them based on assumptions. Instead, obtain
-them from what `vfs.mount()` returns or `vfs.mountPoint`.
+so virtual paths never conflate with (or shadow) real paths. A mount point is obtained from what
+`vfs.mount()` returns or from [`vfs.mountPoint`][], and the mount points of all mounted file
+systems can be listed by reading the [reserved root directory][], whose path [`vfs.vfsBase()`][]
+returns. The name of a mount point within that directory is assigned at runtime, so it is not
+something to construct or hard-code.
 
 ```cjs
 const vfs = require('node:vfs');
@@ -203,6 +228,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 +410,32 @@ 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 can be read through [`node:fs`][]. [`vfs.vfsBase()`][] returns its path,
+`path.join(os.devNull, 'vfs')`. 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 path = require('node:path');
+
+const root = vfs.vfsBase();
+const assets = vfs.create();
+assets.writeFileSync('/logo.svg', '<svg/>');
+const mountPoint = assets.mount();
+
+const name = path.basename(mountPoint);
+fs.readdirSync(root); // [ name ]
+fs.readdirSync(root, { recursive: true }); // [ name, `${name}/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 +767,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
@@ -721,8 +780,10 @@ fields use synthetic but stable values:
 [`vfs.mountPointURL`]: #vfsmountpointurl
 [`vfs.mountPoint`]: #vfsmountpoint
 [`vfs.unmount()`]: #vfsunmount
+[`vfs.vfsBase()`]: #vfsvfsbase
 [`zipFile.writable`]: zlib.md#zipfilewritable
 [`zlib.ZipBuffer`]: zlib.md#class-zlibzipbuffer
 [`zlib.ZipFile`]: zlib.md#class-zlibzipfile
 [loading from `node_modules` folders]: modules.md#loading-from-node_modules-folders
+[reserved root directory]: #the-reserved-root-directory
 [the global folders]: modules.md#loading-from-the-global-folders

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');
 const kLoadLayer = Symbol('kLoadLayer');
 
 // Layer 0 is reserved for the file system --vfs-load mounts, so that source is
@@ -80,6 +85,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;
 
@@ -122,10 +133,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] = options[kLoadLayer] === true ? kLoadLayerId : nextLayerId++;
   }
 
@@ -260,6 +281,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;
@@ -343,28 +366,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;
   }
 
@@ -386,6 +417,7 @@ class VirtualFileSystem {
    */
   rmdirSync(dirPath) {
     const providerPath = this.#toProviderPath(dirPath);
+    checkNotRoot(providerPath, 'rmdir', dirPath);
     this[kProvider].rmdirSync(providerPath);
   }
 
@@ -406,6 +438,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);
   }
 
@@ -774,7 +808,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));
   }
 
   /**
@@ -1134,6 +1169,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) {
@@ -1163,7 +1200,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) {
@@ -1174,6 +1212,7 @@ class VirtualFileSystem {
 
       async rmdir(dirPath) {
         const providerPath = toProviderPath(dirPath);
+        checkNotRoot(providerPath, 'rmdir', dirPath);
         return provider.rmdir(providerPath);
       },
 
@@ -1185,6 +1224,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);
       },
 
@@ -1240,7 +1281,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));
         }
@@ -1316,5 +1357,6 @@ module.exports = {
   VirtualFileSystem,
   kLayerId,
   kLoadLayer,
+  kReservedRoot,
   normalizeMountedPath,
 };