vfs: drop --vfs-mount, pin the load mount point

--vfs-mount mounted a source without running it, and shared one ordered
list of sources with --vfs-load, so neither option could say which entry
it had contributed: the entry point was recovered from the position of
--vfs-load among the mounts, in a list NODE_OPTIONS could prepend to.
Nothing needs more than one mount from the command line: a program that
wants more can mount them itself through node:vfs, where it also gets
the instance.

Remove --vfs-mount, leaving --vfs-load with the single source it mounts
and runs, and reserve layer 0 for that source, numbering the file
systems a program mounts itself from 1. The source is then at the same
mount point in every thread, whatever else that thread mounts -
including a thread where a --require preload mounted a file system of
its own first - so a path into it stays valid in a worker.

A worker still does not run that entry point: it inherits the source but
not the decision to load from it. A worker created with its own execArgv
inherits neither, so the documentation now says that such a worker must
be given --experimental-vfs and --vfs-load again to run a script from
the mount, and that --experimental-vfs is also what makes node:vfs
available to the worker's own code.

ERR_VFS_INVALID_TARGET now names --vfs-load as the source's origin, and
the startup test moves to test-vfs-load.js, with the cases that covered
mounting without loading removed and cases for the reserved mount point
added.

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

Author: pipobscure

doc/api/cli.md

@@ -3795,56 +3795,18 @@ added: REPLACEME
 
 Requires [`--experimental-vfs`][]. May be given at most once.
 
-Mounts `source` exactly as [`--vfs-mount`][] does, and additionally runs the
-entry point and all subsequent `require()`/`import` resolution against that
-mount rather than the real file system. The entry point is taken from the mount
-the same way `node <directory>` takes one: the mount's own `package.json`
-`"main"`, or `index.js`. Any positional command-line argument is the program's
-own (available from `process.argv[2]` onward), never an entry-point override.
+Mounts `source` as a virtual file system ([`node:vfs`][]), and runs the entry
+point and all subsequent `require()`/`import` resolution against that mount
+rather than the real file system. The mount is placed at a reserved mount point
+assigned by Node.js, so it never shadows real paths and no target can be
+chosen. The entry point is taken from the mount the same way `node <directory>`
+takes one: the mount's own `package.json` `"main"`, or `index.js`. Any
+positional command-line argument is the program's own (available from
+`process.argv[2]` onward), never an entry-point override.
 
 `process.argv[1]` reports `source` rather than the reserved mount point, since
 the mount point is an opaque implementation detail.
 
-Mounting the same source twice mounts it twice, at two separate mount points.
-The entry point then comes from the mount `--vfs-load` itself contributed, not
-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.
-
-`--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.
-
-```console
-$ node --experimental-vfs --vfs-load=app.zip
-$ node --experimental-vfs --vfs-mount=lib.zip --vfs-load=app.zip
-```
-
-### `--vfs-mount=source`
-
-<!-- YAML
-added: REPLACEME
--->
-
-* `source` {string} A directory or an archive file to mount.
-
-Requires [`--experimental-vfs`][]. May be repeated to mount several sources.
-
-Mounts `source` as a virtual file system ([`node:vfs`][]). Each mount is placed
-at a reserved mount point assigned by Node.js, so mounts never shadow real
-paths and no target can be chosen. Mounting alone does not change the entry
-point; use [`--vfs-load`][] for the source to run from.
-
-`--vfs-mount` and [`--vfs-load`][] mount in the order they are written, so
-
-```console
-$ node --experimental-vfs --vfs-mount=a --vfs-load=b --vfs-mount=c
-```
-
-mounts `a`, `b` and `c` in that order and runs `b`. Mounts contributed by
-[`NODE_OPTIONS`][] are mounted before the command line's.
-
 The provider backing a source is chosen from the source itself rather than from
 its file name:
 
@@ -3857,6 +3819,29 @@ preloaded with [`--require`][] or [`--import`][]) are consulted first, in
 reverse registration order, and may claim directories as well as files. If no
 provider claims the source, Node.js exits with an error.
 
+In worker threads `--vfs-load` mounts but does not load: a worker inherits the
+mount and runs its own entry point, which may itself live in the mount.
+
+The source is mounted at the same reserved mount point in every thread that
+mounts it, whatever else that thread mounts, so a path into the mount means the
+same thing in all of them.
+
+A worker created with its own `execArgv` inherits none of the parent's options,
+and so does not mount the source at all. To run a script from the mount, such a
+worker must be given the same options again, `--experimental-vfs` and
+`--vfs-load`; without them, that thread has no mount for the script to come
+from, and the worker fails to load it. `--experimental-vfs` is also what makes
+[`node:vfs`][] available to the worker's own code. A worker whose script comes
+from anywhere else, such as the real file system, needs nothing added.
+
+`--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.
+
+```console
+$ node --experimental-vfs --vfs-load=app.zip
+```
+
 ### `--watch`
 
 <!-- YAML
