vfs: unflag

Enable node:vfs by default. --no-experimental-vfs disables node:vfs
exposure and --vfs-load.

Assisted-by: pi
Signed-off-by: Matteo Collina <hello@matteocollina.com>
PR-URL: #66318
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>

Author: mcollina

doc/api/cli.md

@@ -330,7 +330,7 @@ so mounting one is gated on its own flag rather than on `--allow-fs-read` or
 `--allow-fs-write`.
 
 ```console
-$ node --experimental-vfs --permission --allow-fs-vfs app.js
+$ node --permission --allow-fs-vfs app.js
 ```
 
 ### `--allow-fs-write`
@@ -1711,16 +1711,6 @@ with AND, so a test must satisfy every expression to run.
 A malformed expression causes the test runner to exit with a non-zero status
 before running any tests.
 
-### `--experimental-vfs`
-
-<!-- YAML
-added: v26.4.0
--->
-
-> Stability: 1 - Experimental
-
-Enable the experimental [`node:vfs`][] module.
-
 ### `--experimental-vm-modules`
 
 <!-- YAML
@@ -2364,6 +2354,18 @@ changes:
 
 Disable the experimental [`node:sqlite`][] module.
 
+### `--no-experimental-vfs`
+
+<!-- YAML
+added: v26.4.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/66318
+    description: VFS is unflagged but still experimental.
+-->
+
+Disable the experimental [`node:vfs`][] module and `--vfs-load`.
+
 ### `--no-experimental-webstorage`
 
 <!-- YAML
@@ -3907,11 +3909,13 @@ added: v26.10.0
 
 * `source` {string} A directory or an archive file to mount and run.
 
-Requires [`--experimental-vfs`][]. May be given at most once.
+May be given at most once.
 
 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
+rather than the real file system. This option is unavailable when
+`--no-experimental-vfs` disables [`node:vfs`][]. 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
@@ -3942,18 +3946,17 @@ 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.
+worker must be given `--vfs-load` again; without it, that thread has no mount
+for the script to come from, and the worker fails to load it. [`node:vfs`][] is
+available to worker code without an experimental flag. 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
+$ node --vfs-load=app.zip
 ```
 
 ### `--watch`
@@ -4280,7 +4283,6 @@ one is included in the list below.
 * `--experimental-stream-iter`
 * `--experimental-test-isolation`
 * `--experimental-top-level-await`
-* `--experimental-vfs`
 * `--experimental-vm-modules`
 * `--experimental-wasi-unstable-preview1`
 * `--experimental-web-worker`
@@ -4315,6 +4317,7 @@ one is included in the list below.
 * `--no-experimental-global-navigator`
 * `--no-experimental-sqlite`
 * `--no-experimental-strip-types`
+* `--no-experimental-vfs`
 * `--no-experimental-webstorage`
 * `--no-extra-info-on-fatal-exception`
 * `--no-force-async-hooks-checks`
@@ -4914,7 +4917,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--env-file-if-exists`]: #--env-file-if-existsfile
 [`--env-file`]: #--env-filefile
 [`--experimental-sea-config`]: single-executable-applications.md#1-generating-single-executable-preparation-blobs
-[`--experimental-vfs`]: #--experimental-vfs
 [`--heap-prof-dir`]: #--heap-prof-dir
 [`--import`]: #--importmodule
 [`--no-require-module`]: #--no-require-module

doc/api/vfs.md

@@ -24,8 +24,8 @@ import vfs from 'node:vfs';
 const vfs = require('node:vfs');
 ```
 
-This module is only available under the `node:` scheme, and only when Node.js
-is started with the `--experimental-vfs` flag.
+This module is only available under the `node:` scheme. Loading it emits an
+`ExperimentalWarning`.
 
 ## Security
 
@@ -77,8 +77,9 @@ added: v26.4.0
 * `provider` {VirtualProvider} The provider to use. **Default:**
   `new MemoryProvider()`.
 * `options` {Object}
-  * `emitExperimentalWarning` {boolean} Whether to emit the experimental
-    warning when the instance is created. **Default:** `true`.
+  * `emitExperimentalWarning` {boolean} Whether to emit an experimental warning
+    when an instance is created. **Default:** `true`. Loading `node:vfs` emits
+    the warning regardless of this option.
 * Returns: {VirtualFileSystem}
 
 Convenience factory equivalent to `new VirtualFileSystem(provider, options)`.
@@ -148,7 +149,7 @@ vfs.registerProvider({
 ```
 
 ```console
-$ node --experimental-vfs --require ./provider.js \
+$ node --require ./provider.js \
        --vfs-load archive.customfmt
 ```
 
