vfs: clarify name resolution and add fs benchmark

Rename `followLast` to `followLink` and document it as the difference
between `stat()` and `lstat()`. Use `path.join()` for the mount name
prefixes purged on register and deregister, and explain why the hot
path in `resolveVFS()` concatenates instead.

Add a benchmark for the cost of the fs hooks on a real path and on a
layer path reached by id or by mount name. On Windows x64 (Release,
three runs of `statSync`, n=100000):

                                     ops/s
  vfs/fs-resolve.js target=real  80,929  82,063  82,618
  vfs/fs-resolve.js target=id    67,669  66,850  63,834
  vfs/fs-resolve.js target=name  65,911  64,155  60,767

Resolving through a mount name costs about 4% over resolving by id.

Against the merge base (dd5dfb5), with 30 interleaved runs each
and a Welch t-test, there is no significant difference:

               main ops/s  this ops/s  change  95% CI            p
  target=id        67,837      67,532  -0.45%  [-1.69%, +0.79%]  0.47
  target=real      81,951      80,991  -1.17%  [-5.91%, +3.57%]  0.62

Main has no mount names, so `target=name` has no baseline.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: pipobscure

benchmark/vfs/fs-resolve.js

@@ -0,0 +1,32 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const common = require('../common.js');
+
+// Measures what the fs hooks cost a call once a VFS is mounted: a real path
+// only has to be told apart from the VFS root, while a path in a layer is
+// resolved to the layer, either by its id or through its mount name.
+const bench = common.createBenchmark(main, {
+  target: ['real', 'id', 'name'],
+  n: [1e5],
+}, { flags: ['--experimental-vfs', '--no-warnings'] });
+
+function main({ n, target }) {
+  const vfs = require('node:vfs');
+  const layer = vfs.create();
+  layer.mkdirSync('/dir');
+  layer.writeFileSync('/dir/file.txt', 'x');
+  const mountPoint = layer.mount('bench');
+  const file = {
+    real: __filename,
+    id: path.join(mountPoint, 'dir', 'file.txt'),
+    name: path.join(path.dirname(mountPoint), 'bench', 'dir', 'file.txt'),
+  }[target];
+
+  bench.start();
+  for (let i = 0; i < n; i++) {
+    fs.statSync(file);
+  }
+  bench.end(n);
+  layer.unmount();
+}

lib/internal/vfs/setup.js

