vfs: mount inside a reserved namespace

Move VFS mounts into `${os.devNull}/vfs/layer-<id>/<prefix>`, a
reserved location that cannot exist on the real file system because
`os.devNull` is a character device on POSIX and a device-namespace
path on Windows - neither can have child filesystem entries. Virtual
paths never conflate with real paths, and the owning layer of a path
is decidable by inspecting the path itself.

The prefix passed to `vfs.mount(prefix)` becomes a purely logical name
inside the namespace - it is never resolved against `process.cwd()`.
`mount()` returns the resulting absolute mount point. Two instances
using the same prefix cannot collide, so overlap detection is gone.

Because the namespace makes ownership self-describing, this removes:

- the per-VFS `ownedFilenames` / `ownedPathCacheKeys` sets;
- the `Module._pathCache` write recorder;
- the `?vfs-layer=<id>` search-param tagging in the ESM resolver;
- the Windows drive-less-URL fixup in finalizeResolution.

Dispatch collapses to one normalization, one prefix check against the
namespace root, and a map lookup on the layer id - constant time in the
number of mounted layers. Unmount purges loader caches by a prefix scan
of the mount point, which fixes the two correctness gaps flagged in
review: symlink realpaths inside a VFS always resolve under the mount
point, so cached entries under any symlinked realpath are purged; and
resolved URLs are plain file URLs under the mount point, so
`import(import.meta.resolve(x))` hits the same module job on repeat.

`os.devNull` was chosen over `process.execPath` because it is
ASCII-clean by definition. This keeps mount points safe to embed in
dynamic-`import()` specifiers even when Node.js itself is installed
under a directory whose name contains URL-reserved characters (a case
exercised by the "linux-arm" CI job that runs from a path containing
`?` and other unusual characters).

`fs.statSync` / `fs.lstatSync` now catch ENOENT from the VFS handler
when `throwIfNoEntry` is false, matching the native binding contract.
The VFS handler surfaces ENOENT unconditionally for missing entries;
the fall-through to the real file system would otherwise traverse
`os.devNull` and produce ENOTDIR.

Docs, tests and benchmark adapted. `benchmark/vfs/bench-fs-dispatch.js`
now reports flat per-call latency across 1..10 mounted layers, versus
~80 ns/layer for stat/exists/access and ~200 ns/layer for readFile
before this change.

Refs: https://github.com/nodejs/single-executable/blob/main/docs/virtual-file-system-requirements.md#no-interference-with-valid-paths-in-the-file-system

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Author: mcollina

benchmark/vfs/bench-fs-dispatch.js

@@ -9,11 +9,12 @@
 //   binding.op(getValidatedPath(path));
 //
 // With layers=0 the VFS module is never required and `h === null` is
-// the first thing fs sees. With layers>=1 the handler walks
-// activeVFSList calling vfs.shouldHandle(path) on each. The benchmark
-// mounts N VFSes at distinct, unrelated mount points and probes a real
-// file under __dirname, so every call falls through after the VFS list
-// declines the path. That isolates per-layer dispatch cost.
+// the first thing fs sees. With layers>=1 the handler normalizes the
+// path once and rejects it with a single prefix comparison against the
+// reserved VFS namespace - the number of mounted layers should not
+// matter. The benchmark mounts N VFSes and probes a real file under
+// __dirname, so every call falls through after the namespace check
+// declines the path.
 
 const common = require('../common.js');
 const fs = require('fs');
