module: refactor to use iterable-weak-map

Using an iterable WeakMap (a data-structure that uses WeakRef and
WeakMap), we are able to: stop relying on Module._cache to
serialize source maps; stop requiring an error object when calling
findSourceMap().

PR-URL: nodejs#35915
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>

Author: bcoe

doc/api/module.md

@@ -135,26 +135,22 @@ import { findSourceMap, SourceMap } from 'module';
 const { findSourceMap, SourceMap } = require('module');
 ```
 
-### `module.findSourceMap(path[, error])`
+<!-- Anchors to make sure old links find a target -->
+<a id="module_module_findsourcemap_path_error"></a>
+### `module.findSourceMap(path)`
+
 <!-- YAML
 added:
  - v13.7.0
  - v12.17.0
 -->
 
 * `path` {string}
-* `error` {Error}
 * Returns: {module.SourceMap}
 
 `path` is the resolved path for the file for which a corresponding source map
 should be fetched.
 
-The `error` instance should be passed as the second parameter to `findSourceMap`
-in exceptional flows, such as when an overridden
-[`Error.prepareStackTrace(error, trace)`][] is invoked. Modules are not added to
-the module cache until they are successfully loaded. In these cases, source maps
-are associated with the `error` instance along with the `path`.
-
 ### Class: `module.SourceMap`
 <!-- YAML
 added:
@@ -204,7 +200,6 @@ consists of the following keys:
 [ES Modules]: esm.md
 [Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
 [`--enable-source-maps`]: cli.md#cli_enable_source_maps
-[`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces
 [`NODE_V8_COVERAGE=dir`]: cli.md#cli_node_v8_coverage_dir
 [`SourceMap`]: #module_class_module_sourcemap
 [`createRequire()`]: #module_module_createrequire_filename

doc/api/modules.md

