vfs: scope-purge loader caches on deregister

Replace the global loader-cache flush in deregisterVFS with a
scope-purge that only drops entries owned by the unmounting VFS.
Per-layer ownership is determined two ways:

- For CJS-style filename-keyed caches (Module._cache,
  Module._pathCache, the CJS stat cache, the helpers.js realpath
  cache, and the package.json caches) entries are filtered with
  `vfs.shouldHandle(filename)`. __filename stays a clean absolute
  path so user code that does `path.dirname(__filename)` or similar
  is unaffected.

- For the ESM cascaded loader's loadCache, entries are tagged at
  resolve time: when finalizeResolution() detects the resolved
  path is VFS-owned (via the new loaderGetLayerForPath hook), it
  appends `?vfs-layer=<id>` to the URL. The tag surfaces in
  `import.meta.url`, matching the cache-busting pattern used by
  HMR tooling. On deregister, entries whose URL carries the tag
  for the unmounting layer are deleted.

Multi-mount setups no longer pay the cross-VFS cache-warmup
penalty when a single VFS unmounts, and ESM modules loaded from a
VFS become reachable for purge instead of leaking forever in the
cascaded loader.

New helpers exposed for VFS:
- cjs/loader.js: clearStatCacheForVFS
- helpers.js: purgeRealpathCacheForVFS, loaderGetLayerForPath
- package_json_reader.js: purgePackageJSONCacheForVFS

Adds test-vfs-scoped-cache-purge covering both the multi-mount
isolation and the import.meta.url tag visibility.

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

Author: mcollina

lib/internal/modules/cjs/loader.js

@@ -114,6 +114,7 @@ const kFormat = Symbol('kFormat');
 // Set first due to cycle with ESM loader functions.
 module.exports = {
   clearStatCache,
+  clearStatCacheForVFS,
   kModuleSource,
   kModuleExport,
   kModuleExportNames,
@@ -291,6 +292,22 @@ function clearStatCache() {
   }
 }
 