@@ -4299,7 +4284,6 @@ one is included in the list below.
 * `--use-openssl-ca`
 * `--use-system-ca`
 * `--v8-pool-size`
-* `--vfs-mount`
 * `--watch-kill-signal`
 * `--watch-path`
 * `--watch-preserve-output`
@@ -4825,8 +4809,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--require`]: #-r---require-module
 [`--use-env-proxy`]: #--use-env-proxy
 [`--use-system-ca`]: #--use-system-ca
-[`--vfs-load`]: #--vfs-loadsource
-[`--vfs-mount`]: #--vfs-mountsource
 [`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
 [`Buffer`]: buffer.md#class-buffer
 [`CRYPTO_secure_malloc_init`]: https://www.openssl.org/docs/man3.0/man3/CRYPTO_secure_malloc_init.html

doc/api/errors.md

@@ -3569,7 +3569,7 @@ entry types are found.
 
 ### `ERR_VFS_INVALID_TARGET`
 
-A `--vfs-mount` source does not exist, is neither a regular file nor a
+A `--vfs-load` source does not exist, is neither a regular file nor a
 directory, or is a source no provider claims.
 
 <a id="ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING"></a>

doc/api/vfs.md

@@ -106,7 +106,7 @@ added: REPLACEME
   * `create` {Function} Called with the resolved path and its [`fs.Stats`][].
     Returns the {VirtualProvider} backing the source.
 
-Registers a provider that [`--vfs-mount`][] can select for a source it
+Registers a provider that [`--vfs-load`][] can select for a source it
 recognizes, so a file format Node.js has no built-in provider for can still be
 mounted.
 
@@ -118,7 +118,7 @@ source, the built-in providers handle it: a directory with
 [`RealFSProvider`][], and a file whose bytes are a ZIP archive with
 [`ZipProvider`][].
 
