src: improve compile cache performance and size

Improve the compile cache by:

- Reading cache files with a single exactly-sized read using the file
  size from fstat instead of reading into an exponentially growing
  buffer, which previously cost O(log N) syscalls and allocations and
  about 2N bytes of copying per file.
- Compressing the cache content on disk with zstd at level 1, falling
  back to raw storage when the data is not compressible. This shrinks
  cache directories by about 2-4x. The magic number is bumped so that
  files in the old format are discarded as cache misses and then
  overwritten in place.
- Handing the cache to V8 through a non-owning CachedData wrapper
  instead of copying the whole buffer on every cache hit.

Corrupted cache files keep degrading to silent cache misses and are
regenerated, now covered by a regression test.

Co-authored-by: Grok <grok@x.ai>
Signed-off-by: Yagiz Nizipli <yagiz@nizipli.com>

Author: anonrig

src/compile_cache.cc

@@ -1,4 +1,6 @@
 #include "compile_cache.h"
+#include <array>
+#include <memory>
 #include <string>
 #include "debug_utils-inl.h"
 #include "env-inl.h"
@@ -8,6 +10,7 @@
 #include "path.h"
 #include "util.h"
 #include "zlib.h"
+#include "zstd.h"
 
 #ifdef NODE_IMPLEMENTS_POSIX_CREDENTIALS
 #include <unistd.h>  // getuid
@@ -75,18 +78,21 @@ inline void CompileCacheHandler::Debug(const char* format,
   }
 }
 
-ScriptCompiler::CachedData* CompileCacheEntry::CopyCache() const {
+ScriptCompiler::CachedData* CompileCacheEntry::WrapCache() const {
   DCHECK_NOT_NULL(cache);
-  int cache_size = cache->length;
-  uint8_t* data = new uint8_t[cache_size];
-  memcpy(data, cache->data, cache_size);
+  // The returned CachedData does not own the buffer - it's a view into
+  // the buffer owned by this entry, which outlives the synchronous
+  // consumption of the cache during compilation, so no copy is necessary.
   return new ScriptCompiler::CachedData(
-      data, cache_size, ScriptCompiler::CachedData::BufferOwned);
+      cache->data, cache->length, ScriptCompiler::CachedData::BufferNotOwned);
 }
 
 // Used for identifying and verifying a file is a compile cache file.
 // See comments in CompileCacheHandler::Persist().
