src: add an option to make compile cache portable

Adds an option (NODE_COMPILE_CACHE_PORTABLE) for
the built-in compile cache to encode the hashes with
relative file paths. On enabling the option,
the source directory along with cache directory can be
bundled and moved, and the cache continues to work.

When enabled, paths encoded in hash are relative to
compile cache directory.

Author: Aditi-1400

doc/api/cli.md

@@ -3253,6 +3253,10 @@ added: v22.1.0
 Enable the [module compile cache][] for the Node.js instance. See the documentation of
 [module compile cache][] for details.
 
+### `NODE_COMPILE_CACHE_PORTABLE=1`
+
+When set to 1, the path for [module compile cache][] is considered relative.
+
 ### `NODE_DEBUG=module[,…]`
 
 <!-- YAML

doc/api/module.md

@@ -399,6 +399,18 @@ the [`NODE_COMPILE_CACHE=dir`][] 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()`][].
 
+When portable mode is enabled, cache keys use paths relative to the compile cache directory.
+This allows the cache to be reused after moving the project across directories etc.
+
+It can be enabled via:
+
+```js
+module.enableCompileCache({ path: '...', portable: true });
+```
+
+or [`NODE_COMPILE_CACHE_PORTABLE=1`][] environment variable.
+If a relative path can't be computed, Node.js falls back to using the absolute path.
+
 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
@@ -1789,6 +1801,7 @@ returned object contains the following keys:
 [`--import`]: cli.md#--importmodule
 [`--require`]: cli.md#-r---require-module
 [`NODE_COMPILE_CACHE=dir`]: cli.md#node_compile_cachedir
+[`NODE_COMPILE_CACHE_PORTABLE=1`]: cli.md#node_compile_cache_portable1
 [`NODE_DISABLE_COMPILE_CACHE=1`]: cli.md#node_disable_compile_cache1
 [`NODE_V8_COVERAGE=dir`]: cli.md#node_v8_coveragedir
 [`SourceMap`]: #class-modulesourcemap

doc/node.1

@@ -701,6 +701,14 @@ Enable the
 .Sy module compile cache
 for the Node.js instance.
 .
+.It Ev NODE_COMPILE_CACHE_PORTABLE
+When set to '1' or 'true', the
+.Sy module compile cache
+uses relative paths when computing cache keys. This makes the cache
+portable across directories etc.
+This can be used in conjunction with .Ev NODE_COMPILE_CACHE
+to enable on-disk caching with relative path resolution.
+.
 .It Ev NODE_DEBUG Ar modules...
 Comma-separated list of core modules that should print debug information.
 .

lib/internal/modules/helpers.js

@@ -371,18 +371,31 @@ function stringify(body) {
 }
 
 /**
- * Enable on-disk compiled cache for all user modules being complied in the current Node.js instance
+ * Enable on-disk compiled cache for all user modules being compiled 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
+ * This method accepts either:
+ * - A string `cacheDir`: the path to the cache directory.
+ * - An options object `{path?: string, portable?: boolean}`:
+ *   - `path`: A string path to the cache directory.
+ *   - `portable`: If `portable` is true, the cache directory will be considered relative. Defaults to false.
+ * If cache path is undefined, it defaults to the NODE_MODULE_CACHE environment variable.
+ * If `NODE_MODULE_CACHE` isn't set, it defaults to `path.join(os.tmpdir(), 'node-compile-cache')`.
+ * @param {string | { path?: string, portable?: boolean } | undefined} options
  * @returns {{status: number, message?: string, directory?: string}}
  */
-function enableCompileCache(cacheDir) {
+function enableCompileCache(options) {
+  let cacheDir;
+  let portable = false;
+
+  if (typeof options === 'object' && options !== null) {
+    ({ path: cacheDir, portable = false } = options);
+  } else {
+    cacheDir = options;
+  }
   if (cacheDir === undefined) {
     cacheDir = join(lazyTmpdir(), 'node-compile-cache');
   }
-  const nativeResult = _enableCompileCache(cacheDir);
+  const nativeResult = _enableCompileCache(cacheDir, portable);
   const result = { status: nativeResult[0] };
   if (nativeResult[1]) {
     result.message = nativeResult[1];

src/compile_cache.cc

@@ -13,8 +13,14 @@
 #include <unistd.h>  // getuid
 #endif
 
+#ifdef _WIN32
+#include <windows.h>
+#endif
 namespace node {
 
+#ifdef _WIN32
+using fs::ConvertWideToUTF8;
+#endif
 using v8::Function;
 using v8::Local;
 using v8::Module;
@@ -223,13 +229,102 @@ void CompileCacheHandler::ReadCacheFile(CompileCacheEntry* entry) {
   Debug(" success, size=%d\n", total_read);
 }
 
+#ifdef _WIN32
+constexpr bool IsWindowsDeviceRoot(const char c) noexcept {
+  return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
+}
+#endif
+
+static std::string NormalisePath(std::string_view path) {
+  std::string normalised_string(path);
+  constexpr std::string_view file_scheme = "file://";
+  if (normalised_string.rfind(file_scheme, 0) == 0) {
+    normalised_string.erase(0, file_scheme.size());
+  }
+
+#ifdef _WIN32
+  if (normalised_string.size() > 2 &&
+      IsWindowsDeviceRoot(normalised_string[0]) &&
+      normalised_string[1] == ':' &&
+      (normalised_string[2] == '/' || normalised_string[2] == '\\')) {
+    normalised_string[0] = ToLower(normalised_string[0]);
+  }
+#endif
+  for (char& c : normalised_string) {
+    if (c == '\\') {
+      c = '/';
+    }
+  }
+
+  normalised_string = NormalizeString(normalised_string, false, "/");
+  return normalised_string;
+}
+
+// Check if a path looks like an absolute path or file URL.
+static bool IsAbsoluteFilePath(std::string_view path) {
+  if (path.rfind("file://", 0) == 0) {
+    return true;
+  }
+#ifdef _WIN32
+  if (path.size() > 2 && IsWindowsDeviceRoot(path[0]) &&
+      (path[1] == ':' && (path[2] == '/' || path[2] == '\\')))
+    return true;
+  if (path.size() > 1 && path[0] == '\\' && path[1] == '\\') return true;
+#else
+  if (path.size() > 0 && path[0] == '/') return true;
+#endif
+  return false;
+}
+
+static std::string GetRelativePath(std::string_view path,
+                                   std::string_view base) {
+// On Windows, the native encoding is UTF-16, so we need to convert
+// the paths to wide strings before using std::filesystem::path.
+// On other platforms, std::filesystem::path can handle UTF-8 directly.
+#ifdef _WIN32
+  std::wstring wpath = ConvertToWideString(std::string(path), CP_UTF8);
+  std::wstring wbase = ConvertToWideString(std::string(base), CP_UTF8);
+  std::filesystem::path relative =
+      std::filesystem::path(wpath).lexically_relative(
+          std::filesystem::path(wbase));
+  if (relative.empty()) {
+    return std::string();
+  }
+  std::string relative_path = ConvertWideToUTF8(relative.wstring());
+  return relative_path;
+#else
+  std::filesystem::path relative =
+      std::filesystem::path(path).lexically_relative(
+          std::filesystem::path(base));
+  if (relative.empty()) {
+    return std::string();
+  }
+  return relative.generic_string();
+#endif
+}
+
 CompileCacheEntry* CompileCacheHandler::GetOrInsert(Local<String> code,
                                                     Local<String> filename,
                                                     CachedCodeType type) {
   DCHECK(!compile_cache_dir_.empty());
 
   Utf8Value filename_utf8(isolate_, filename);
-  uint32_t key = GetCacheKey(filename_utf8.ToStringView(), type);
+  std::string file_path = filename_utf8.ToString();
+  // If the relative path is enabled, we try to use a relative path
+  // from the compile cache directory to the file path
+  if (portable_ && IsAbsoluteFilePath(file_path)) {
+    // Normalise the path to ensure it is consistent.
+    std::string normalised_file_path = NormalisePath(file_path);
+    std::string relative_path =
+        GetRelativePath(normalised_file_path, normalised_compile_cache_dir_);
+    if (!relative_path.empty()) {
+      file_path = relative_path;
+      Debug("[compile cache] using relative path %s from %s\n",
+            file_path.c_str(),
+            absolute_compile_cache_dir_.c_str());
+    }
+  }
+  uint32_t key = GetCacheKey(file_path, type);
 
   // TODO(joyeecheung): don't encode this again into UTF8. If we read the
   // UTF8 content on disk as raw buffer (from the JS layer, while watching out
@@ -500,11 +595,15 @@ CompileCacheHandler::CompileCacheHandler(Environment* env)
 //   - $NODE_VERSION-$ARCH-$CACHE_DATA_VERSION_TAG-$UID
 //     - $FILENAME_AND_MODULE_TYPE_HASH.cache: a hash of filename + module type
 CompileCacheEnableResult CompileCacheHandler::Enable(Environment* env,
-                                                     const std::string& dir) {
+                                                     const std::string& dir,
+                                                     bool portable) {
   std::string cache_tag = GetCacheVersionTag();
-  std::string absolute_cache_dir_base = PathResolve(env, {dir});
-  std::string cache_dir_with_tag =
-      absolute_cache_dir_base + kPathSeparator + cache_tag;
+  std::string base_dir = dir;
+  if (!portable) {
+    base_dir = PathResolve(env, {dir});
+  }
+
+  std::string cache_dir_with_tag = base_dir + kPathSeparator + cache_tag;
   CompileCacheEnableResult result;
   Debug("[compile cache] resolved path %s + %s -> %s\n",
         dir,
@@ -546,8 +645,11 @@ CompileCacheEnableResult CompileCacheHandler::Enable(Environment* env,
     return result;
   }
 
-  result.cache_directory = absolute_cache_dir_base;
+  result.cache_directory = base_dir;
   compile_cache_dir_ = cache_dir_with_tag;
+  absolute_compile_cache_dir_ = PathResolve(env, {compile_cache_dir_});
+  portable_ = portable;
+  normalised_compile_cache_dir_ = NormalisePath(absolute_compile_cache_dir_);
   result.status = CompileCacheEnableStatus::ENABLED;
   return result;
 }

src/compile_cache.h

@@ -65,7 +65,9 @@ struct CompileCacheEnableResult {
 class CompileCacheHandler {
  public:
   explicit CompileCacheHandler(Environment* env);
-  CompileCacheEnableResult Enable(Environment* env, const std::string& dir);
+  CompileCacheEnableResult Enable(Environment* env,
+                                  const std::string& dir,
+                                  bool portable);
 
   void Persist();
 
@@ -103,6 +105,9 @@ class CompileCacheHandler {
   bool is_debug_ = false;
 
   std::string compile_cache_dir_;
+  std::string absolute_compile_cache_dir_;
+  std::string normalised_compile_cache_dir_;
+  bool portable_ = false;
   std::unordered_map<uint32_t, std::unique_ptr<CompileCacheEntry>>
       compiler_cache_store_;
 };

src/env.cc

@@ -1122,11 +1122,21 @@ void Environment::InitializeCompileCache() {
       dir_from_env.empty()) {
     return;
   }
-  EnableCompileCache(dir_from_env);
+  std::string portable_env;
+  bool portable = credentials::SafeGetenv(
+                      "NODE_COMPILE_CACHE_PORTABLE", &portable_env, this) &&
+                  !portable_env.empty() &&
+                  (portable_env == "1" || portable_env == "true");
+  if (portable) {
+    Debug(this,
+          DebugCategory::COMPILE_CACHE,
+          "[compile cache] using relative path\n");
+  }
+  EnableCompileCache(dir_from_env, portable);
 }
 
 CompileCacheEnableResult Environment::EnableCompileCache(
-    const std::string& cache_dir) {
+    const std::string& cache_dir, bool portable) {
   CompileCacheEnableResult result;
   std::string disable_env;
   if (credentials::SafeGetenv(
@@ -1143,7 +1153,7 @@ CompileCacheEnableResult Environment::EnableCompileCache(
   if (!compile_cache_handler_) {
     std::unique_ptr<CompileCacheHandler> handler =
         std::make_unique<CompileCacheHandler>(this);
-    result = handler->Enable(this, cache_dir);
+    result = handler->Enable(this, cache_dir, portable);
     if (result.status == CompileCacheEnableStatus::ENABLED) {
       compile_cache_handler_ = std::move(handler);
       AtExit(

src/env.h

@@ -1022,7 +1022,8 @@ class Environment final : public MemoryRetainer {
   void InitializeCompileCache();
   // Enable built-in compile cache if it has not yet been enabled.
   // The cache will be persisted to disk on exit.
-  CompileCacheEnableResult EnableCompileCache(const std::string& cache_dir);
+  CompileCacheEnableResult EnableCompileCache(const std::string& cache_dir,
+                                              bool portable);
   void FlushCompileCache();
 
   void RunAndClearNativeImmediates(bool only_refed = false);

src/node_file.h

@@ -531,6 +531,8 @@ int SyncCallAndThrowOnError(Environment* env,
                             FSReqWrapSync* req_wrap,
                             Func fn,
                             Args... args);
+
+std::string ConvertWideToUTF8(const std::wstring& wstr);
 }  // namespace fs
 
 }  // namespace node

src/node_modules.cc

@@ -513,8 +513,14 @@ void EnableCompileCache(const FunctionCallbackInfo<Value>& args) {
     THROW_ERR_INVALID_ARG_TYPE(env, "cacheDir should be a string");
     return;
   }
+
+  bool portable = false;
+  if (args.Length() > 1 && args[1]->IsTrue()) {
+    portable = true;
+  }
+
   Utf8Value value(isolate, args[0]);
-  CompileCacheEnableResult result = env->EnableCompileCache(*value);
+  CompileCacheEnableResult result = env->EnableCompileCache(*value, portable);
   Local<Value> values[3];
   values[0] = v8::Integer::New(isolate, static_cast<uint8_t>(result.status));
   if (ToV8Value(context, result.message).ToLocal(&values[1]) &&