src: add JS APIs for compile cache and NODE_DISABLE_COMPILE_CACHE

This patch adds the following API for tools to enable compile
cache dynamically and query its status.

- module.enableCompileCache(cacheDir)
- module.getCompileCacheDir()

In addition this adds a NODE_DISABLE_COMPILE_CACHE environment
variable to disable the code cache enabled by the APIs as
an escape hatch to avoid unexpected/undesired effects of
the compile cache (e.g. less precise test coverage).

When the module.enableCompileCache() method is invoked without
a specified directory, Node.js will use the value of
the NODE_COMPILE_CACHE environment variable if it's set, or
defaults to `path.join(os.tmpdir(), 'node-compile-cache')`
otherwise. Therefore it's recommended for tools to call this
method without specifying the directory to allow overrides.

PR-URL: #54501
Fixes: #53639
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>

doc/api/cli.md

@@ -2868,25 +2868,8 @@ added: v22.1.0
 
 > Stability: 1.1 - Active Development
 
-When set, whenever Node.js compiles a CommonJS or a ECMAScript Module,
-it will use on-disk [V8 code cache][] persisted in the specified directory
-to speed up the compilation. This may slow down the first load of a
-module graph, but subsequent loads of the same module graph may get
-a significant speedup if the contents of the modules do not change.
-
-To clean up the generated code cache, simply remove the directory.
-It will be recreated the next time the same directory is used for
-`NODE_COMPILE_CACHE`.
-
-Compilation cache generated by one version of Node.js may not be used
-by a different version of Node.js. Cache generated by different versions
-of Node.js will be stored separately if the same directory is used
-to persist the cache, so they can co-exist.
-
-Caveat: currently when using this with [V8 JavaScript code coverage][], the
-coverage being collected by V8 may be less precise in functions that are
-deserialized from the code cache. It's recommended to turn this off when
-running tests to generate precise coverage.
+Enable the [module compile cache][] for the Node.js instance. See the documentation of
+[module compile cache][] for details.
 
 ### `NODE_DEBUG=module[,…]`
 
@@ -2908,6 +2891,17 @@ added: v0.3.0
 
 When set, colors will not be used in the REPL.
 
+### `NODE_DISABLE_COMPILE_CACHE=1`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active Development
+
+Disable the [module compile cache][] for the Node.js instance. See the documentation of
+[module compile cache][] for details.
+
 ### `NODE_EXTRA_CA_CERTS=file`
 
 <!-- YAML