@@ -193,8 +194,9 @@ added: v26.4.0
 * `provider` {VirtualProvider} The provider to use. **Default:**
   `new MemoryProvider()`.
 * `options` {Object}
-  * `emitExperimentalWarning` {boolean} Whether to emit the experimental
-    warning. **Default:** `true`.
+  * `emitExperimentalWarning` {boolean} Whether to emit an experimental warning
+    when an instance is created. **Default:** `true`. Loading `node:vfs` emits
+    the warning regardless of this option.
 
 ### `vfs.mount()`
 

doc/node.1

@@ -210,7 +210,7 @@ A mounted VFS serves paths that the file system permissions do not describe,
 so mounting one is gated on its own flag rather than on \fB--allow-fs-read\fR or
 \fB--allow-fs-write\fR.
 .Bd -literal
-$ node --experimental-vfs --permission --allow-fs-vfs app.js
+$ node --permission --allow-fs-vfs app.js
 .Ed
 .
 .It Fl -allow-fs-write
@@ -930,9 +930,6 @@ with AND, so a test must satisfy every expression to run.
 A malformed expression causes the test runner to exit with a non-zero status
 before running any tests.
 .
-.It Fl -experimental-vfs
-Enable the experimental \fBnode:vfs\fR module.
-.
 .It Fl -experimental-vm-modules
 Enable experimental ES Module support in the \fBnode:vm\fR module.
 .
@@ -1233,6 +1230,9 @@ Legacy alias for \fB--no-require-module\fR.
 .It Fl -no-experimental-sqlite
 Disable the experimental \fBnode:sqlite\fR module.
 .
+.It Fl -no-experimental-vfs
+Disable the experimental \fBnode:vfs\fR module and \fB--vfs-load\fR.
+.
 .It Fl -no-experimental-webstorage
 Disable \fBWeb Storage\fR support.
 .
@@ -1973,10 +1973,12 @@ Print node's version.
 .It
 \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.
+May be given at most once.
 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
+rather than the real file system. This option is unavailable when
+\fB--no-experimental-vfs\fR disables \fBnode:vfs\fR. 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
@@ -2004,16 +2006,15 @@ 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.
+worker must be given \fB--vfs-load\fR again; without it, that thread has no mount
+for the script to come from, and the worker fails to load it. \fBnode:vfs\fR is
+available to worker code without an experimental flag. 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
+$ node --vfs-load=app.zip
 .Ed
 .
 .It Fl -watch
@@ -2271,8 +2272,6 @@ one is included in the list below.
 .It
 \fB--experimental-top-level-await\fR
 .It
-\fB--experimental-vfs\fR
-.It
 \fB--experimental-vm-modules\fR
 .It
 \fB--experimental-wasi-unstable-preview1\fR
@@ -2341,6 +2340,8 @@ one is included in the list below.
 .It
 \fB--no-experimental-strip-types\fR
 .It
+\fB--no-experimental-vfs\fR
+.It
 \fB--no-experimental-webstorage\fR
 .It
 \fB--no-extra-info-on-fatal-exception\fR

lib/internal/vfs/file_system.js

@@ -15,7 +15,6 @@ const {
     ERR_INVALID_STATE,
   },
 } = require('internal/errors');
-const { validateBoolean } = require('internal/validators');
 const { MemoryProvider } = require('internal/vfs/providers/memory');
 const path = require('path');
 const { posix: pathPosix, resolve: resolvePath, sep, toNamespacedPath } = path;
