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.

Reserve layer 0 for the file system --vfs-load mounts, and number the
others from 1. That source is then at the same reserved mount point in
every thread, whatever else a thread mounts and wherever --vfs-load is
written among the other mounts, so a path into it stays valid in a
worker - including a worker created with its own execArgv, which
inherits none of the parent's options and has to be given --vfs-load
again. A worker still does not run that entry point, but it now has to
recognize which source it belongs to in order to mount it at that layer.

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.

Add vfs.vfsBase(), which returns that directory, so a program can list
what is mounted without spelling out `path.join(os.devNull, 'vfs')`. The
note under vfs.mount() said the path scheme must not be relied on, which
read as a contradiction of the root being listable; it now says where a
mount point comes from, and that only the name within the root is
assigned at runtime.

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

Author: pipobscure

doc/api/cli.md

@@ -3812,6 +3812,11 @@ from an earlier `--vfs-mount` of the same source.
 In worker threads `--vfs-load` mounts but does not load: a worker inherits the
 same mounts, in the same order, and runs its own entry point.
 
+The source `--vfs-load` names is mounted at the same reserved mount point in
+every thread, whatever else that thread mounts, so a path into it stays valid
+in a worker - including one created with its own `execArgv`, which does not
+inherit the parent's options and has to be given `--vfs-load` again.
+
 `--vfs-load` is not permitted in [`NODE_OPTIONS`][]: which entry point runs is
 the command line's decision, and the environment must not be able to redirect
 it.

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()); // e.g. [ '1' ]
+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();
+
+fs.readdirSync(root); // e.g. [ '1' ]
+path.join(root, fs.readdirSync(root)[0]) === mountPoint; // true
+fs.readdirSync(root, { recursive: true }); // e.g. [ '1', '1/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

doc/node.1

@@ -1901,6 +1901,10 @@ The entry point then comes from the mount \fB--vfs-load\fR itself contributed, n
 from an earlier \fB--vfs-mount\fR of the same source.
 In worker threads \fB--vfs-load\fR mounts but does not load: a worker inherits the
 same mounts, in the same order, and runs its own entry point.
+The source \fB--vfs-load\fR names is mounted at the same reserved mount point in
+every thread, whatever else that thread mounts, so a path into it stays valid
+in a worker - including one created with its own \fBexecArgv\fR, which does not
+inherit the parent's options and has to be given \fB--vfs-load\fR again.
 \fB--vfs-load\fR is not permitted in \fBNODE_OPTIONS\fR: which entry point runs is
 the command line's decision, and the environment must not be able to redirect
 it.

lib/internal/process/pre_execution.js

@@ -223,9 +223,11 @@ let vfsLoadRoot;
 // the command line's own node options, in order. NODE_OPTIONS may add mounts
 // but not a --vfs-load, so anything it contributed sits ahead of these.
 // Returns -1 when no --vfs-load was given.
+//
+// A worker does not run the --vfs-load entry (see node_worker.cc), but it must
+// still recognize which source that entry is, so as to give it the reserved
+// layer its mount point has on every other thread.
 function getVfsLoadIndex(mountCount) {
-  if (!getOptionValue('[vfs_load_set]')) return -1;
-
   const execArgv = process.execArgv;
   let seen = 0;
   let found = -1;
@@ -267,12 +269,13 @@ function finishVfsMounts() {
   const fs = require('fs');
   const path = require('path');
   const { selectProvider } = require('internal/vfs/provider_registry');
-  const { VirtualFileSystem } = require('internal/vfs/file_system');
+  const { VirtualFileSystem, kLoadLayer } = require('internal/vfs/file_system');
 
-  // --vfs-load is forced off in workers (see node_worker.cc), so this records a
-  // load root only on the main thread; a worker re-mounts the same sources in
-  // the same order (the reserved paths line up) but runs its own entry.
   const loadIndex = getVfsLoadIndex(entries.length);
+  // [vfs_load_set] is forced off in workers (see node_worker.cc), so a worker
+  // mounts every source, the --vfs-load one at its reserved layer, and runs its
+  // own entry rather than the mount's.
+  const loads = getOptionValue('[vfs_load_set]');
   for (let i = 0; i < entries.length; i++) {
     const resolvedSource = path.resolve(entries[i]);
     let stats;
@@ -288,7 +291,11 @@ function finishVfsMounts() {
     if (provider === null) {
       throw new ERR_VFS_INVALID_TARGET(resolvedSource);
     }
-    const vfs = new VirtualFileSystem(provider, { emitExperimentalWarning: false });
+    const vfs = new VirtualFileSystem(provider, {
+      __proto__: null,
+      emitExperimentalWarning: false,
+      [kLoadLayer]: i === loadIndex,
+    });
     const mountPoint = vfs.mount();
     // The mount --vfs-load contributed is what the entry is require()d from;
     // process.argv[1] names the real source instead, since the reserved mount
@@ -297,7 +304,7 @@ function finishVfsMounts() {
     // The source is spliced in rather than assigned over argv[1]: the entry
     // comes from the mount, so nothing was consumed as an entry point and the
     // first positional argument is the program's own. Overwriting would drop it.
-    if (i === loadIndex) {
+    if (i === loadIndex && loads) {
       vfsLoadRoot = mountPoint;
       ArrayPrototypeSplice(process.argv, 1, 0, resolvedSource);
     }

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,
 };