+/**
+ * Drop only the stat-cache entries owned by the given VFS instance.
+ * Real-fs entries and entries owned by other VFSes are untouched.
+ * @param {{shouldHandle: (path: string) => boolean}} vfs
+ */
+function clearStatCacheForVFS(vfs) {
+  if (statCache === null) {
+    return;
+  }
+  for (const filename of statCache.keys()) {
+    if (vfs.shouldHandle(filename)) {
+      statCache.delete(filename);
+    }
+  }
+}
+
 let _stat = stat;
 ObjectDefineProperty(Module, '_stat', {
   __proto__: null,

lib/internal/modules/esm/resolve.js

@@ -45,7 +45,12 @@ const {
 const { defaultGetFormatWithoutErrors } = require('internal/modules/esm/get_format');
 const { getConditionsSet } = require('internal/modules/esm/utils');
 const packageJsonReader = require('internal/modules/package_json_reader');
-const { loaderLegacyMainResolve, loaderStat, toRealPath } = require('internal/modules/helpers');
+const {
+  loaderGetLayerForPath,
+  loaderLegacyMainResolve,
+  loaderStat,
+  toRealPath,
+} = require('internal/modules/helpers');
 
 /**
  * @typedef {import('internal/modules/esm/package_config.js').PackageConfig} PackageConfig
@@ -281,6 +286,21 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
     resolved.hash = hash;
   }
 
+  // If the resolved path is owned by an installed VFS layer, append a
+  // `vfs-layer=N` search param so cache entries are tagged with the
+  // owning layer. On deregister, entries matching the unmounted layer
+  // can be scope-purged without touching unrelated real-fs imports.
+  // The tag is surfaced in `import.meta.url`, matching the
+  // cache-busting pattern used by HMR tooling.
+  const layerId = loaderGetLayerForPath(path);
+  if (layerId !== undefined) {
+    if (resolved.search) {
+      resolved.search += `&vfs-layer=${layerId}`;
+    } else {
+      resolved.search = `?vfs-layer=${layerId}`;
+    }
+  }
+
   return resolved;
 }
 

lib/internal/modules/helpers.js

@@ -65,6 +65,7 @@ let _loaderReadFile = null;
 let _loaderRealpath = null;
 let _loaderLegacyMainResolve = null;
 let _loaderGetFormatOfExtensionlessFile = null;
+let _loaderGetLayerForPath = null;
 
 /**
  * Set override functions for the module loader's fs operations.
@@ -78,6 +79,22 @@ function setLoaderFsOverrides(overrides = kEmptyObject) {
   _loaderRealpath = overrides.realpath ?? null;
   _loaderLegacyMainResolve = overrides.legacyMainResolve ?? null;
   _loaderGetFormatOfExtensionlessFile = overrides.getFormatOfExtensionlessFile ?? null;
+  _loaderGetLayerForPath = overrides.getLayerForPath ?? null;
+}
+
+/**
+ * If `filename` is owned by an installed VFS layer, returns that layer's
+ * monotonically increasing id; otherwise returns `undefined`. Used by the
+ * ESM resolver to tag resolved URLs so cache entries can be scope-purged
+ * on VFS deregister without touching unrelated real-fs imports.
+ * @param {string} filename Absolute path
+ * @returns {number|undefined}
+ */
+function loaderGetLayerForPath(filename) {
+  if (_loaderGetLayerForPath !== null) {
+    return _loaderGetLayerForPath(filename);
+  }
+  return undefined;
 }
 
 /**
@@ -179,6 +196,19 @@ function clearRealpathCache() {
   realpathCache.clear();
 }
 
+/**
+ * Drop only realpath-cache entries owned by the given VFS instance.
+ * Entries for unrelated paths are untouched.
+ * @param {{shouldHandle: (path: string) => boolean}} vfs
+ */
+function purgeRealpathCacheForVFS(vfs) {
+  for (const key of realpathCache.keys()) {
+    if (vfs.shouldHandle(key)) {
+      realpathCache.delete(key);
+    }
+  }
+}
+
 /**
  * Wrapper for modulesBinding.readPackageJSON that supports VFS toggle.
  * @param {string} jsonPath
@@ -680,6 +710,7 @@ module.exports = {
   addBuiltinLibsToObject,
   assertBufferSource,
   clearRealpathCache,
+  purgeRealpathCacheForVFS,
   constants,
   enableCompileCache,
   flushCompileCache,
@@ -689,6 +720,7 @@ module.exports = {
   getCompileCacheDir,
   initializeCjsConditions,
   loaderGetFormatOfExtensionlessFile,
+  loaderGetLayerForPath,
   loaderGetNearestParentPackageJSON,
   loaderGetPackageScopeConfig,
   loaderGetPackageType,

lib/internal/modules/package_json_reader.js

@@ -367,6 +367,24 @@ function clearPackageJSONCache() {
   deserializedPackageJSONCache.clear();
 }
 
+/**
+ * Drop only package.json-cache entries owned by the given VFS instance.
+ * Real-fs entries and other-VFS entries are untouched.
+ * @param {{shouldHandle: (path: string) => boolean}} vfs
+ */
+function purgePackageJSONCacheForVFS(vfs) {
+  for (const key of moduleToParentPackageJSONCache.keys()) {
+    if (vfs.shouldHandle(key)) {
+      moduleToParentPackageJSONCache.delete(key);
+    }
+  }
+  for (const key of deserializedPackageJSONCache.keys()) {
+    if (typeof key === 'string' && vfs.shouldHandle(key)) {
+      deserializedPackageJSONCache.delete(key);
+    }
+  }
+}
+
 module.exports = {
   read,
   getNearestParentPackageJSON,
@@ -375,4 +393,5 @@ module.exports = {
   getPackageJSONURL,
   findPackageJSON,
   clearPackageJSONCache,
+  purgePackageJSONCacheForVFS,
 };

lib/internal/vfs/setup.js

@@ -7,9 +7,11 @@ const {
   ArrayPrototypeSplice,
   JSONParse,
   JSONStringify,
+  ObjectKeys,
   PromiseResolve,
   String,
   StringPrototypeEndsWith,
+  StringPrototypeIncludes,
   StringPrototypeStartsWith,
 } = primordials;
 
@@ -101,34 +103,101 @@ function deregisterVFS(vfs) {
   if (index === -1) return;
   ArrayPrototypeSplice(activeVFSList, index, 1);
   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.
-  clearLoaderCaches();
+  // Scope-purge: only drop loader-cache entries that belong to the VFS
+  // that is going away. Other VFSes and real-fs imports are untouched.
+  purgeLoaderCachesForVFS(vfs);
   if (activeVFSList.length === 0) {
     uninstallHooks();
   }
 }
 
 /**
- * Clear every JS-reachable loader cache that could hold a VFS-resolved
- * entry. Called from deregisterVFS only when the last VFS unmounts.
+ * Returns true if `cjsFilename` is a path that `vfs` claims via
+ * `shouldHandle()`. Used to filter CJS cache entries on deregister.
+ * @param {object} vfs
+ * @param {string} cjsFilename
+ * @returns {boolean}
  */
-function clearLoaderCaches() {
+function isOwnedByVFS(vfs, cjsFilename) {
+  if (typeof cjsFilename !== 'string') return false;
+  try {
+    return vfs.shouldHandle(resolve(cjsFilename));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if `url` carries the `vfs-layer=<layerId>` tag emitted by
+ * esm/resolve.js for the given VFS layer. Used to filter ESM cache
+ * entries on deregister.
+ * @param {string} url
+ * @param {number} layerId
+ * @returns {boolean}
+ */
+function urlBelongsToLayer(url, layerId) {
+  if (typeof url !== 'string') return false;
+  return StringPrototypeIncludes(url, `vfs-layer=${layerId}`);
+}
+
+/**
+ * Drop the cache entries owned by `vfs` from the JS-reachable loader
+ * caches. Real-fs entries and other-VFS entries are left in place.
+ * @param {object} vfs The VFS being deregistered
+ */
+function purgeLoaderCachesForVFS(vfs) {
+  const layerId = vfs.layerId;
+
+  // CJS module cache, keyed by absolute filename.
   const cjsLoader = require('internal/modules/cjs/loader');
-  cjsLoader.Module._pathCache = { __proto__: null };
-  cjsLoader.clearStatCache();
+  const moduleCache = cjsLoader.Module._cache;
+  for (const filename of ObjectKeys(moduleCache)) {
+    if (isOwnedByVFS(vfs, filename)) {
+      delete moduleCache[filename];
+    }
+  }
+
+  // CJS path cache: keyed by request + parent paths string. The
+  // cached value is the resolved filename, so filter on that.
+  const pathCache = cjsLoader.Module._pathCache;
+  for (const key of ObjectKeys(pathCache)) {
+    if (isOwnedByVFS(vfs, pathCache[key])) {
+      delete pathCache[key];
+    }
+  }
+
+  // CJS stat cache: keys are absolute filenames.
+  cjsLoader.clearStatCacheForVFS(vfs);
+
+  // Realpath cache used by helpers.toRealPath: keys are absolute paths.
   const helpers = require('internal/modules/helpers');
-  helpers.clearRealpathCache();
-  const { clearPackageJSONCache } = require('internal/modules/package_json_reader');
-  clearPackageJSONCache();
-  // The ESM cascaded loader's loadCache is intentionally NOT cleared here:
-  // clearing it mid-flight (while another import() is awaiting nested
-  // resolution) would let a second ModuleJob be created for the same URL,
-  // breaking module identity. The trade-off is that an ESM module already
-  // loaded from a VFS path remains cached after unmount and across a
-  // re-mount with different content, consistent with how ESM caches
-  // modules everywhere else in Node.js.
+  helpers.purgeRealpathCacheForVFS(vfs);
+
+  // package.json caches: keyed by absolute path.
+  const pkgReader = require('internal/modules/package_json_reader');
+  pkgReader.purgePackageJSONCacheForVFS(vfs);
+
+  // ESM cascaded loader: scope-purge by URL tag.
+  const esmLoader = require('internal/modules/esm/loader');
+  if (esmLoader.isCascadedLoaderInitialized()) {
+    const loader = esmLoader.getOrInitializeCascadedLoader();
+    const loadCache = loader.loadCache;
+    // LoadCache extends SafeMap (url -> { [type]: job }). We iterate
+    // keys() and delete entries whose URL carries this layer's tag.
+    if (loadCache && typeof loadCache.delete === 'function') {
+      for (const url of loadCache.keys()) {
+        if (urlBelongsToLayer(url, layerId)) {
+          // Drop every type variant for this URL.
+          const variants = loadCache.get(url);
+          if (variants) {
+            for (const type of ObjectKeys(variants)) {
+              loadCache.delete(url, type);
+            }
+          }
+        }
+      }
+    }
+  }
 }
 
 /**
@@ -934,6 +1003,14 @@ function installModuleLoaderOverrides() {
       }
       return 0; // EXTENSIONLESS_FORMAT_JAVASCRIPT
     },
+    getLayerForPath(filename) {
+      const normalized = resolve(filename);
+      for (let i = 0; i < activeVFSList.length; i++) {
+        const vfs = activeVFSList[i];
+        if (vfs.shouldHandle(normalized)) return vfs.layerId;
+      }
+      return undefined;
+    },
   });
 
   setLoaderPackageOverrides({

test/parallel/test-vfs-scoped-cache-purge.js

@@ -0,0 +1,55 @@
+// Flags: --experimental-vfs
+'use strict';
+
+// Deregistering one of several mounted VFSes must scope-purge the
+// loader caches: entries that belong to the VFS going away are
+// dropped, entries from other VFSes are kept warm. ESM cache entries
+// are tagged with `?vfs-layer=N` and surface in `import.meta.url`.
+
+const common = require('../common');
+const assert = require('assert');
+const vfs = require('node:vfs');
+
+// 1) Multi-mount: deregister of one VFS keeps the other's CJS module
+//    cache warm. The test relies on the require.cache being preserved.
+{
+  const a = vfs.create();
+  a.writeFileSync('/value.js', 'module.exports = "a-cached"');
+  a.mount('/mnt-purge-a');
+
+  const b = vfs.create();
+  b.writeFileSync('/value.js', 'module.exports = "b-cached"');
+  b.mount('/mnt-purge-b');
+
+  // Warm both caches.
+  assert.strictEqual(require('/mnt-purge-a/value.js'), 'a-cached');
+  assert.strictEqual(require('/mnt-purge-b/value.js'), 'b-cached');
+
+  const bKey = require.resolve('/mnt-purge-b/value.js');
+  assert.ok(bKey in require.cache, 'b should be cached before unmount');
+
+  // Unmount A. B's cache entry must survive.
+  a.unmount();
+  assert.ok(
+    bKey in require.cache,
+    'unmounting a different VFS must not evict b\'s cache entry',
+  );
+
+  // Re-require yields the same module instance (identity preserved).
+  assert.strictEqual(require('/mnt-purge-b/value.js'), 'b-cached');
+
+  b.unmount();
+}
+
+// 2) ESM URLs are tagged with `vfs-layer=<id>` and the tag surfaces in
+//    `import.meta.url`.
+(async () => {
+  const v = vfs.create();
+  v.writeFileSync('/m.mjs', 'export const url = import.meta.url;');
+  v.mount('/mnt-tag');
+
+  const ns = await import('/mnt-tag/m.mjs');
+  assert.match(ns.url, new RegExp(`vfs-layer=${v.layerId}`));
+
+  v.unmount();
+})().then(common.mustCall());