vfs: scope-purge loader caches via per-VFS owned-keys sets

Each VirtualFileSystem now tracks the absolute filenames it has
handled (ownedFilenames) and the Module._pathCache keys that resolve
to a VFS-owned filename (ownedPathCacheKeys). Recording happens at
routing time inside the loader overrides (findVFSForStat /
findVFSForRead / findVFSWith, the inline package.json override
loops, and a pathCache write recorder installed on the cjs loader).

On deregister, purgeLoaderCachesForVFS walks the per-VFS sets and
removes entries from Module._cache, Module._pathCache, the stat /
realpath / package.json caches in O(owned) instead of scanning every
cache and calling vfs.shouldHandle() on each entry. The pathCache
recorder uses a Set.has() lookup over activeVFSList so the per-write
overhead is M cheap Set checks rather than M path normalizations.

Also encapsulates the previous direct access to Module._cache /
Module._pathCache from internal/vfs/setup.js behind the cjs loader's
new purgeModuleCacheForVFS / setPathCacheWriteRecorder /
cachePathResolution helpers, so the loader's private data
structures stay owned by the loader module.

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

Author: mcollina

lib/internal/modules/cjs/loader.js

@@ -38,7 +38,6 @@ const {
   Error,
   FunctionPrototypeCall,
   JSONParse,
-  MapPrototypeForEach,
   ObjectDefineProperty,
   ObjectFreeze,
   ObjectGetOwnPropertyDescriptor,
@@ -53,6 +52,7 @@ const {
   RegExpPrototypeExec,
   SafeMap,
   SafeSet,
+  SetPrototypeForEach,
   String,
   StringPrototypeCharAt,
   StringPrototypeCharCodeAt,
@@ -116,6 +116,8 @@ const kFormat = Symbol('kFormat');
 module.exports = {
   clearStatCache,
   clearStatCacheForVFS,
+  purgeModuleCacheForVFS,
+  setPathCacheWriteRecorder,
   kModuleSource,
   kModuleExport,
   kModuleExportNames,
@@ -301,17 +303,73 @@ 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
+ * Iterates the per-VFS ownedFilenames set populated by the loader
+ * overrides at routing time - O(owned) rather than O(statCache).
+ * @param {{ownedFilenames: SafeSet<string>}} vfs
  */
 function clearStatCacheForVFS(vfs) {
-  if (statCache !== null) {
-    // MapPrototypeForEach (not for-of statCache.keys()) so a polluted
-    // Map iterator can't break this purge path.
-    MapPrototypeForEach(statCache, (_value, filename) => {
-      if (vfs.shouldHandle(filename)) {
-        statCache.delete(filename);
-      }
-    });
+  if (statCache === null) {
+    return;
+  }
+  // SafeSetIterator yields filenames; SafeSet's iteration helpers
+  // protect against pollution of the global Set prototype.
+  SetPrototypeForEach(vfs.ownedFilenames, (filename) => {
+    statCache.delete(filename);
+  });
+}
+
+/**
+ * Drop the module and path cache entries owned by the given VFS instance.
+ * Real-fs entries and entries owned by other VFSes are untouched. This
+ * keeps Module._cache / Module._pathCache encapsulated so callers don't
+ * reach into the loader's private data structures directly, and runs
+ * in O(owned) by walking the per-VFS sets populated at routing time.
+ * @param {{ownedFilenames: SafeSet<string>, ownedPathCacheKeys: SafeSet<string>}} vfs
+ */
+function purgeModuleCacheForVFS(vfs) {
+  // Module._cache: keyed by absolute filename. Iterate only the
+  // filenames the VFS handled rather than scanning the whole cache.
+  SetPrototypeForEach(vfs.ownedFilenames, (filename) => {
+    delete Module._cache[filename];
+  });
+
+  // Module._pathCache: keyed by "request\0parent" strings. The keys
+  // are recorded at write time via the pathCache write recorder
+  // installed by setup.js, so we iterate only the recorded keys.
+  SetPrototypeForEach(vfs.ownedPathCacheKeys, (key) => {
+    delete Module._pathCache[key];
+  });
+}
+
+/**
+ * Hook invoked whenever Module._pathCache is written. Allows the VFS
+ * layer to associate the new pathCache key with the VFS that owns the
+ * resolved filename, so on unmount the key can be removed by direct
+ * lookup instead of scanning the whole pathCache.
+ * @type {((cacheKey: string, resolvedFilename: string) => void) | null}
+ */
+let pathCacheWriteRecorder = null;
+
+/**
+ * Install (or clear) the pathCache write recorder. Called by
+ * internal/vfs/setup.js on hook install / uninstall.
+ * @param {((cacheKey: string, resolvedFilename: string) => void) | null} fn
+ */
+function setPathCacheWriteRecorder(fn) {
+  pathCacheWriteRecorder = fn ?? null;
+}
+
+/**
+ * Encapsulated writer for Module._pathCache. Goes through the recorder
+ * so external observers (currently: VFS scope-purge) can track which
+ * keys belong to which owner without exposing the cache itself.
+ * @param {string} cacheKey
+ * @param {string} resolvedFilename
+ */
+function cachePathResolution(cacheKey, resolvedFilename) {
+  Module._pathCache[cacheKey] = resolvedFilename;
+  if (pathCacheWriteRecorder !== null) {
+    pathCacheWriteRecorder(cacheKey, resolvedFilename);
   }
 }
 
@@ -906,7 +964,7 @@ Module._findPath = function(request, paths, isMain, conditions = getCjsCondition
     }
 
     if (filename) {
-      Module._pathCache[cacheKey] = filename;
+      cachePathResolution(cacheKey, filename);
       return filename;
     }
 
@@ -1586,7 +1644,7 @@ Module._resolveFilename = function(request, parent, isMain, options) {
   if (selfResolved) {
     const cacheKey = request + '\x00' +
          (paths.length === 1 ? paths[0] : ArrayPrototypeJoin(paths, '\x00'));
-    Module._pathCache[cacheKey] = selfResolved;
+    cachePathResolution(cacheKey, selfResolved);
     return selfResolved;
   }
 

lib/internal/modules/helpers.js

@@ -2,12 +2,12 @@
 
 const {
   ArrayPrototypeForEach,
-  MapPrototypeForEach,
   ObjectDefineProperty,
   ObjectFreeze,
   ObjectPrototypeHasOwnProperty,
   SafeMap,
   SafeSet,
+  SetPrototypeForEach,
   StringPrototypeCharCodeAt,
   StringPrototypeIncludes,
   StringPrototypeSlice,
@@ -199,16 +199,13 @@ function clearRealpathCache() {
 
 /**
  * Drop only realpath-cache entries owned by the given VFS instance.
- * Entries for unrelated paths are untouched.
- * @param {{shouldHandle: (path: string) => boolean}} vfs
+ * Entries for unrelated paths are untouched. Iterates the per-VFS
+ * ownedFilenames set rather than the whole realpath cache.
+ * @param {{ownedFilenames: SafeSet<string>}} vfs
  */
 function purgeRealpathCacheForVFS(vfs) {
-  // MapPrototypeForEach (not for-of realpathCache.keys()) so a polluted
-  // Map iterator can't break this purge path.
-  MapPrototypeForEach(realpathCache, (_value, key) => {
-    if (vfs.shouldHandle(key)) {
-      realpathCache.delete(key);
-    }
+  SetPrototypeForEach(vfs.ownedFilenames, (filename) => {
+    realpathCache.delete(filename);
   });
 }
 

lib/internal/modules/package_json_reader.js

@@ -3,10 +3,10 @@
 const {
   ArrayIsArray,
   JSONParse,
-  MapPrototypeForEach,
   ObjectDefineProperty,
   RegExpPrototypeExec,
   SafeMap,
+  SetPrototypeForEach,
   StringPrototypeIndexOf,
   StringPrototypeSlice,
 } = primordials;
@@ -370,21 +370,18 @@ function clearPackageJSONCache() {
 
 /**
  * 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
+ * Real-fs entries and other-VFS entries are untouched. Iterates the
+ * per-VFS ownedFilenames set (populated at routing time by the loader
+ * overrides) rather than scanning the global caches. The set is a
+ * superset of the VFS-owned keys, so the same iteration covers both
+ * the input-path cache and the package.json-path cache; misses are
+ * harmless `Map.delete` no-ops.
+ * @param {{ownedFilenames: SafeSet<string>}} vfs
  */
 function purgePackageJSONCacheForVFS(vfs) {
-  // MapPrototypeForEach (not for-of) so a polluted Map iterator can't
-  // break this purge path.
-  MapPrototypeForEach(moduleToParentPackageJSONCache, (_value, key) => {
-    if (vfs.shouldHandle(key)) {
-      moduleToParentPackageJSONCache.delete(key);
-    }
-  });
-  MapPrototypeForEach(deserializedPackageJSONCache, (_value, key) => {
-    if (typeof key === 'string' && vfs.shouldHandle(key)) {
-      deserializedPackageJSONCache.delete(key);
-    }
+  SetPrototypeForEach(vfs.ownedFilenames, (filename) => {
+    moduleToParentPackageJSONCache.delete(filename);
+    deserializedPackageJSONCache.delete(filename);
   });
 }
 

lib/internal/vfs/file_system.js

@@ -3,6 +3,7 @@
 const {
   MathRandom,
   ObjectFreeze,
+  SafeSet,
   Symbol,
   SymbolDispose,
 } = primordials;
@@ -44,6 +45,12 @@ const kMountPoint = Symbol('kMountPoint');
 const kMounted = Symbol('kMounted');
 const kPromises = Symbol('kPromises');
 const kLayerId = Symbol('kLayerId');
+// Per-VFS sets used by the loader to scope-purge module caches on unmount
+// without iterating every cached entry. Populated by the loader overrides
+// in internal/vfs/setup.js whenever a request is claimed by this VFS, and
+// cleared on unmount once the purge has run.
+const kOwnedFilenames = Symbol('kOwnedFilenames');
+const kOwnedPathCacheKeys = Symbol('kOwnedPathCacheKeys');
 
 // Per-process monotonically increasing counter that gives each
 // VirtualFileSystem instance a unique, stable id. Useful for ordering
@@ -115,6 +122,8 @@ class VirtualFileSystem {
     this[kMounted] = false;
     this[kPromises] = null; // Lazy-initialized
     this[kLayerId] = nextLayerId++;
+    this[kOwnedFilenames] = new SafeSet();
+    this[kOwnedPathCacheKeys] = new SafeSet();
   }
 
   /**
@@ -213,6 +222,55 @@ class VirtualFileSystem {
     return isUnderMountPoint(normalized, mountPoint);
   }
 
+  /**
+   * Record an absolute filename that the module loader routed through
+   * this VFS. The recorded paths are used on unmount to scope-purge
+   * per-filename loader caches (Module._cache, stat, realpath,
+   * package.json) without scanning the whole cache.
+   * @param {string} filename
+   */
+  recordOwnedFilename(filename) {
+    this[kOwnedFilenames].add(filename);
+  }
+
+  /**
+   * Record a Module._pathCache key whose resolved value points into
+   * this VFS. Used on unmount to scope-purge the path cache by stored
+   * key rather than scanning every entry.
+   * @param {string} key
+   */
+  recordOwnedPathCacheKey(key) {
+    this[kOwnedPathCacheKeys].add(key);
+  }
+
+  /**
+   * The set of filenames recorded via recordOwnedFilename. Returned
+   * directly (not copied) so callers can iterate with the primordials
+   * iterator helpers used in the loader's cache purge paths.
+   * @returns {SafeSet<string>}
+   */
+  get ownedFilenames() {
+    return this[kOwnedFilenames];
+  }
+
+  /**
+   * The set of Module._pathCache keys recorded via
+   * recordOwnedPathCacheKey.
+   * @returns {SafeSet<string>}
+   */
+  get ownedPathCacheKeys() {
+    return this[kOwnedPathCacheKeys];
+  }
+
+  /**
+   * Drop the per-VFS ownership tracking after the loader has used it
+   * to purge its caches on unmount.
+   */
+  clearOwnedKeys() {
+    this[kOwnedFilenames].clear();
+    this[kOwnedPathCacheKeys].clear();
+  }
+
   // ==================== Path Resolution ====================
 
   /**