@@ -968,7 +968,7 @@ This section was moved to
 [Modules: `module` core module](module.md#module_source_map_v3_support).
 
 <!-- Anchors to make sure old links find a target -->
-* <a id="modules_module_findsourcemap_path_error" href="module.html#module_module_findsourcemap_path_error">`module.findSourceMap(path[, error])`</a>
+* <a id="modules_module_findsourcemap_path_error" href="module.html#module_module_findsourcemap_path">`module.findSourceMap(path)`</a>
 * <a id="modules_class_module_sourcemap" href="module.html#module_class_module_sourcemap">Class: `module.SourceMap`</a>
   * <a id="modules_new_sourcemap_payload" href="module.html#module_new_sourcemap_payload">`new SourceMap(payload)`</a>
   * <a id="modules_sourcemap_payload" href="module.html#module_sourcemap_payload">`sourceMap.payload`</a>

lib/internal/per_context/primordials.js

@@ -86,6 +86,7 @@ function makeSafe(unsafe, safe) {
   Object.freeze(safe);
   return safe;
 }
+primordials.makeSafe = makeSafe;
 
 // Subclass the constructors because we need to use their prototype
 // methods later.

lib/internal/source_map/prepare_stack_trace.js

@@ -52,7 +52,7 @@ const prepareStackTrace = (globalThis, error, trace) => {
     let str = i !== 0 ? '\n    at ' : '';
     str = `${str}${t}`;
     try {
-      const sm = findSourceMap(t.getFileName(), error);
+      const sm = findSourceMap(t.getFileName());
       if (sm) {
         // Source Map V3 lines/columns use zero-based offsets whereas, in
         // stack traces, they start at 1/1.
@@ -91,11 +91,21 @@ const prepareStackTrace = (globalThis, error, trace) => {
 function getErrorSource(firstSource, firstLine, firstColumn) {
   let exceptionLine = '';
   let source;
-  try {
-    source = readFileSync(firstSource, 'utf8');
-  } catch (err) {
-    debug(err);
-    return exceptionLine;
+  const sourceContentIndex =
+    ArrayPrototypeIndexOf(payload.sources, originalSource);
+  if (payload.sourcesContent?.[sourceContentIndex]) {
+    // First we check if the original source content was provided in the
+    // source map itself:
+    source = payload.sourcesContent[sourceContentIndex];
+  } else {
+    // If no sourcesContent was found, attempt to load the original source
+    // from disk:
+    try {
+      source = readFileSync(originalSourceNoScheme, 'utf8');
+    } catch (err) {
+      debug(err);
+      return '';
+    }
   }
   const lines = source.split(/\r?\n/, firstLine);
   const line = lines[firstLine - 1];

lib/internal/source_map/source_map_cache.js

@@ -1,15 +1,18 @@
 'use strict';
 
 const {
+  ArrayPrototypeMap,
   JSONParse,
   ObjectCreate,
   ObjectKeys,
   ObjectGetOwnPropertyDescriptor,
   ObjectPrototypeHasOwnProperty,
   Map,
   MapPrototypeEntries,
-  WeakMap,
-  WeakMapPrototypeGet,
+  RegExpPrototypeTest,
+  SafeMap,
+  StringPrototypeMatch,
+  StringPrototypeSplit,
   uncurryThis,
 } = primordials;
 
@@ -28,17 +31,17 @@ let debug = require('internal/util/debuglog').debuglog('source_map', (fn) => {
 const { dirname, resolve } = require('path');
 const fs = require('fs');
 const { getOptionValue } = require('internal/options');
+const { IterableWeakMap } = require('internal/util/iterable_weak_map');
 const {
   normalizeReferrerURL,
 } = require('internal/modules/cjs/helpers');
-// For cjs, since Module._cache is exposed to users, we use a WeakMap
-// keyed on module, facilitating garbage collection.
-const cjsSourceMapCache = new WeakMap();
-// The esm cache is not exposed to users, so we can use a Map keyed
-// on filenames.
-const esmSourceMapCache = new Map();
-const { fileURLToPath, URL } = require('url');
-let Module;
+// Since the CJS module cache is mutable, which leads to memory leaks when
+// modules are deleted, we use a WeakMap so that the source map cache will
+// be purged automatically:
+const cjsSourceMapCache = new IterableWeakMap();
+// The esm cache is not mutable, so we can use a Map without memory concerns:
+const esmSourceMapCache = new SafeMap();
+const { fileURLToPath, pathToFileURL, URL } = require('internal/url');
 let SourceMap;
 
 let sourceMapsEnabled;
@@ -73,13 +76,14 @@ function maybeCacheSourceMap(filename, content, cjsModuleInstance) {
     debug(err.stack);
     return;
   }
-
-  const match = content.match(/\/[*/]#\s+sourceMappingURL=(?<sourceMappingURL>[^\s]+)/);
+  const match = StringPrototypeMatch(
+    content,
+    /\/[*/]#\s+sourceMappingURL=(?<sourceMappingURL>[^\s]+)/
+  );
   if (match) {
     const data = dataFromUrl(basePath, match.groups.sourceMappingURL);
     const url = data ? null : match.groups.sourceMappingURL;
     if (cjsModuleInstance) {
-      if (!Module) Module = require('internal/modules/cjs/loader').Module;
       cjsSourceMapCache.set(cjsModuleInstance, {
         filename,
         lineLengths: lineLengths(content),
@@ -123,7 +127,7 @@ function lineLengths(content) {
   // We purposefully keep \r as part of the line-length calculation, in
   // cases where there is a \r\n separator, so that this can be taken into
   // account in coverage calculations.
-  return content.split(/\n|\u2028|\u2029/).map((line) => {
+  return ArrayPrototypeMap(StringPrototypeSplit(content, /\n|\u2028|\u2029/), (line) => {
     return line.length;
   });
 }
@@ -141,9 +145,9 @@ function sourceMapFromFile(sourceMapFile) {
 
 // data:[<mediatype>][;base64],<data> see:
 // https://tools.ietf.org/html/rfc2397#section-2
-function sourceMapFromDataUrl(basePath, url) {
-  const [format, data] = url.split(',');
-  const splitFormat = format.split(';');
+function sourceMapFromDataUrl(sourceURL, url) {
+  const [format, data] = StringPrototypeSplit(url, ',');
+  const splitFormat = StringPrototypeSplit(format, ';');
   const contentType = splitFormat[0];
   const base64 = splitFormat[splitFormat.length - 1] === 'base64';
   if (contentType === 'application/json') {
@@ -214,48 +218,32 @@ function sourceMapCacheToObject() {
   return obj;
 }
 
-// Since WeakMap can't be iterated over, we use Module._cache's
-// keys to facilitate Source Map serialization.
-//
-// TODO(bcoe): this means we don't currently serialize source-maps attached
-// to error instances, only module instances.
 function appendCJSCache(obj) {
-  if (!Module) return;
-  const cjsModuleCache = ObjectGetValueSafe(Module, '_cache');
-  const cjsModules = ObjectKeys(cjsModuleCache);
-  for (let i = 0; i < cjsModules.length; i++) {
-    const key = cjsModules[i];
-    const module = ObjectGetValueSafe(cjsModuleCache, key);
-    const value = WeakMapPrototypeGet(cjsSourceMapCache, module);
-    if (value) {
-      // This is okay because `obj` has a null prototype.
-      obj[`file://${key}`] = {
-        lineLengths: ObjectGetValueSafe(value, 'lineLengths'),
-        data: ObjectGetValueSafe(value, 'data'),
-        url: ObjectGetValueSafe(value, 'url')
-      };
-    }
+  for (const value of cjsSourceMapCache) {
+    obj[ObjectGetValueSafe(value, 'filename')] = {
+      lineLengths: ObjectGetValueSafe(value, 'lineLengths'),
+      data: ObjectGetValueSafe(value, 'data'),
+      url: ObjectGetValueSafe(value, 'url')
+    };
   }
 }
 
-// Attempt to lookup a source map, which is either attached to a file URI, or
-// keyed on an error instance.
-// TODO(bcoe): once WeakRefs are available in Node.js, refactor to drop
-// requirement of error parameter.
-function findSourceMap(uri, error) {
-  if (!Module) Module = require('internal/modules/cjs/loader').Module;
+function findSourceMap(sourceURL) {
+  if (!RegExpPrototypeTest(/^\w+:\/\//, sourceURL)) {
+    sourceURL = pathToFileURL(sourceURL).href;
+  }
   if (!SourceMap) {
     SourceMap = require('internal/source_map/source_map').SourceMap;
   }
-  let sourceMap = cjsSourceMapCache.get(Module._cache[uri]);
-  if (!uri.startsWith('file://')) uri = normalizeReferrerURL(uri);
-  if (sourceMap === undefined) {
-    sourceMap = esmSourceMapCache.get(uri);
-  }
+  let sourceMap = esmSourceMapCache.get(sourceURL);
   if (sourceMap === undefined) {
-    const candidateSourceMap = cjsSourceMapCache.get(error);
-    if (candidateSourceMap && uri === candidateSourceMap.filename) {
-      sourceMap = candidateSourceMap;
+    for (const value of cjsSourceMapCache) {
+      const filename = ObjectGetValueSafe(value, 'filename');
+      if (sourceURL === filename) {
+        sourceMap = {
+          data: ObjectGetValueSafe(value, 'data')
+        };
+      }
     }
   }
   if (sourceMap && sourceMap.data) {

lib/internal/util/iterable_weak_map.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const {
+  makeSafe,
+  Object,
+  SafeSet,
+  SafeWeakMap,
+  SymbolIterator,
+} = primordials;
+
+// TODO(aduh95): Add FinalizationRegistry to primordials
+const SafeFinalizationRegistry = makeSafe(
+  globalThis.FinalizationRegistry,
+  class SafeFinalizationRegistry extends globalThis.FinalizationRegistry {}
+);
+
+// TODO(aduh95): Add WeakRef to primordials
+const SafeWeakRef = makeSafe(
+  globalThis.WeakRef,
+  class SafeWeakRef extends globalThis.WeakRef {}
+);
+
+// This class is modified from the example code in the WeakRefs specification:
+// https://github.com/tc39/proposal-weakrefs
+// Licensed under ECMA's MIT-style license, see:
+// https://github.com/tc39/ecma262/blob/master/LICENSE.md
+class IterableWeakMap {
+  #weakMap = new SafeWeakMap();
+  #refSet = new SafeSet();
+  #finalizationGroup = new SafeFinalizationRegistry(cleanup);
+
+  set(key, value) {
+    const entry = this.#weakMap.get(key);
+    if (entry) {
+      // If there's already an entry for the object represented by "key",
+      // the value can be updated without creating a new WeakRef:
+      this.#weakMap.set(key, { value, ref: entry.ref });
+    } else {
+      const ref = new SafeWeakRef(key);
+      this.#weakMap.set(key, { value, ref });
+      this.#refSet.add(ref);
+      this.#finalizationGroup.register(key, {
+        set: this.#refSet,
+        ref
+      }, ref);
+    }
+  }
+
+  get(key) {
+    return this.#weakMap.get(key)?.value;
+  }
+
+  has(key) {
+    return this.#weakMap.has(key);
+  }
+
+  delete(key) {
+    const entry = this.#weakMap.get(key);
+    if (!entry) {
+      return false;
+    }
+    this.#weakMap.delete(key);
+    this.#refSet.delete(entry.ref);
+    this.#finalizationGroup.unregister(entry.ref);
+    return true;
+  }
+
+  *[SymbolIterator]() {
+    for (const ref of this.#refSet) {
+      const key = ref.deref();
+      if (!key) continue;
+      const { value } = this.#weakMap.get(key);
+      yield value;
+    }
+  }
+}
+
+function cleanup({ set, ref }) {
+  set.delete(ref);
+}
+
+Object.freeze(IterableWeakMap.prototype);
+
+module.exports = {
+  IterableWeakMap,
+};

node.gyp

@@ -208,6 +208,7 @@
       'lib/internal/util/debuglog.js',
       'lib/internal/util/inspect.js',
       'lib/internal/util/inspector.js',
+      'lib/internal/util/iterable_weak_map.js',
       'lib/internal/util/types.js',
       'lib/internal/http2/core.js',
       'lib/internal/http2/compat.js',

test/fixtures/source-map/throw-on-require-entry.js

@@ -0,0 +1,12 @@
+enum ATrue {
+  IsTrue = 1,
+  IsFalse = 0
+}
+ 
+if (false) {
+  console.info('unreachable')
+} else if (true) {
+  throw Error('throw early')
+} else {
+  console.info('unreachable')
+}

test/fixtures/source-map/throw-on-require-entry.js.map

@@ -80,6 +80,7 @@ const expectedModules = new Set([
   'NativeModule internal/util',
   'NativeModule internal/util/debuglog',
   'NativeModule internal/util/inspect',
+  'NativeModule internal/util/iterable_weak_map',
   'NativeModule internal/util/types',
   'NativeModule internal/validators',
   'NativeModule internal/vm/module',