vfs: assign a monotonic layer id to each instance

Each VirtualFileSystem now exposes a per-process monotonically
increasing `layerId`, assigned at construction. The id is stable
across mount/unmount cycles for the lifetime of the instance and
surfaces in:

- debug() output for register / deregister so the layer stack is
  visible when NODE_DEBUG=vfs is enabled;
- the overlap ERR_INVALID_STATE message, which now names the layer
  ids of the conflicting mounts.

The id is the building block for tagging cache entries with the
owning VFS, which a follow-up will use to replace the global
loader-cache flush in deregisterVFS with a scoped purge.

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

Author: mcollina

lib/internal/vfs/file_system.js

@@ -43,6 +43,13 @@ const kProvider = Symbol('kProvider');
 const kMountPoint = Symbol('kMountPoint');
 const kMounted = Symbol('kMounted');
 const kPromises = Symbol('kPromises');
+const kLayerId = Symbol('kLayerId');
+
+// Per-process monotonically increasing counter that gives each
+// VirtualFileSystem instance a unique, stable id. Useful for ordering
+// mounted layers in debug output and disambiguating instances in error
+// messages.
+let nextLayerId = 0;
 
 // Lazy-loaded VFS setup
 let registerVFS;
@@ -94,6 +101,17 @@ class VirtualFileSystem {
     this[kMountPoint] = null;
     this[kMounted] = false;
     this[kPromises] = null; // Lazy-initialized
+    this[kLayerId] = nextLayerId++;
+  }
+
+  /**
+   * Per-process monotonically increasing identifier assigned to this
+   * VFS instance at construction. Stable across mount/unmount cycles
+   * for the lifetime of the instance.
+   * @returns {number}
+   */
+  get layerId() {
+    return this[kLayerId];
   }
 
   /**

lib/internal/vfs/setup.js

@@ -71,7 +71,8 @@ function registerVFS(vfs) {
   const newMount = vfs.mountPoint;
   if (newMount != null) {
     for (let i = 0; i < activeVFSList.length; i++) {
-      const existingMount = activeVFSList[i].mountPoint;
+      const existing = activeVFSList[i];
+      const existingMount = existing.mountPoint;
       if (existingMount == null) continue;
       // Use path.sep so the trailing-separator guard works on Windows where
       // mountPoint values are resolved to drive-letter / backslash paths.
@@ -81,13 +82,15 @@ function registerVFS(vfs) {
           StringPrototypeStartsWith(newMount, existingPrefix) ||
           StringPrototypeStartsWith(existingMount, newPrefix)) {
         throw new ERR_INVALID_STATE(
-          `VFS mount '${newMount}' overlaps with existing mount '${existingMount}'`,
+          `VFS mount '${newMount}' (layer ${vfs.layerId}) overlaps with ` +
+          `existing mount '${existingMount}' (layer ${existing.layerId})`,
         );
       }
     }
   }
   ArrayPrototypePush(activeVFSList, vfs);
-  debug('register mount=%s active=%d', newMount, activeVFSList.length);
+  debug('register layer=%d mount=%s active=%d',
+        vfs.layerId, newMount, activeVFSList.length);
   if (!hooksInstalled) {
     installHooks();
   }
@@ -97,7 +100,7 @@ function deregisterVFS(vfs) {
   const index = ArrayPrototypeIndexOf(activeVFSList, vfs);
   if (index === -1) return;
   ArrayPrototypeSplice(activeVFSList, index, 1);
-  debug('deregister active=%d', activeVFSList.length);
+  debug('deregister layer=%d active=%d', vfs.layerId, activeVFSList.length);
   // Loader/path caches are shared across all VFSes and we can't tell
   // which entries belonged to the one going away, so flush them on
   // every unmount. The cost is bounded; correctness wins.

test/parallel/test-vfs-layer-id.js

@@ -0,0 +1,43 @@
+// Flags: --experimental-vfs
+'use strict';
+
+// `vfs.layerId` is a per-process monotonically increasing identifier
+// assigned at construction. It is stable across mount/unmount cycles
+// and surfaces in overlap error messages.
+
+require('../common');
+const assert = require('assert');
+const vfs = require('node:vfs');
+
+{
+  const a = vfs.create();
+  const b = vfs.create();
+  const c = vfs.create();
+  assert.strictEqual(typeof a.layerId, 'number');
+  assert.ok(b.layerId > a.layerId);
+  assert.ok(c.layerId > b.layerId);
+  // Stable across mount/unmount.
+  const idBefore = a.layerId;
+  a.mount('/mnt-layer-stable');
+  assert.strictEqual(a.layerId, idBefore);
+  a.unmount();
+  assert.strictEqual(a.layerId, idBefore);
+}
+
+// layerId appears in the overlap error message so the user can tell
+// which instance lost the race.
+{
+  const outer = vfs.create();
+  const inner = vfs.create();
+  outer.mount('/mnt-layer-overlap');
+  assert.throws(
+    () => inner.mount('/mnt-layer-overlap/sub'),
+    (err) => {
+      assert.strictEqual(err.code, 'ERR_INVALID_STATE');
+      assert.match(err.message, new RegExp(`layer ${inner.layerId}`));
+      assert.match(err.message, new RegExp(`layer ${outer.layerId}`));
+      return true;
+    },
+  );
+  outer.unmount();
+}