@@ -118,7 +118,7 @@ function registerVFS(vfs, name) {
   if (name !== undefined) {
     // What was loaded through the name came from the layer it linked to.
     if (activeNames.has(name)) {
-      purgeLoaderCachesForPrefix(getVfsRoot() + sep + name);
+      purgeLoaderCachesForPrefix(join(getVfsRoot(), name));
     }
     activeNames.set(name, vfs[kLayerId]);
   }
@@ -134,7 +134,7 @@ function deregisterVFS(vfs) {
   MapPrototypeForEach(activeNames, (target, name) => {
     if (target === layerId) {
       activeNames.delete(name);
-      purgeLoaderCachesForPrefix(getVfsRoot() + sep + name);
+      purgeLoaderCachesForPrefix(join(getVfsRoot(), name));
     }
   });
   purgeLoaderCachesForPrefix(vfs.mountPoint);
@@ -153,10 +153,14 @@ function deregisterVFS(vfs) {
  *
  * A mount name is a symbolic link to its layer, so a path that starts with
  * one is rewritten to start with the layer's mount point instead, and
- * `path` is what the layer must be handed. With `followLast` false, a path
- * that is the name itself is not followed, for the operations that act on
- * a link rather than on its target. `mountPoint` is the layer's mount point
- * as the input spells it, by name or by id.
+ * `path` is what the layer must be handed. `followLink` is the difference
+ * between stat() and lstat(): a name in the middle of a path is always
+ * followed, but a path that is the name itself is only followed when
+ * `followLink` is true. The operations that act on a link rather than on its
+ * target (lstat, readlink, unlink, rename, ...) pass false, so that they see
+ * the name as a symbolic link, not as the layer's root directory.
+ * `mountPoint` is the layer's mount point as the input spells it, by name or
+ * by id.
  *
  * A path under the root that no layer serves comes back with `vfs: null`
  * rather than as `null`, because the two cases must not be treated alike
@@ -170,15 +174,16 @@ function deregisterVFS(vfs) {
  * it rejects the empty device as an invalid package.json, so the loader
  * must answer for the whole root.
  * @param {string} inputPath
- * @param {boolean} [followLast]
+ * @param {boolean} [followLink] Whether a path that is a mount name
+ *   resolves to its layer; false to act on the name's link itself.
  * @returns {{
  *   vfs: object|null,
  *   path: string,
  *   normalized: string,
  *   mountPoint: string|null,
  * }|null}
  */
-function resolveVFS(inputPath, followLast = true) {
+function resolveVFS(inputPath, followLink = true) {
   const normalized = normalizeMountedPath(inputPath);
   if (normalized !== normalizedVfsRoot &&
       !StringPrototypeStartsWith(normalized, normalizedVfsRootPrefix)) {
@@ -192,9 +197,12 @@ function resolveVFS(inputPath, followLast = true) {
     if (vfs !== undefined && vfs.shouldHandleNormalized(normalized)) {
       return { vfs, path: inputPath, normalized, mountPoint: vfs.mountPoint };
     }
-  } else if (followLast || end < normalized.length) {
+  } else if (followLink || end < normalized.length) {
     const layerId = activeNames.get(segment);
     if (layerId !== undefined) {
+      // This runs for every fs call through a name, so the paths are
+      // concatenated rather than joined: the root is already normalized and
+      // `segment` is a single segment, so there is nothing to normalize.
       const path = normalizedVfsRootPrefix + layerId +
         StringPrototypeSlice(normalized, end);
       return {
@@ -214,11 +222,11 @@ function resolveVFS(inputPath, followLast = true) {
  * fs functions see the root as a directory, so a path under the root that
  * no layer serves is the root file system's to answer.
  * @param {string} inputPath
- * @param {boolean} [followLast]
+ * @param {boolean} [followLink] See `resolveVFS()`.
  * @returns {{ vfs: object, path: string }|null}
  */
-function findVFS(inputPath, followLast) {
-  const r = resolveVFS(inputPath, followLast);
+function findVFS(inputPath, followLink) {
+  const r = resolveVFS(inputPath, followLink);
   if (r === null) return null;
   if (r.vfs === null) r.vfs = rootVFS;
   return r;
@@ -388,28 +396,28 @@ function vfsRead(path, syscall, fn) {
   return findVFSWith(pathStr, syscall, fn);
 }
 
-function vfsOp(path, fn, followLast) {
+function vfsOp(path, fn, followLink) {
   const pathStr = toPathStr(path);
   if (pathStr !== null) {
-    const r = findVFS(pathStr, followLast);
+    const r = findVFS(pathStr, followLink);
     if (r !== null) return fn(r.vfs, r.path);
   }
   return undefined;
 }
 
-function vfsOpVoid(path, fn, followLast) {
+function vfsOpVoid(path, fn, followLink) {
   const pathStr = toPathStr(path);
   if (pathStr !== null) {
-    const r = findVFS(pathStr, followLast);
+    const r = findVFS(pathStr, followLink);
     if (r !== null) { fn(r.vfs, r.path); return true; }
   }
   return undefined;
 }
 
 // Returns the path to hand `srcVfs` for `destPath`, which must be served by
 // the same VFS as the source.
-function findSameVFS(srcPath, destPath, syscall, srcVfs, followLast) {
-  const r = findVFS(destPath, followLast);
+function findSameVFS(srcPath, destPath, syscall, srcVfs, followLink) {
+  const r = findVFS(destPath, followLink);
   if (r?.vfs !== srcVfs) {
     throw createEXDEV(syscall, srcPath);
   }