-constexpr uint32_t kCacheMagicNumber = 0x8adfdbb2;
+// The last byte is bumped whenever the format of the cache file changes
+// so that files in an older format are discarded as cache misses and
+// then overwritten with the new format.
+constexpr uint32_t kCacheMagicNumber = 0x8adfdbb3;
 
 const char* CompileCacheEntry::type_name() const {
   switch (type) {
@@ -124,10 +130,21 @@ void CompileCacheHandler::ReadCacheFile(CompileCacheEntry* entry) {
     uv_fs_req_cleanup(&close_req);
   });
 
+  // Get the file size upfront so that the cache can be read with a single
+  // exactly-sized read, and truncated or trailing data can be detected
+  // without additional read attempts.
+  int err = uv_fs_fstat(nullptr, &req, file, nullptr);
+  if (err < 0) {
+    Debug("fstat failed, %s\n", uv_strerror(err));
+    return;
+  }
+  uint64_t file_size = req.statbuf.st_size;
+  uv_fs_req_cleanup(&req);
+
   // Read the headers.
-  std::vector<uint32_t> headers(kHeaderCount);
-  uv_buf_t headers_buf = uv_buf_init(reinterpret_cast<char*>(headers.data()),
-                                     kHeaderCount * sizeof(uint32_t));
+  std::array<uint32_t, kHeaderCount> headers;
+  uv_buf_t headers_buf =
+      uv_buf_init(reinterpret_cast<char*>(headers.data()), kHeaderSize);
   const int r = uv_fs_read(nullptr, &req, file, &headers_buf, 1, 0, nullptr);
   if (r != static_cast<int>(headers_buf.len)) {
     Debug("reading header failed, bytes read %d", r);
@@ -137,13 +154,15 @@ void CompileCacheHandler::ReadCacheFile(CompileCacheEntry* entry) {
     Debug("\n");
     return;
   }
+  uv_fs_req_cleanup(&req);
 
-  Debug("[%d %d %d %d %d]...",
+  Debug("[%d %d %d %d %d %d]...",
         headers[kMagicNumberOffset],
         headers[kCodeSizeOffset],
         headers[kCacheSizeOffset],
         headers[kCodeHashOffset],
-        headers[kCacheHashOffset]);
+        headers[kCacheHashOffset],
+        headers[kCacheRawSizeOffset]);
 
   if (headers[kMagicNumberOffset] != kCacheMagicNumber) {
     Debug("magic number mismatch: expected %d, actual %d\n",
@@ -166,60 +185,102 @@ void CompileCacheHandler::ReadCacheFile(CompileCacheEntry* entry) {
     return;
   }
 
-  // Read the cache, grow the buffer exponentially whenever it fills up.
-  size_t offset = headers_buf.len;
-  size_t capacity = 4096;  // Initial buffer capacity
-  size_t total_read = 0;
-  uint8_t* buffer = new uint8_t[capacity];
-
-  while (true) {
-    // If there is not enough space to read more data, do a simple
-    // realloc here (we don't actually realloc because V8 requires
-    // the underlying buffer to be delete[]-able).
-    if (total_read == capacity) {
-      size_t new_capacity = capacity * 2;
-      auto* new_buffer = new uint8_t[new_capacity];
-      memcpy(new_buffer, buffer, capacity);
-      delete[] buffer;
-      buffer = new_buffer;
-      capacity = new_capacity;
-    }
+  uint32_t cache_size = headers[kCacheSizeOffset];
+  uint32_t raw_size = headers[kCacheRawSizeOffset];
+
+  // Check the cache size. The headers were read successfully, so
+  // file_size >= kHeaderSize here. The file must contain exactly the
+  // headers followed by cache_size bytes of cache content.
+  if (file_size - kHeaderSize != cache_size) {
+    Debug("cache size mismatch: expected %d, actual %d\n",
+          cache_size,
+          file_size - kHeaderSize);
+    return;
+  }
 
-    uv_buf_t iov = uv_buf_init(reinterpret_cast<char*>(buffer + total_read),
-                               capacity - total_read);
-    int bytes_read =
-        uv_fs_read(nullptr, &req, file, &iov, 1, offset + total_read, nullptr);
+  // The cache content is stored uncompressed when cache_size == raw_size,
+  // and zstd-compressed when cache_size < raw_size (see
+  // CompileCacheHandler::Persist()). Anything else is invalid.
+  if (cache_size > raw_size) {
+    Debug("invalid cache size %d > uncompressed size %d\n",
+          cache_size,
+          raw_size);
+    return;
+  }
+
+  // Read the cache content in one go with an exactly-sized buffer,
+  // looping only in case of short reads.
+  std::unique_ptr<uint8_t[]> disk_data(new uint8_t[cache_size]);
+  size_t total_read = 0;
+  while (total_read < cache_size) {
+    uv_buf_t iov =
+        uv_buf_init(reinterpret_cast<char*>(disk_data.get() + total_read),
+                    cache_size - total_read);
+    int bytes_read = uv_fs_read(
+        nullptr, &req, file, &iov, 1, kHeaderSize + total_read, nullptr);
     if (req.result < 0) {  // Error.
       // req will be cleaned up by scope leave.
-      delete[] buffer;
       Debug(" %s\n", uv_strerror(req.result));
       return;
     }
     uv_fs_req_cleanup(&req);
-    if (bytes_read <= 0) {
-      break;
+    if (bytes_read == 0) {  // Unexpected EOF - the file shrank under us.
+      Debug("cache size mismatch: expected %d, actual %d\n",
+            cache_size,
+            total_read);
+      return;
     }
     total_read += bytes_read;
   }
 
-  // Check the cache size and hash.
-  if (headers[kCacheSizeOffset] != total_read) {
-    Debug("cache size mismatch: expected %d, actual %d\n",
-          headers[kCacheSizeOffset],
-          total_read);
-    return;
-  }
-  uint32_t cache_hash = GetHash(reinterpret_cast<char*>(buffer), total_read);
+  // Check the cache hash of the on-disk content before decompressing.
+  uint32_t cache_hash =
+      GetHash(reinterpret_cast<char*>(disk_data.get()), cache_size);
   if (headers[kCacheHashOffset] != cache_hash) {
     Debug("cache hash mismatch: expected %d, actual %d\n",
           headers[kCacheHashOffset],
           cache_hash);
     return;
   }
 
-  entry->cache.reset(new ScriptCompiler::CachedData(
-      buffer, total_read, ScriptCompiler::CachedData::BufferOwned));
-  Debug(" success, size=%d\n", total_read);
+  if (cache_size == raw_size) {
+    // Stored uncompressed - hand the buffer to V8 directly.
+    entry->cache.reset(new ScriptCompiler::CachedData(
+        disk_data.release(),
+        raw_size,
+        ScriptCompiler::CachedData::BufferOwned));
+  } else {
+    // Cross-check the content size embedded in the zstd frame before
+    // allocating, in case the headers are corrupted.
+    unsigned long long content_size =  // NOLINT(runtime/int)
+        ZSTD_getFrameContentSize(disk_data.get(), cache_size);
+    if (content_size != raw_size) {
+      Debug("uncompressed size mismatch: expected %d, actual %d\n",
+            raw_size,
+            content_size);
+      return;
+    }
+    // Decompress directly into the buffer handed to V8.
+    std::unique_ptr<uint8_t[]> raw_data(new uint8_t[raw_size]);
+    size_t decompressed_size =
+        ZSTD_decompress(raw_data.get(), raw_size, disk_data.get(), cache_size);
+    if (ZSTD_isError(decompressed_size)) {
+      Debug("decompression failed: %s\n",
+            ZSTD_getErrorName(decompressed_size));
+      return;
+    }
+    if (decompressed_size != raw_size) {
+      Debug("decompressed size mismatch: expected %d, actual %d\n",
+            raw_size,
+            decompressed_size);
+      return;
+    }
+    entry->cache.reset(new ScriptCompiler::CachedData(
+        raw_data.release(),
+        raw_size,
+        ScriptCompiler::CachedData::BufferOwned));
+  }
+  Debug(" success, size=%d\n", raw_size);
 }
 
 static std::string GetRelativePath(std::string_view path,
@@ -280,11 +341,18 @@ CompileCacheEntry* CompileCacheHandler::GetOrInsert(Local<String> code,
     return loaded->second.get();
   }
 
-  // If the code hash mismatches, the code has changed, discard the stale entry
-  // and create a new one.
-  auto emplaced =
-      compiler_cache_store_.emplace(key, std::make_unique<CompileCacheEntry>());
-  auto* result = emplaced.first->second.get();
+  // If the code hash mismatches, the code has changed, reset the stale
+  // entry in place. Otherwise insert a new one.
+  CompileCacheEntry* result;
+  if (loaded != compiler_cache_store_.end()) {
+    result = loaded->second.get();
+    result->refreshed = false;
+    result->persisted = false;
+  } else {
+    result = compiler_cache_store_
+                 .emplace(key, std::make_unique<CompileCacheEntry>())
+                 .first->second.get();
+  }
 
   result->code_hash = code_hash;
   result->code_size = code_utf8.length();
@@ -418,18 +486,41 @@ void CompileCacheHandler::Persist() {
 
     DCHECK_EQ(entry->cache->buffer_policy,
               ScriptCompiler::CachedData::BufferOwned);
-    char* cache_ptr =
+    char* raw_ptr =
         reinterpret_cast<char*>(const_cast<uint8_t*>(entry->cache->data));
-    uint32_t cache_size = static_cast<uint32_t>(entry->cache->length);
+    uint32_t raw_size = static_cast<uint32_t>(entry->cache->length);
+
+    // Compress the cache with zstd to reduce the size on disk. Compression
+    // level 1 prioritizes speed - persistence usually happens on process
+    // shutdown and should add as little overhead as possible. If the data
+    // is not compressible, store it uncompressed, which is indicated by
+    // the cache size being equal to the uncompressed size in the headers.
+    size_t compressed_bound = ZSTD_compressBound(raw_size);
+    std::unique_ptr<uint8_t[]> compressed(new uint8_t[compressed_bound]);
+    size_t compressed_size = ZSTD_compress(
+        compressed.get(), compressed_bound, raw_ptr, raw_size, 1);
+    char* cache_ptr = raw_ptr;
+    uint32_t cache_size = raw_size;
+    if (!ZSTD_isError(compressed_size) && compressed_size < raw_size) {
+      cache_ptr = reinterpret_cast<char*>(compressed.get());
+      cache_size = static_cast<uint32_t>(compressed_size);
+    }
+    Debug("[compile cache] compressed cache for %s %s: %d -> %d bytes\n",
+          type_name,
+          entry->source_filename,
+          raw_size,
+          cache_size);
+
     uint32_t cache_hash = GetHash(cache_ptr, cache_size);
 
     // Generating headers.
-    std::vector<uint32_t> headers(kHeaderCount);
+    std::array<uint32_t, kHeaderCount> headers;
     headers[kMagicNumberOffset] = kCacheMagicNumber;
     headers[kCodeSizeOffset] = entry->code_size;
     headers[kCacheSizeOffset] = cache_size;
     headers[kCodeHashOffset] = entry->code_hash;
     headers[kCacheHashOffset] = cache_hash;
+    headers[kCacheRawSizeOffset] = raw_size;
 
     // Generate the temporary filename.
     // The temporary file should be placed in a location like:
@@ -459,20 +550,21 @@ void CompileCacheHandler::Persist() {
     Debug(" -> %s\n", mkstemp_req.path);
     Debug("[compile cache] writing cache for %s %s to temporary file %s [%d "
           "%d %d "
-          "%d %d]...",
+          "%d %d %d]...",
           type_name,
           entry->source_filename,
           mkstemp_req.path,
           headers[kMagicNumberOffset],
           headers[kCodeSizeOffset],
           headers[kCacheSizeOffset],
           headers[kCodeHashOffset],
-          headers[kCacheHashOffset]);
+          headers[kCacheHashOffset],
+          headers[kCacheRawSizeOffset]);
 
     // Write to the temporary file.
-    uv_buf_t headers_buf = uv_buf_init(reinterpret_cast<char*>(headers.data()),
-                                       headers.size() * sizeof(uint32_t));
-    uv_buf_t data_buf = uv_buf_init(cache_ptr, entry->cache->length);
+    uv_buf_t headers_buf =
+        uv_buf_init(reinterpret_cast<char*>(headers.data()), kHeaderSize);
+    uv_buf_t data_buf = uv_buf_init(cache_ptr, cache_size);
     uv_buf_t bufs[] = {headers_buf, data_buf};
 
     uv_fs_t write_req;

src/compile_cache.h

@@ -36,9 +36,11 @@ struct CompileCacheEntry {
   bool refreshed = false;
   bool persisted = false;
 
-  // Copy the cache into a new store for V8 to consume. Caller takes
-  // ownership.
-  v8::ScriptCompiler::CachedData* CopyCache() const;
+  // Wrap the cache into a non-owning CachedData for V8 to consume.
+  // The caller takes ownership of the returned wrapper object, while
+  // the underlying buffer remains owned by this entry and must outlive
+  // the consumption of the wrapper.
+  v8::ScriptCompiler::CachedData* WrapCache() const;
   const char* type_name() const;
 };
 
@@ -99,7 +101,9 @@ class CompileCacheHandler {
   static constexpr size_t kCacheSizeOffset = 2;
   static constexpr size_t kCodeHashOffset = 3;
   static constexpr size_t kCacheHashOffset = 4;
-  static constexpr size_t kHeaderCount = 5;
+  static constexpr size_t kCacheRawSizeOffset = 5;
+  static constexpr size_t kHeaderCount = 6;
+  static constexpr size_t kHeaderSize = kHeaderCount * sizeof(uint32_t);
 
   v8::Isolate* isolate_ = nullptr;
   bool is_debug_ = false;

src/module_wrap.cc

@@ -521,8 +521,9 @@ MaybeLocal<Module> ModuleWrap::CompileSourceTextModule(
   }
 
   if (cache_entry != nullptr && cache_entry->cache != nullptr) {
-    // source will take ownership of cached_data.
-    cached_data = cache_entry->CopyCache();
+    // source only takes ownership of the cached_data wrapper - the
+    // underlying buffer is still owned by the compile cache entry.
+    cached_data = cache_entry->WrapCache();
   }
 
   ScriptCompiler::Source source(source_text, origin, cached_data);

src/node_contextify.cc

@@ -1675,8 +1675,9 @@ static MaybeLocal<Function> CompileFunctionForCJSLoader(
         code, filename, CachedCodeType::kCommonJS);
   }
   if (cache_entry != nullptr && cache_entry->cache != nullptr) {
-    // source will take ownership of cached_data.
-    cached_data = cache_entry->CopyCache();
+    // source only takes ownership of the cached_data wrapper - the
+    // underlying buffer is still owned by the compile cache entry.
+    cached_data = cache_entry->WrapCache();
   }
 
   ScriptCompiler::Source source(code, origin, cached_data);