@@ -39,6 +38,7 @@ const {
 const { VirtualReadStream, VirtualWriteStream } = require('internal/vfs/streams');
 const { VirtualDir } = require('internal/vfs/dir');
 const { emitExperimentalWarning, kEmptyObject } = require('internal/util');
+const { validateBoolean } = require('internal/validators');
 let debug = require('internal/util/debuglog').debuglog('vfs', (fn) => {
   debug = fn;
 });
@@ -111,7 +111,6 @@ class VirtualFileSystem {
   /**
    * @param {VirtualProvider|object} [providerOrOptions] The provider to use, or options
    * @param {object} [options] Configuration options
-   * @param {boolean} [options.emitExperimentalWarning] Emit the experimental warning (default: true)
    */
   constructor(providerOrOptions, options = kEmptyObject) {
     let provider = null;

lib/vfs.js

@@ -4,6 +4,9 @@ const {
   FunctionPrototypeSymbolHasInstance,
 } = primordials;
 
+const { emitExperimentalWarning } = require('internal/util');
+emitExperimentalWarning('VirtualFileSystem');
+
 const { VirtualFileSystem } = require('internal/vfs/file_system');
 const { VirtualProvider } = require('internal/vfs/provider');
 const { MemoryProvider } = require('internal/vfs/providers/memory');

src/node.cc

@@ -1119,7 +1119,7 @@ static ExitCode InitializeNodeWithArgsInternal(
   {
     auto* env_options = per_process::cli_options->per_isolate->per_env.get();
     if (!env_options->experimental_vfs && env_options->vfs_load) {
-      errors->push_back("--vfs-load requires --experimental-vfs");
+      errors->push_back("--vfs-load requires node:vfs to be enabled");
     }
     // A second --vfs-load would silently replace the first, and the option
     // itself cannot say how often it was given; count it in the node options

src/node_options.cc

@@ -801,7 +801,8 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   AddOption("--experimental-vfs",
             "experimental node:vfs module",
             BOOL_FIELD(experimental_vfs),
-            kAllowedInEnvvar);
+            kAllowedInEnvvar,
+            true);
   // Choosing the entry point is the command line's alone: an environment
   // variable must not be able to redirect what a `node <args>` invocation runs,
   // so this is rejected in NODE_OPTIONS. The source and whether to run from it
@@ -810,7 +811,7 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   AddOption("--vfs-load",
             "mount a directory or archive as a virtual file system and run the "
             "entry point and module resolution against it instead of the real "
-            "file system (may be given once; requires --experimental-vfs)",
+            "file system (may be given once)",
             &EnvironmentOptions::vfs_load_source,
             kDisallowedInEnvvar);
   AddOption("[vfs_load_set]", "", BOOL_FIELD(vfs_load));

src/node_options.h

@@ -215,7 +215,7 @@ class EnvironmentOptions : public Options {
   DEFINE_BOOL_FIELD(experimental_websocket) = true;
   DEFINE_BOOL_FIELD(experimental_sqlite) = HAVE_SQLITE;
   DEFINE_BOOL_FIELD(experimental_stream_iter) = EXPERIMENTALS_DEFAULT_VALUE;
-  DEFINE_BOOL_FIELD(experimental_vfs) = EXPERIMENTALS_DEFAULT_VALUE;
+  DEFINE_BOOL_FIELD(experimental_vfs) = true;
   DEFINE_BOOL_FIELD(vfs_load) = false;
   DEFINE_BOOL_FIELD(webstorage) = HAVE_SQLITE;
   DEFINE_BOOL_FIELD(experimental_dtls) = EXPERIMENTALS_DEFAULT_VALUE;

test/ffi/test-ffi-vfs.js

@@ -1,4 +1,4 @@
-// Flags: --experimental-vfs
+// Flags: --disable-warning=ExperimentalWarning
 'use strict';
 const common = require('../common');
 common.skipIfFFIMissing();

test/parallel/test-module-builtin-experimental.js

@@ -1,3 +1,4 @@
+// Flags: --disable-warning=ExperimentalWarning
 'use strict';
 
 const common = require('../common');
@@ -8,7 +9,6 @@ const experimentalBuiltins = [
   ['bench/reporters', '--experimental-bench', true],
   ['dtls', '--experimental-dtls', common.hasDtls],
   ['quic', '--experimental-quic', common.hasQuic],
-  ['vfs', '--experimental-vfs', true],
 ].filter(([, , available]) => available);
 
 for (const [id, flag] of experimentalBuiltins) {
@@ -51,7 +51,14 @@ if (common.hasFFI) {
   ], { status: 0 });
 }
 
-const schemeOnlyBuiltins = ['node:test', 'node:sea'];
+// node:vfs is enabled by default and can be disabled with
+// --no-experimental-vfs.
+spawnSyncAndAssert(process.execPath, [
+  '--no-experimental-vfs',
+  '-e', `const m = require('node:module'); if (m.builtinModules.includes('node:vfs')) process.exit(1); try { require('node:vfs'); } catch (e) { if (e.code === 'ERR_UNKNOWN_BUILTIN_MODULE') process.exit(0); } process.exit(1);`,
+], { status: 0 });
+
+const schemeOnlyBuiltins = ['node:test', 'node:sea', 'node:vfs'];
 if (common.hasFFI) {
   schemeOnlyBuiltins.push('node:ffi');
 }