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>
PR-URL: #66162
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

Author: pipobscure

doc/api/cli.md

@@ -3783,56 +3783,18 @@ added: v26.10.0
 
 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: v26.10.0
--->
-
-* `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:
 
@@ -3845,6 +3807,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
@@ -4285,7 +4270,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`
@@ -4811,8 +4795,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

@@ -3548,7 +3548,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: v26.10.0
   * `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

@@ -1201,7 +1201,7 @@ Legacy alias for \fB--no-require-module\fR.
 Disable the experimental \fBnode:sqlite\fR module.
 .
 .It Fl -no-experimental-websocket
-Disable exposition of \fB<WebSocket>\fR on the global scope.
+Disable exposition of \fB{WebSocket}\fR on the global scope.
 .
 .It Fl -no-experimental-webstorage
 Disable \fBWeb Storage\fR support.
@@ -1891,46 +1891,19 @@ Print node's version.
 .It Fl -vfs-load Ns = Ns Ar source
 .Bl -bullet
 .It
-\fBsource\fR \fB<string>\fR A directory or an archive file to mount and run.
+\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
@@ -1944,6 +1917,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.
@@ -2436,8 +2427,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

@@ -1959,7 +1959,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) {