@@ -23,7 +24,7 @@ const bench = common.createBenchmark(main, {
   n: [3e5],
   op: ['statSync', 'existsSync', 'accessSync', 'readFileSync'],
   // 0 = VFS module never loaded (true baseline)
-  // >=1 = that many VFS instances mounted at unrelated paths
+  // >=1 = that many VFS instances mounted
   layers: [0, 1, 2, 5, 10],
 }, {
   flags: ['--experimental-vfs', '--no-warnings'],
@@ -34,7 +35,7 @@ function mountLayers(count) {
   const handles = [];
   for (let i = 0; i < count; i++) {
     const v = vfs.create();
-    v.mount(`/vfs-bench-${i}`);
+    v.mount('/bench');
     handles.push(v);
   }
   return handles;

doc/api/vfs.md

@@ -112,39 +112,50 @@ added: v26.4.0
   * `emitExperimentalWarning` {boolean} Whether to emit the experimental
     warning. **Default:** `true`.
 
-### `vfs.mount(prefix)`
+### `vfs.mount([prefix])`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* `prefix` {string} The path prefix where the VFS will be mounted.
-* Returns: {VirtualFileSystem} The VFS instance, for chaining or `using`.
-
-Mounts the virtual file system at the specified path prefix. After
-mounting, files in the VFS can be accessed through the `node:fs`
-module — and resolved through `require()` and `import` — using paths
-that start with the prefix.
-
-If a real file-system path already exists at the mount prefix, the
-VFS **shadows** that path: every operation against a path under the
-mount point is directed to the VFS until the VFS is unmounted.
+* `prefix` {string} A logical name for the mount inside the reserved
+  VFS namespace. Interpreted as a relative path; leading separators
+  are ignored. **Default:** `'/'`.
+* Returns: {string} The absolute mount point.
+
+Mounts the virtual file system and returns the resulting mount point.
+After mounting, files in the VFS can be accessed through the
+`node:fs` module — and resolved through `require()` and `import` —
+using paths under the returned mount point.
+
+Mount points always live inside a reserved namespace,
+`${os.devNull}/vfs/layer-<layerId>/`. Because [`os.devNull`][] is a
+character device (POSIX) or a device-namespace path (Windows) that
+cannot have child filesystem entries, no real file-system path can
+exist under this namespace: virtual paths never conflate with (or
+shadow) real paths, and the layer that owns a path is visible in the
+path itself. The `prefix` argument is a purely logical name inside
+the namespace — it is never resolved against the working directory,
+and a prefix that attempts to escape the namespace (for example with
+`..` segments) throws `ERR_INVALID_ARG_VALUE`.
 
 ```cjs
 const vfs = require('node:vfs');
 const fs = require('node:fs');
 
 const myVfs = vfs.create();
 myVfs.writeFileSync('/data.txt', 'Hello');
-myVfs.mount('/virtual');
+const mountPoint = myVfs.mount('/virtual');
+// e.g. '/dev/null/vfs/layer-0/virtual'
 
-fs.readFileSync('/virtual/data.txt', 'utf8'); // 'Hello'
+fs.readFileSync(`${mountPoint}/data.txt`, 'utf8'); // 'Hello'
 ```
 
 Each `VirtualFileSystem` instance may be mounted at most once at a
 time. Attempting to mount an already-mounted instance throws
-`ERR_INVALID_STATE`. Mounting two instances at overlapping prefixes
-(e.g., `/virtual` and `/virtual/sub`) also throws `ERR_INVALID_STATE`.
+`ERR_INVALID_STATE`. Because each instance mounts inside its own
+`layer-<layerId>` namespace, mounts from different instances can
+never overlap, even when they use the same `prefix`.
 
 The VFS supports the [Explicit Resource Management][] proposal. Use
 a `using` declaration to unmount automatically when leaving scope:
@@ -153,15 +164,16 @@ a `using` declaration to unmount automatically when leaving scope:
 const vfs = require('node:vfs');
 const fs = require('node:fs');
 
+let mountPoint;
 {
   using myVfs = vfs.create();
   myVfs.writeFileSync('/data.txt', 'Hello');
-  myVfs.mount('/virtual');
+  mountPoint = myVfs.mount('/virtual');
 
-  fs.readFileSync('/virtual/data.txt', 'utf8'); // 'Hello'
+  fs.readFileSync(`${mountPoint}/data.txt`, 'utf8'); // 'Hello'
 } // VFS is automatically unmounted here
 
-fs.existsSync('/virtual/data.txt'); // false
+fs.existsSync(`${mountPoint}/data.txt`); // false
 ```
 
 ### `vfs.unmount()`
@@ -196,8 +208,9 @@ added: REPLACEME
 
 * {string | null}
 
-The current mount-point path as an absolute string, or `null` when
-the VFS is not mounted.
+The current mount point as an absolute string (the value returned by
+the last [`vfs.mount(prefix)`][] call), or `null` when the VFS is not
+mounted.
 
 ### `vfs.layerId`
 
@@ -212,16 +225,10 @@ construction. The id is stable across `mount()` / `unmount()` cycles
 for the lifetime of the instance, and is independent of the order in
 which VFS layers are mounted.
 
-The layer id is the building block for cache scoping (see
-[Module loader integration][]):
-
-* it surfaces in `import.meta.url` for ES modules loaded from this
-  VFS, as a `?vfs-layer=<id>` search parameter, so that the cascaded
-  loader's caches can be scoped per VFS;
-* it appears in the `NODE_DEBUG=vfs` output for `register` and
-  `deregister` events;
-* it appears in the `ERR_INVALID_STATE` error message thrown when two
-  VFS instances try to mount at overlapping prefixes.
+The layer id forms the `layer-<id>` segment of the reserved mount
+namespace, so every path served by this instance carries the id, and
+it appears in the `NODE_DEBUG=vfs` output for `register` and
+`deregister` events.
 
 ```cjs
 const vfs = require('node:vfs');
@@ -322,7 +329,7 @@ The promise namespace mirrors `fs.promises` and includes `readFile`,
 
 ## Module loader integration
 
-Once a `VirtualFileSystem` is mounted, paths under the mount prefix
+Once a `VirtualFileSystem` is mounted, paths under the mount point
 participate in module resolution and loading. Both
 `require()` / `require.resolve()` (CommonJS) and `import` /
 `import.meta.resolve()` (ECMAScript modules) consult the VFS through
@@ -339,44 +346,26 @@ myVfs.mkdirSync('/lib');
 myVfs.writeFileSync('/lib/greet.js', 'module.exports = () => "hi";');
 myVfs.writeFileSync(
   '/lib/package.json', '{"main": "./greet.js"}');
-myVfs.mount('/virtual');
+const mountPoint = myVfs.mount('/virtual');
 
-const greet = require('/virtual/lib');
+const greet = require(`${mountPoint}/lib`);
 console.log(greet()); // 'hi'
 
 myVfs.unmount();
 ```
 
-### Cache scoping and `import.meta.url`
-
-Module loaders maintain caches that survive the lifetime of any
-single VFS. To keep entries from leaking once a VFS is unmounted
-without invalidating unrelated real-fs imports, two mechanisms are
-combined:
-
-* **CommonJS caches** (`require.cache`, the internal stat and
-  realpath caches, and the `package.json` caches) are filtered on
-  `unmount()`: entries whose absolute filename would be claimed by
-  the VFS going away are deleted. `__filename` and `module.filename`
-  are unchanged - they remain plain absolute paths.
-
-* **ECMAScript module URLs** are tagged at resolve time. When the
-  resolver determines that a path belongs to a mounted VFS, it
-  appends `?vfs-layer=<id>` (where `<id>` is the owning instance's
-  [`vfs.layerId`][]) to the resolved URL. The tag therefore appears
-  in `import.meta.url` and in cache keys, and on `unmount()` the
-  cascaded loader's caches drop just the entries that carry the tag
-  for the unmounting layer.
-
-```mjs
-// inside /virtual/lib/greet.mjs after the VFS above is mounted
-console.log(import.meta.url);
-// e.g. 'file:///virtual/lib/greet.mjs?vfs-layer=0'
-```
+Module identity follows the path: `__filename`, `module.filename`,
+and `import.meta.url` are the plain absolute path (or `file:` URL) of
+the module under the mount point, with no synthetic decorations.
+Importing the same virtual path repeatedly — including through
+`import.meta.resolve()` — yields the same module instance, exactly as
+for real files.
 
-User code that compares `import.meta.url` literally should account
-for the search parameter; use `new URL(import.meta.url).pathname` or
-`fileURLToPath()` to obtain the underlying path.
+Calling [`vfs.unmount()`][] invalidates the modules that were loaded
+from the mount point: a subsequent `require()` or `import` of a path
+under a re-created mount re-reads the file from the newly mounted
+VFS rather than returning a stale module. Modules loaded from other
+VFS instances or from the real file system are unaffected.
 
 Mounting and unmounting do not invalidate ESM modules that are
 already executing. As with any other module-system teardown,
@@ -507,14 +496,13 @@ fields use synthetic but stable values:
 * Times default to the moment the entry was created/last modified.
 
 [Explicit Resource Management]: https://github.com/tc39/proposal-explicit-resource-management
-[Module loader integration]: #module-loader-integration
 [`MemoryProvider`]: #class-memoryprovider
 [`RealFSProvider`]: #class-realfsprovider
 [`VirtualFileSystem`]: #class-virtualfilesystem
 [`VirtualProvider`]: #class-virtualprovider
 [`fs.BigIntStats`]: fs.md#class-fsbigintstats
 [`fs.Stats`]: fs.md#class-fsstats
 [`node:fs`]: fs.md
-[`vfs.layerId`]: #vfslayerid
+[`os.devNull`]: os.md#osdevnull
 [`vfs.mount(prefix)`]: #vfsmountprefix
 [`vfs.unmount()`]: #vfsunmount

lib/fs.js

@@ -2044,8 +2044,13 @@ function fstatSync(fd, options = { __proto__: null, bigint: false }) {
 function lstatSync(path, options = { __proto__: null, bigint: false, throwIfNoEntry: true }) {
   const h = vfsState.handlers;
   if (h !== null) {
-    const result = h.lstatSync(path, options);
-    if (result !== undefined) return result;
+    try {
+      const result = h.lstatSync(path, options);
+      if (result !== undefined) return result;
+    } catch (err) {
+      if (err?.code === 'ENOENT' && options?.throwIfNoEntry === false) return;
+      throw err;
+    }
   }
   path = getValidatedPath(path);
   if (permission.isEnabled() && !permission.has('fs.read', path)) {
@@ -2078,8 +2083,13 @@ function lstatSync(path, options = { __proto__: null, bigint: false, throwIfNoEn
 function statSync(path, options = { __proto__: null, bigint: false, throwIfNoEntry: true }) {
   const h = vfsState.handlers;
   if (h !== null) {
-    const result = h.statSync(path, options);
-    if (result !== undefined) return result;
+    try {
+      const result = h.statSync(path, options);
+      if (result !== undefined) return result;
+    } catch (err) {
+      if (err?.code === 'ENOENT' && options?.throwIfNoEntry === false) return undefined;
+      throw err;
+    }
   }
   const stats = binding.stat(
     getValidatedPath(path),