@@ -3559,7 +3553,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [TypeScript type-stripping]: typescript.md#type-stripping
 [V8 Inspector integration for Node.js]: debugger.md#v8-inspector-integration-for-nodejs
 [V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
-[V8 code cache]: https://v8.dev/blog/code-caching-for-devs
 [Web Crypto API]: webcrypto.md
 [`"type"`]: packages.md#type
 [`--allow-child-process`]: #--allow-child-process
@@ -3616,6 +3609,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [filtering tests by name]: test.md#filtering-tests-by-name
 [jitless]: https://v8.dev/blog/jitless
 [libuv threadpool documentation]: https://docs.libuv.org/en/latest/threadpool.html
+[module compile cache]: module.md#module-compile-cache
 [remote code execution]: https://www.owasp.org/index.php/Code_Injection
 [running tests from the command line]: test.md#running-tests-from-the-command-line
 [scavenge garbage collector]: https://v8.dev/blog/orinoco-parallel-scavenger

doc/api/module.md

@@ -64,6 +64,152 @@ const require = createRequire(import.meta.url);
 const siblingModule = require('./sibling-module');
 ```
 
+### `module.constants.compileCacheStatus`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active Development
+
+The following constants are returned as the `status` field in the object returned by
+[`module.enableCompileCache()`][] to indicate the result of the attempt to enable the
+[module compile cache][].
+
+<table>
+  <tr>
+    <th>Constant</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>ENABLED</code></td>
+    <td>
+      Node.js has enabled the compile cache successfully. The directory used to store the
+      compile cache will be returned in the <code>directory</code> field in the
+      returned object.
+    </td>
+  </tr>
+  <tr>
+    <td><code>ALREADY_ENABLED</code></td>
+    <td>
+      The compile cache has already been enabled before, either by a previous call to
+      <code>module.enableCompileCache()</code>, or by the <code>NODE_COMPILE_CACHE=dir</code>
+      environment variable. The directory used to store the
+      compile cache will be returned in the <code>directory</code> field in the
+      returned object.
+    </td>
+  </tr>
+  <tr>
+    <td><code>FAILED</code></td>
+    <td>
+      Node.js fails to enable the compile cache. This can be caused by the lack of
+      permission to use the specified directory, or various kinds of file system errors.
+      The detail of the failure will be returned in the <code>message</code> field in the
+      returned object.
+    </td>
+  </tr>
+  <tr>
+    <td><code>DISABLED</code></td>
+    <td>
+      Node.js cannot enable the compile cache because the environment variable
+      <code>NODE_DISABLE_COMPILE_CACHE=1</code> has been set.
+    </td>
+  </tr>
+</table>
+
+### `module.enableCompileCache([cacheDir])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active Development
+
+* `cacheDir` {string|undefined} Optional path to specify the directory where the compile cache
+  will be stored/retrieved.
+* Returns: {Object}
+  * `status` {integer} One of the [`module.constants.compileCacheStatus`][]
+  * `message` {string|undefined} If Node.js cannot enable the compile cache, this contains
+    the error message. Only set if `status` is `module.constants.compileCacheStatus.FAILED`.
+  * `directory` {string|undefined} If the compile cache is enabled, this contains the directory
+    where the compile cache is stored. Only set if  `status` is
+    `module.constants.compileCacheStatus.ENABLED` or
+    `module.constants.compileCacheStatus.ALREADY_ENABLED`.
+
+Enable [module compile cache][] in the current Node.js instance.
+
+If `cacheDir` is not specified, Node.js will either use the directory specified by the
+[`NODE_COMPILE_CACHE=dir`][] environment variable if it's set, or use
+`path.join(os.tmpdir(), 'node-compile-cache')` otherwise. For general use cases, it's
+recommended to call `module.enableCompileCache()` without specifying the `cacheDir`,
+so that the directory can be overriden by the `NODE_COMPILE_CACHE` environment
+variable when necessary.
+
+Since compile cache is supposed to be a quiet optimization that is not required for the
+application to be functional, this method is designed to not throw any exception when the
+compile cache cannot be enabled. Instead, it will return an object containing an error
+message in the `message` field to aid debugging.
+If compile cache is enabled successefully, the `directory` field in the returned object
+contains the path to the directory where the compile cache is stored. The `status`
+field in the returned object would be one of the `module.constants.compileCacheStatus`
+values to indicate the result of the attempt to enable the [module compile cache][].
+
+This method only affects the current Node.js instance. To enable it in child worker threads,
+either call this method in child worker threads too, or set the
+`process.env.NODE_COMPILE_CACHE` value to compile cache directory so the behavior can
+be inheritend into the child workers. The directory can be obtained either from the
+`directory` field returned by this method, or with [`module.getCompileCacheDir()`][].
+
+#### Module compile cache
+
+<!-- YAML
+added: v22.1.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/54501
+    description: add initial JavaScript APIs for runtime access.
+-->
+
+The module compile cache can be enabled either using the [`module.enableCompileCache()`][]
+method or the [`NODE_COMPILE_CACHE=dir`][] environemnt variable. After it's enabled,
+whenever Node.js compiles a CommonJS or a ECMAScript Module, it will use on-disk
+[V8 code cache][] persisted in the specified directory to speed up the compilation.
+This may slow down the first load of a module graph, but subsequent loads of the same module
+graph may get a significant speedup if the contents of the modules do not change.
+
+To clean up the generated compile cache on disk, simply remove the cache directory. The cache
+directory will be recreated the next time the same directory is used for for compile cache
+storage. To avoid filling up the disk with stale cache, it is recommended to use a directory
+under the [`os.tmpdir()`][]. If the compile cache is enabled by a call to
+[`module.enableCompileCache()`][] without specifying the directory, Node.js will use
+the [`NODE_DISABLE_COMPILE_CACHE=1`][] environment variable if it's set, or defaults
+to `path.join(os.tmpdir(), 'node-compile-cache')` otherwise. To locate the compile cache
+directory used by a running Node.js instance, use [`module.getCompileCacheDir()`][].
+
+Currently when using the compile cache with [V8 JavaScript code coverage][], the
+coverage being collected by V8 may be less precise in functions that are
+deserialized from the code cache. It's recommended to turn this off when
+running tests to generate precise coverage.
+
+The enabled module compile cache can be disabled by the [`NODE_DISABLE_COMPILE_CACHE=1`][]
+environment variable. This can be useful when the compile cache leads to unexpected or
+undesired behaviors (e.g. less precise test coverage).
+
+Compilation cache generated by one version of Node.js can not be reused by a different
+version of Node.js. Cache generated by different versions of Node.js will be stored
+separately if the same base directory is used to persist the cache, so they can co-exist.
+
+### `module.getCompileCacheDir()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active Development
+
+* Returns: {string|undefined} Path to the [module compile cache][] directory if it is enabled,
+  or `undefined` otherwise.
+
 ### `module.isBuiltin(moduleName)`
 
 <!-- YAML
@@ -1055,22 +1201,31 @@ returned object contains the following keys:
 [Customization hooks]: #customization-hooks
 [ES Modules]: esm.md
 [Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
+[V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
+[V8 code cache]: https://v8.dev/blog/code-caching-for-devs
 [`"exports"`]: packages.md#exports
 [`--enable-source-maps`]: cli.md#--enable-source-maps
 [`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
+[`NODE_COMPILE_CACHE=dir`]: cli.md#node_compile_cachedir
+[`NODE_DISABLE_COMPILE_CACHE=1`]: cli.md#node_disable_compile_cache1
 [`NODE_V8_COVERAGE=dir`]: cli.md#node_v8_coveragedir
 [`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
 [`SourceMap`]: #class-modulesourcemap
 [`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
 [`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
 [`initialize`]: #initialize
-[`module`]: modules.md#the-module-object
+[`module.constants.compileCacheStatus`]: #moduleconstantscompilecachestatus
+[`module.enableCompileCache()`]: #moduleenablecompilecachecachedir
+[`module.getCompileCacheDir()`]: #modulegetcompilecachedir
+[`module`]: #the-module-object
+[`os.tmpdir()`]: os.md#ostmpdir
 [`register`]: #moduleregisterspecifier-parenturl-options
 [`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
 [`util.TextDecoder`]: util.md#class-utiltextdecoder
 [chain]: #chaining
 [hooks]: #customization-hooks
 [load hook]: #loadurl-context-nextload
+[module compile cache]: #module-compile-cache
 [module wrapper]: modules.md#the-module-wrapper
 [prefix-only modules]: modules.md#built-in-modules-with-mandatory-node-prefix
 [realm]: https://tc39.es/ecma262/#realm

lib/internal/modules/helpers.js

@@ -4,6 +4,7 @@ const {
   ArrayPrototypeForEach,
   ArrayPrototypeIncludes,
   ObjectDefineProperty,
+  ObjectFreeze,
   ObjectPrototypeHasOwnProperty,
   SafeMap,
   SafeSet,
@@ -27,10 +28,18 @@ const assert = require('internal/assert');
 
 const { Buffer } = require('buffer');
 const { getOptionValue } = require('internal/options');
-const { setOwnProperty } = require('internal/util');
+const { setOwnProperty, getLazy } = require('internal/util');
 const { inspect } = require('internal/util/inspect');
 
+const lazyTmpdir = getLazy(() => require('os').tmpdir());
+const { join } = path;
+
 const { canParse: URLCanParse } = internalBinding('url');
+const {
+  enableCompileCache: _enableCompileCache,
+  getCompileCacheDir: _getCompileCacheDir,
+  compileCacheStatus: _compileCacheStatus,
+} = internalBinding('modules');
 
 let debug = require('internal/util/debuglog').debuglog('module', (fn) => {
   debug = fn;
@@ -380,10 +389,53 @@ function isUnderNodeModules(filename) {
   return ArrayPrototypeIncludes(splitPath, 'node_modules');
 }
 
+/**
+ * Enable on-disk compiled cache for all user modules being complied in the current Node.js instance
+ * after this method is called.
+ * If cacheDir is undefined, defaults to the NODE_MODULE_CACHE environment variable.
+ * If NODE_MODULE_CACHE isn't set, default to path.join(os.tmpdir(), 'node-compile-cache').
+ * @param {string|undefined} cacheDir
+ * @returns {{status: number, message?: string, directory?: string}}
+ */
+function enableCompileCache(cacheDir) {
+  if (cacheDir === undefined) {
+    cacheDir = join(lazyTmpdir(), 'node-compile-cache');
+  }
+  const nativeResult = _enableCompileCache(cacheDir);
+  const result = { status: nativeResult[0] };
+  if (nativeResult[1]) {
+    result.message = nativeResult[1];
+  }
+  if (nativeResult[2]) {
+    result.directory = nativeResult[2];
+  }
+  return result;
+}
+
+const compileCacheStatus = { __proto__: null };
+for (let i = 0; i < _compileCacheStatus.length; ++i) {
+  compileCacheStatus[_compileCacheStatus[i]] = i;
+}
+ObjectFreeze(compileCacheStatus);
+const constants = { __proto__: null, compileCacheStatus };
+ObjectFreeze(constants);
+
+/**
+ * Get the compile cache directory if on-disk compile cache is enabled.
+ * @returns {string|undefined} Path to the module compile cache directory if it is enabled,
+ *                             or undefined otherwise.
+ */
+function getCompileCacheDir() {
+  return _getCompileCacheDir() || undefined;
+}
+
 module.exports = {
   addBuiltinLibsToObject,
+  constants,
+  enableCompileCache,
   getBuiltinModule,
   getCjsConditions,
+  getCompileCacheDir,
   initializeCjsConditions,
   isUnderNodeModules,
   loadBuiltinModule,

lib/module.js

@@ -4,8 +4,16 @@ const { findSourceMap } = require('internal/source_map/source_map_cache');
 const { Module } = require('internal/modules/cjs/loader');
 const { register } = require('internal/modules/esm/loader');
 const { SourceMap } = require('internal/source_map/source_map');
+const {
+  constants,
+  enableCompileCache,
+  getCompileCacheDir,
+} = require('internal/modules/helpers');
 
 Module.findSourceMap = findSourceMap;
 Module.register = register;
 Module.SourceMap = SourceMap;
+Module.constants = constants;
+Module.enableCompileCache = enableCompileCache;
+Module.getCompileCacheDir = getCompileCacheDir;
 module.exports = Module;

src/compile_cache.cc

@@ -381,7 +381,7 @@ CompileCacheEnableResult CompileCacheHandler::Enable(Environment* env,
           cache_dir_with_tag_str))) {
     result.message = "Skipping compile cache because write permission for " +
                      cache_dir_with_tag_str + " is not granted";
-    result.status = CompileCacheEnableStatus::kFailed;
+    result.status = CompileCacheEnableStatus::FAILED;
     return result;
   }
 
@@ -391,7 +391,7 @@ CompileCacheEnableResult CompileCacheHandler::Enable(Environment* env,
           cache_dir_with_tag_str))) {
     result.message = "Skipping compile cache because read permission for " +
                      cache_dir_with_tag_str + " is not granted";
-    result.status = CompileCacheEnableStatus::kFailed;
+    result.status = CompileCacheEnableStatus::FAILED;
     return result;
   }
 
@@ -406,14 +406,14 @@ CompileCacheEnableResult CompileCacheHandler::Enable(Environment* env,
   if (err != 0 && err != UV_EEXIST) {
     result.message =
         "Cannot create cache directory: " + std::string(uv_strerror(err));
-    result.status = CompileCacheEnableStatus::kFailed;
+    result.status = CompileCacheEnableStatus::FAILED;
     return result;
   }
 
   compile_cache_dir_str_ = absolute_cache_dir_base;
   result.cache_directory = absolute_cache_dir_base;
   compile_cache_dir_ = cache_dir_with_tag;
-  result.status = CompileCacheEnableStatus::kEnabled;
+  result.status = CompileCacheEnableStatus::ENABLED;
   return result;
 }
 

src/compile_cache.h

@@ -36,9 +36,10 @@ struct CompileCacheEntry {
 };
 
 #define COMPILE_CACHE_STATUS(V)                                                \
-  V(kFailed)         /* Failed to enable the cache */                          \
-  V(kEnabled)        /* Was not enabled before, and now enabled. */            \
-  V(kAlreadyEnabled) /* Was already enabled. */
+  V(FAILED)          /* Failed to enable the cache */                          \
+  V(ENABLED)         /* Was not enabled before, and now enabled. */            \
+  V(ALREADY_ENABLED) /* Was already enabled. */                                \
+  V(DISABLED)        /* Has been disabled by NODE_DISABLE_COMPILE_CACHE. */
 
 enum class CompileCacheEnableStatus : uint8_t {
 #define V(status) status,