vfs: gate node:vfs behind --experimental-vfs flag

mcollina · mcollina · commit 27063b5270b8 · 2026-05-04T17:59:22.000+02:00
Adds an --experimental-vfs runtime option that gates loading of the
node:vfs builtin module, matching the pattern used by node:quic and
node:stream/iter. Without the flag, require('node:vfs') / import
'node:vfs' throw ERR_UNKNOWN_BUILTIN_MODULE.

All VFS test files are updated to pass --experimental-vfs.

Assisted-by: Claude-Opus4.7
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -1332,6 +1332,16 @@ added: v25.9.0
 
 Enable the experimental [`node:stream/iter`][] module.
 
+### `--experimental-vfs`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Enable the experimental [`node:vfs`][] module.
+
 ### `--experimental-test-coverage`
 
 <!-- YAML
@@ -3710,6 +3720,7 @@ 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`
 * `--force-context-aware`
@@ -4351,6 +4362,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`node:ffi`]: ffi.md
 [`node:sqlite`]: sqlite.md
 [`node:stream/iter`]: stream_iter.md
+[`node:vfs`]: vfs.md
 [`process.setUncaughtExceptionCaptureCallback()`]: process.md#processsetuncaughtexceptioncapturecallbackfn
 [`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version
 [`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version
diff --git a/doc/api/vfs.md b/doc/api/vfs.md
@@ -24,7 +24,8 @@ import vfs from 'node:vfs';
 const vfs = require('node:vfs');
 ```
 
-This module is only available under the `node:` scheme.
+This module is only available under the `node:` scheme, and only when Node.js
+is started with the `--experimental-vfs` flag.
 
 ## Overview
 
diff --git a/lib/internal/bootstrap/realm.js b/lib/internal/bootstrap/realm.js
@@ -133,7 +133,7 @@ const schemelessBlockList = new SafeSet([
   'vfs',
 ]);
 // Modules that will only be enabled at run time.
-const experimentalModuleList = new SafeSet(['ffi', 'sqlite', 'quic', 'stream/iter', 'zlib/iter']);
+const experimentalModuleList = new SafeSet(['ffi', 'sqlite', 'quic', 'stream/iter', 'zlib/iter', 'vfs']);
 
 // Set up process.binding() and process._linkedBinding().
 {
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
@@ -117,6 +117,7 @@ function prepareExecution(options) {
   setupFFI();
   setupSQLite();
   setupStreamIter();
+  setupVfs();
   setupQuic();
   setupWebStorage();
   setupWebsocket();
@@ -421,6 +422,15 @@ function setupQuic() {
   BuiltinModule.allowRequireByUsers('quic');
 }
 
+function setupVfs() {
+  if (!getOptionValue('--experimental-vfs')) {
+    return;
+  }
+
+  const { BuiltinModule } = require('internal/bootstrap/realm');
+  BuiltinModule.allowRequireByUsers('vfs');
+}
+
 function setupWebStorage() {
   if (getEmbedderOptions().noBrowserGlobals ||
       !getOptionValue('--experimental-webstorage')) {
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -610,6 +610,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "experimental iterable streams API (node:stream/iter)",
             &EnvironmentOptions::experimental_stream_iter,
             kAllowedInEnvvar);
+  AddOption("--experimental-vfs",
+            "experimental node:vfs module",
+            &EnvironmentOptions::experimental_vfs,
+            kAllowedInEnvvar);
   AddOption("--experimental-quic",
 #ifndef OPENSSL_NO_QUIC
             "experimental QUIC support",
diff --git a/src/node_options.h b/src/node_options.h
@@ -132,6 +132,7 @@ class EnvironmentOptions : public Options {
   bool experimental_websocket = true;
   bool experimental_sqlite = HAVE_SQLITE;
   bool experimental_stream_iter = EXPERIMENTALS_DEFAULT_VALUE;
+  bool experimental_vfs = EXPERIMENTALS_DEFAULT_VALUE;
   bool webstorage = HAVE_SQLITE;
   bool experimental_quic = EXPERIMENTALS_DEFAULT_VALUE;
   std::string localstorage_file;
diff --git a/test/parallel/test-vfs-access-modes.js b/test/parallel/test-vfs-access-modes.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // access / accessSync honour the R_OK / W_OK / X_OK / F_OK mode bits and
diff --git a/test/parallel/test-vfs-append-write.js b/test/parallel/test-vfs-append-write.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // writeSync in append mode must append, not overwrite.
diff --git a/test/parallel/test-vfs-bigint-position.js b/test/parallel/test-vfs-bigint-position.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // VFS readSync should accept a BigInt position parameter.
diff --git a/test/parallel/test-vfs-callback-api.js b/test/parallel/test-vfs-callback-api.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Exercise the VFS callback-style async API on every method.
diff --git a/test/parallel/test-vfs-copyfile-mode.js b/test/parallel/test-vfs-copyfile-mode.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Tests for VFS copyFile mode support:
diff --git a/test/parallel/test-vfs-create.js b/test/parallel/test-vfs-create.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Constructor variants and option validation for vfs.create() and
diff --git a/test/parallel/test-vfs-ctime-update.js b/test/parallel/test-vfs-ctime-update.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 require('../common');
diff --git a/test/parallel/test-vfs-dir-handle.js b/test/parallel/test-vfs-dir-handle.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Exercise the VirtualDir handle returned by opendirSync.
diff --git a/test/parallel/test-vfs-fd.js b/test/parallel/test-vfs-fd.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 const common = require('../common');
diff --git a/test/parallel/test-vfs-file-handle.js b/test/parallel/test-vfs-file-handle.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Exercise VirtualFileHandle / MemoryFileHandle methods directly via
diff --git a/test/parallel/test-vfs-flag.js b/test/parallel/test-vfs-flag.js
@@ -0,0 +1,48 @@
+'use strict';
+
+// node:vfs is gated behind --experimental-vfs. Without the flag the
+// module is not exposed; bare `vfs` (without the node: scheme) is also
+// blocked.
+
+require('../common');
+const { spawnSync } = require('child_process');
+const assert = require('assert');
+
+// Without the flag, requiring node:vfs throws ERR_UNKNOWN_BUILTIN_MODULE.
+{
+  const r = spawnSync(process.execPath, [
+    '-e', 'require("node:vfs")',
+  ]);
+  assert.strictEqual(r.status, 1);
+  assert.match(r.stderr.toString(), /ERR_UNKNOWN_BUILTIN_MODULE/);
+}
+
+// Without the flag, importing node:vfs throws ERR_UNKNOWN_BUILTIN_MODULE.
+{
+  const r = spawnSync(process.execPath, [
+    '--input-type=module',
+    '-e', 'import("node:vfs").catch((e) => { console.error(e.code); process.exit(1); });',
+  ]);
+  assert.strictEqual(r.status, 1);
+  assert.match(r.stderr.toString(), /ERR_UNKNOWN_BUILTIN_MODULE/);
+}
+
+// With the flag, node:vfs loads and works.
+{
+  const r = spawnSync(process.execPath, [
+    '--experimental-vfs',
+    '-e', "const v = require('node:vfs'); const x = v.create(); x.writeFileSync('/x', 'hi'); console.log(x.readFileSync('/x', 'utf8'));",
+  ]);
+  assert.strictEqual(r.status, 0, r.stderr.toString());
+  assert.strictEqual(r.stdout.toString().trim(), 'hi');
+}
+
+// Bare `vfs` (no node: scheme) is always blocked.
+{
+  const r = spawnSync(process.execPath, [
+    '--experimental-vfs',
+    '-e', "require('vfs')",
+  ]);
+  assert.strictEqual(r.status, 1);
+  assert.match(r.stderr.toString(), /Cannot find module 'vfs'/);
+}
diff --git a/test/parallel/test-vfs-hardlink-nlink.js b/test/parallel/test-vfs-hardlink-nlink.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Test that nlink count is updated correctly when creating/removing hard links.
diff --git a/test/parallel/test-vfs-link.js b/test/parallel/test-vfs-link.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Hard-link error cases: creating a link to a directory or to an
diff --git a/test/parallel/test-vfs-memory-file-handle.js b/test/parallel/test-vfs-memory-file-handle.js
@@ -1,4 +1,4 @@
-// Flags: --expose-internals
+// Flags: --experimental-vfs --expose-internals
 'use strict';
 
 // MemoryFileHandle internals: the "stats not available" path when there
diff --git a/test/parallel/test-vfs-memory-provider-dynamic.js b/test/parallel/test-vfs-memory-provider-dynamic.js
@@ -1,4 +1,4 @@
-// Flags: --expose-internals
+// Flags: --experimental-vfs --expose-internals
 'use strict';
 
 // MemoryProvider supports dynamic content providers and lazily-populated
diff --git a/test/parallel/test-vfs-memory-provider-flags.js b/test/parallel/test-vfs-memory-provider-flags.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // MemoryProvider: numeric open flags (mirroring fs.constants.O_*) must be
diff --git a/test/parallel/test-vfs-memory-provider.js b/test/parallel/test-vfs-memory-provider.js
@@ -1,4 +1,4 @@
-// Flags: --expose-internals
+// Flags: --experimental-vfs --expose-internals
 'use strict';
 
 const common = require('../common');
diff --git a/test/parallel/test-vfs-mkdir.js b/test/parallel/test-vfs-mkdir.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // mkdirSync / rmdirSync behaviour: return value, recursive option, mode
diff --git a/test/parallel/test-vfs-mkdtemp.js b/test/parallel/test-vfs-mkdtemp.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // mkdtemp / mkdtempSync behaviour.
diff --git a/test/parallel/test-vfs-parent-timestamps.js b/test/parallel/test-vfs-parent-timestamps.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Operations that modify a directory should bump its mtime/ctime.
diff --git a/test/parallel/test-vfs-promises-open.js b/test/parallel/test-vfs-promises-open.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // VFS promises.open returns a usable handle.
diff --git a/test/parallel/test-vfs-promises.js b/test/parallel/test-vfs-promises.js
@@ -1,4 +1,4 @@
-// Flags: --expose-internals
+// Flags: --experimental-vfs --expose-internals
 'use strict';
 
 const common = require('../common');
diff --git a/test/parallel/test-vfs-readdir-symlink-recursive.js b/test/parallel/test-vfs-readdir-symlink-recursive.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Recursive readdir must follow symlinks to directories.
diff --git a/test/parallel/test-vfs-readfile-async.js b/test/parallel/test-vfs-readfile-async.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // VFS readFile callback API.
diff --git a/test/parallel/test-vfs-readfile-encoding.js b/test/parallel/test-vfs-readfile-encoding.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // readFileSync with invalid encoding must throw.
diff --git a/test/parallel/test-vfs-readfile-flag.js b/test/parallel/test-vfs-readfile-flag.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 const common = require('../common');
diff --git a/test/parallel/test-vfs-real-provider-handle.js b/test/parallel/test-vfs-real-provider-handle.js
@@ -1,4 +1,4 @@
-// Flags: --expose-internals
+// Flags: --experimental-vfs --expose-internals
 'use strict';
 
 // RealFileHandle: sync and async file-handle operations, plus EBADF
diff --git a/test/parallel/test-vfs-real-provider-promises.js b/test/parallel/test-vfs-real-provider-promises.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Promises API for RealFSProvider: every async/promises method,
diff --git a/test/parallel/test-vfs-real-provider-symlinks.js b/test/parallel/test-vfs-real-provider-symlinks.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Symlink and path-escape behaviour for RealFSProvider.
diff --git a/test/parallel/test-vfs-real-provider-watch.js b/test/parallel/test-vfs-real-provider-watch.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // watch / promises.watch / watchFile through RealFSProvider.
diff --git a/test/parallel/test-vfs-real-provider.js b/test/parallel/test-vfs-real-provider.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Synchronous API for RealFSProvider: construction, basic file ops,
diff --git a/test/parallel/test-vfs-rename.js b/test/parallel/test-vfs-rename.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Rename behaviour: overwrite, type mismatches, same-parent rename.
diff --git a/test/parallel/test-vfs-rm-edge-cases.js b/test/parallel/test-vfs-rm-edge-cases.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Tests for VFS rmSync edge cases:
diff --git a/test/parallel/test-vfs-rmdir-symlink.js b/test/parallel/test-vfs-rmdir-symlink.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // rmdirSync on a symlink to a directory should throw ENOTDIR
diff --git a/test/parallel/test-vfs-stats-bigint.js b/test/parallel/test-vfs-stats-bigint.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Verify { bigint: true } returns BigInt values for VFS stats.
diff --git a/test/parallel/test-vfs-stats-helpers.js b/test/parallel/test-vfs-stats-helpers.js
@@ -1,4 +1,4 @@
-// Flags: --expose-internals
+// Flags: --experimental-vfs --expose-internals
 'use strict';
 
 // Exercise the default-option paths in createFileStats / createDirectoryStats
diff --git a/test/parallel/test-vfs-stats-ino-dev.js b/test/parallel/test-vfs-stats-ino-dev.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // VFS stats must have non-zero, unique ino and a distinctive dev.
diff --git a/test/parallel/test-vfs-stream-errors.js b/test/parallel/test-vfs-stream-errors.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Error paths in VFS streams: missing files, EBADF on closed fds,
diff --git a/test/parallel/test-vfs-stream-explicit-fd.js b/test/parallel/test-vfs-stream-explicit-fd.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Test createReadStream / createWriteStream with an explicit `fd` option.
diff --git a/test/parallel/test-vfs-stream-properties.js b/test/parallel/test-vfs-stream-properties.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // VFS streams must expose bytesRead, bytesWritten, and pending.
diff --git a/test/parallel/test-vfs-stream-validation.js b/test/parallel/test-vfs-stream-validation.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // VFS stream constructors must validate start/end synchronously.
diff --git a/test/parallel/test-vfs-streams.js b/test/parallel/test-vfs-streams.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 const common = require('../common');
diff --git a/test/parallel/test-vfs-symlinks.js b/test/parallel/test-vfs-symlinks.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Symlink behaviour in the default (memory) VFS:
diff --git a/test/parallel/test-vfs-truncate-negative.js b/test/parallel/test-vfs-truncate-negative.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // truncateSync with negative length must clamp to 0, not throw.
diff --git a/test/parallel/test-vfs-utimes.js b/test/parallel/test-vfs-utimes.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // utimes / lutimes accept Date instances, numeric seconds, strings,
diff --git a/test/parallel/test-vfs-virtual-file-handle.js b/test/parallel/test-vfs-virtual-file-handle.js
@@ -1,4 +1,4 @@
-// Flags: --expose-internals
+// Flags: --experimental-vfs --expose-internals
 'use strict';
 
 // Cover the VirtualFileHandle base class — all primitives must throw
diff --git a/test/parallel/test-vfs-virtual-provider.js b/test/parallel/test-vfs-virtual-provider.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Exercise the VirtualProvider base class — its capability flags,
diff --git a/test/parallel/test-vfs-watch-abort-signal.js b/test/parallel/test-vfs-watch-abort-signal.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // AbortSignal handling for watch() and promises.watch().
diff --git a/test/parallel/test-vfs-watch-directory.js b/test/parallel/test-vfs-watch-directory.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Tests for VFS directory watching:
diff --git a/test/parallel/test-vfs-watch-encoding.js b/test/parallel/test-vfs-watch-encoding.js
@@ -1,3 +1,4 @@
+// Flags: --experimental-vfs
 'use strict';
 
 // Buffer encoding for watch(): filename arrives as a Buffer.
diff --git a/test/parallel/test-vfs-watch-promises.js b/test/parallel/test-vfs-watch-promises.js
diff --git a/test/parallel/test-vfs-watch-recursive.js b/test/parallel/test-vfs-watch-recursive.js
diff --git a/test/parallel/test-vfs-watch.js b/test/parallel/test-vfs-watch.js
diff --git a/test/parallel/test-vfs-watchfile.js b/test/parallel/test-vfs-watchfile.js
diff --git a/test/parallel/test-vfs-write-options.js b/test/parallel/test-vfs-write-options.js

Original file line number	Diff line number	Diff line change
`@@ -133,7 +133,7 @@ const schemelessBlockList = new SafeSet([`
`133`	`133`	`'vfs',`
`134`	`134`	`]);`
`135`	`135`	`// Modules that will only be enabled at run time.`
`136`		`-const experimentalModuleList = new SafeSet(['ffi', 'sqlite', 'quic', 'stream/iter', 'zlib/iter']);`
	`136`	`+const experimentalModuleList = new SafeSet(['ffi', 'sqlite', 'quic', 'stream/iter', 'zlib/iter', 'vfs']);`
`137`	`137`
`138`	`138`	`// Set up process.binding() and process._linkedBinding().`
`139`	`139`	`{`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Flags: --experimental-vfs`
`1`	`2`	`'use strict';`
`2`	`3`
`3`	`4`	`// access / accessSync honour the R_OK / W_OK / X_OK / F_OK mode bits and`