-Providers must be registered before the mounts are created. Register from a
+Providers must be registered before the source is mounted. Register from a
 module preloaded with [`--require`][] or [`--import`][]:
 
 ```cjs
@@ -702,7 +702,7 @@ fields use synthetic but stable values:
 [Single Executable Application]: single-executable-applications.md
 [`--import`]: cli.md#--importmodule
 [`--require`]: cli.md#-r---require-module
-[`--vfs-mount`]: cli.md#--vfs-mountsource
+[`--vfs-load`]: cli.md#--vfs-loadsource
 [`MemoryProvider`]: #class-memoryprovider
 [`RealFSProvider`]: #class-realfsprovider
 [`VirtualFileSystem`]: #class-virtualfilesystem

doc/node.1

@@ -1888,43 +1888,16 @@ Print node's version.
 \fBsource\fR \fB{string}\fR A directory or an archive file to mount and run.
 .El
 Requires \fB--experimental-vfs\fR. May be given at most once.
-Mounts \fBsource\fR exactly as \fB--vfs-mount\fR does, and additionally runs the
-entry point and all subsequent \fBrequire()\fR/\fBimport\fR resolution against that
-mount rather than the real file system. The entry point is taken from the mount
-the same way \fBnode <directory>\fR takes one: the mount's own \fBpackage.json\fR
-\fB"main"\fR, or \fBindex.js\fR. Any positional command-line argument is the program's
-own (available from \fBprocess.argv[2]\fR onward), never an entry-point override.
+Mounts \fBsource\fR as a virtual file system (\fBnode:vfs\fR), and runs the entry
+point and all subsequent \fBrequire()\fR/\fBimport\fR resolution against that mount
+rather than the real file system. The mount is placed at a reserved mount point
+assigned by Node.js, so it never shadows real paths and no target can be
+chosen. The entry point is taken from the mount the same way \fBnode <directory>\fR
+takes one: the mount's own \fBpackage.json\fR \fB"main"\fR, or \fBindex.js\fR. Any
+positional command-line argument is the program's own (available from
+\fBprocess.argv[2]\fR onward), never an entry-point override.
 \fBprocess.argv[1]\fR reports \fBsource\fR rather than the reserved mount point, since
 the mount point is an opaque implementation detail.
-Mounting the same source twice mounts it twice, at two separate mount points.
-The entry point then comes from the mount \fB--vfs-load\fR itself contributed, not
-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.
-\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.
-.Bd -literal
-$ node --experimental-vfs --vfs-load=app.zip
-$ node --experimental-vfs --vfs-mount=lib.zip --vfs-load=app.zip
-.Ed
-.
-.It Fl -vfs-mount Ns = Ns Ar source
-.Bl -bullet
-.It
-\fBsource\fR \fB{string}\fR A directory or an archive file to mount.
-.El
-Requires \fB--experimental-vfs\fR. May be repeated to mount several sources.
-Mounts \fBsource\fR as a virtual file system (\fBnode:vfs\fR). Each mount is placed
-at a reserved mount point assigned by Node.js, so mounts never shadow real
-paths and no target can be chosen. Mounting alone does not change the entry
-point; use \fB--vfs-load\fR for the source to run from.
-\fB--vfs-mount\fR and \fB--vfs-load\fR mount in the order they are written, so
-.Bd -literal
-$ node --experimental-vfs --vfs-mount=a --vfs-load=b --vfs-mount=c
-.Ed
-mounts \fBa\fR, \fBb\fR and \fBc\fR in that order and runs \fBb\fR. Mounts contributed by
-\fBNODE_OPTIONS\fR are mounted before the command line's.
 The provider backing a source is chosen from the source itself rather than from
 its file name:
 .Bl -bullet
@@ -1938,6 +1911,24 @@ Providers registered with \fBvfs.registerProvider()\fR (typically from a module
 preloaded with \fB--require\fR or \fB--import\fR) are consulted first, in
 reverse registration order, and may claim directories as well as files. If no
 provider claims the source, Node.js exits with an error.
+In worker threads \fB--vfs-load\fR mounts but does not load: a worker inherits the
+mount and runs its own entry point, which may itself live in the mount.
+The source is mounted at the same reserved mount point in every thread that
+mounts it, whatever else that thread mounts, so a path into the mount means the
+same thing in all of them.
+A worker created with its own \fBexecArgv\fR inherits none of the parent's options,
+and so does not mount the source at all. To run a script from the mount, such a
+worker must be given the same options again, \fB--experimental-vfs\fR and
+\fB--vfs-load\fR; without them, that thread has no mount for the script to come
+from, and the worker fails to load it. \fB--experimental-vfs\fR is also what makes
+\fBnode:vfs\fR available to the worker's own code. A worker whose script comes
+from anywhere else, such as the real file system, needs nothing added.
+\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.
+.Bd -literal
+$ node --experimental-vfs --vfs-load=app.zip
+.Ed
 .
 .It Fl -watch
 Starts Node.js in watch mode.
@@ -2430,8 +2421,6 @@ one is included in the list below.
 .It
 \fB--v8-pool-size\fR
 .It
-\fB--vfs-mount\fR
-.It
 \fB--watch-kill-signal\fR
 .It
 \fB--watch-path\fR

lib/internal/errors.js

@@ -1962,7 +1962,7 @@ E('ERR_USE_AFTER_CLOSE', '%s was closed', Error);
 E('ERR_VALID_PERFORMANCE_ENTRY_TYPE',
   'At least one valid performance entry type is required', Error);
 E('ERR_VFS_INVALID_TARGET',
-  '%s is not a valid --vfs-mount source: must be an existing file or directory', Error);
+  '%s is not a valid --vfs-load source: must be an existing file or directory', Error);
 E('ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING',
   'A dynamic import callback was not specified.', TypeError);
 E('ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG',

lib/internal/main/worker_thread.js

@@ -145,8 +145,8 @@ port.on('message', (message) => {
       // initializeAsyncLoaderHooksOnLoaderHookWorker() which needs to run preloads
       // after the asynchronous loader hooks are registered.
       initializeModuleLoaders({ shouldSpawnLoaderHookWorker: true, shouldPreloadModules: true });
-      // Re-mount inherited --vfs-mount sources so their reserved paths (which a
-      // worker filename may point into) resolve in this thread too. With
+      // Re-mount the inherited --vfs-load source so its reserved path (which a
+      // worker filename may point into) resolves in this thread too. With
       // --import, mounting is deferred to after that loop in run_main, matching
       // the main thread; finishVfsMounts() is idempotent so it runs once.
       if (getOptionValue('--import').length === 0) {

lib/internal/process/pre_execution.js

@@ -14,8 +14,6 @@ const {
   ObjectDefineProperty,
   ObjectFreeze,
   String,
-  StringPrototypeIndexOf,
-  StringPrototypeSlice,
   globalThis,
 } = primordials;
 
@@ -216,91 +214,58 @@ function setupVmModules() {
 let vfsMounted = false;
 let vfsLoadRoot;
 
-// --vfs-mount and --vfs-load append to one list, so `mounts` is already in the
-// order the command line gave, and the entry point comes from whichever of them
-// --vfs-load contributed. The parser stores plain strings and cannot record
-// which flag produced an entry, so its position is recovered from execArgv -
-// 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.
-function getVfsLoadIndex(mountCount) {
-  if (!getOptionValue('[vfs_load_set]')) return -1;
-
-  const execArgv = process.execArgv;
-  let seen = 0;
-  let found = -1;
-  for (let i = 0; i < execArgv.length; i++) {
-    const arg = execArgv[i];
-    let name = arg;
-    const eq = StringPrototypeIndexOf(arg, '=');
-    let spaced = false;
-    if (eq !== -1) {
-      name = StringPrototypeSlice(arg, 0, eq);
-    } else {
-      // `--vfs-mount value`: the value is the next argument, so skip it rather
-      // than counting it as a flag of its own.
-      spaced = true;
-    }
-    if (name !== '--vfs-mount' && name !== '--vfs-load') continue;
-    if (name === '--vfs-load') found = seen;
-    seen++;
-    if (spaced) i++;
-  }
-  if (found === -1) return -1;
-  // Mounts from NODE_OPTIONS are parsed first and so precede the command
-  // line's; `seen` counts only the latter.
-  return mountCount - seen + found;
-}
-
-// Mounts every --vfs-mount source. Called from prepareExecution() when there is
+// Mounts the --vfs-load source. Called from prepareExecution() when there is
 // no --import, and otherwise from run_main after the --import loop has run; the
-// guard makes the second call a no-op so a provider registered by either a -r or
-// an --import preload is available before its source's provider is chosen.
+// guard makes the second call a no-op so a provider registered by either a -r
+// or an --import preload is available before the source's provider is chosen.
 function finishVfsMounts() {
   if (vfsMounted) return;
   vfsMounted = true;
 
-  const entries = getOptionValue('--vfs-mount');
-  if (entries.length === 0) return;
-  emitExperimentalWarning('--vfs-mount');
+  const source = getOptionValue('--vfs-load');
+  if (source === '') return;
+  emitExperimentalWarning('--vfs-load');
 
   const fs = require('fs');
   const path = require('path');
   const { selectProvider } = require('internal/vfs/provider_registry');
-  const { VirtualFileSystem } = 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);
-  for (let i = 0; i < entries.length; i++) {
-    const resolvedSource = path.resolve(entries[i]);
-    let stats;
-    try {
-      stats = fs.statSync(resolvedSource);
-    } catch {
-      throw new ERR_VFS_INVALID_TARGET(resolvedSource);
-    }
-    if (!stats.isDirectory() && !stats.isFile()) {
-      throw new ERR_VFS_INVALID_TARGET(resolvedSource);
-    }
-    const provider = selectProvider(resolvedSource, stats);
-    if (provider === null) {
-      throw new ERR_VFS_INVALID_TARGET(resolvedSource);
-    }
-    const vfs = new VirtualFileSystem(provider, { emitExperimentalWarning: false });
-    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
-    // point is an opaque implementation detail.
-    //
-    // 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) {
-      vfsLoadRoot = mountPoint;
-      ArrayPrototypeSplice(process.argv, 1, 0, resolvedSource);
-    }
+  const { VirtualFileSystem, kLoadLayer } = require('internal/vfs/file_system');
+
+  const resolvedSource = path.resolve(source);
+  let stats;
+  try {
+    stats = fs.statSync(resolvedSource);
+  } catch {
+    throw new ERR_VFS_INVALID_TARGET(resolvedSource);
+  }
+  if (!stats.isDirectory() && !stats.isFile()) {
+    throw new ERR_VFS_INVALID_TARGET(resolvedSource);
+  }
+  const provider = selectProvider(resolvedSource, stats);
+  if (provider === null) {
+    throw new ERR_VFS_INVALID_TARGET(resolvedSource);
+  }
+  // The source is mounted at the layer reserved for it, so it is at the same
+  // reserved path in every thread.
+  const vfs = new VirtualFileSystem(provider, {
+    __proto__: null,
+    emitExperimentalWarning: false,
+    [kLoadLayer]: true,
+  });
+  const mountPoint = vfs.mount();
+  // A worker inherits the source but not [vfs_load_set] (see node_worker.cc):
+  // it mounts the same source, and so reaches it at the same reserved path,
+  // but runs its own entry point.
+  //
+  // On the main thread the entry is require()d from the mount point, while
+  // process.argv[1] reports the source, since the reserved mount point is an
+  // opaque implementation detail. 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 (getOptionValue('[vfs_load_set]')) {
+    vfsLoadRoot = mountPoint;
+    ArrayPrototypeSplice(process.argv, 1, 0, resolvedSource);
   }
 }