Remove Cache dependency from Metadata (heroku#1649)

The Cache class code is not unit testable locally (due to a dependence on GNU cp behavior) therefore anything that uses the Cache class cannot be unit tested.

If we remove the use of a Cache instance, the metadata code becomes simpler, and we can write tests for it.

The change here is that previously we wrote to the local `<app dir>/vendor/heroku` and then later copied it into the cache. Now we're directly writing into the cache.

Deployed with current `heroku/ruby`:

```
$ git push heroku
Enumerating objects: 666, done.
Counting objects: 100% (666/666), done.
Delta compression using up to 12 threads
Compressing objects: 100% (321/321), done.
Writing objects: 100% (666/666), 177.94 KiB | 88.97 MiB/s, done.
Total 666 (delta 313), reused 660 (delta 310), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (313/313), done.
remote: Updated 105 paths from 0366119
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Building on the Heroku-24 stack
remote: -----> Determining which buildpack to use for this app
remote:  !     Warning: Multiple default buildpacks reported the ability to handle this app. The first buildpack in the list below will be used.
remote:             Detected buildpacks: Ruby,Node.js
remote:             See https://devcenter.heroku.com/articles/buildpacks#buildpack-detect-order
remote: -----> Ruby app detected
remote: -----> Installing bundler 2.5.23
remote: -----> Removing BUNDLED WITH version in the Gemfile.lock
remote: -----> Compiling Ruby/Rails
remote: -----> Using Ruby version: ruby-3.2.4
remote: -----> Installing dependencies using bundler 2.5.23
remote:        Running: BUNDLE_WITHOUT='development:test' BUNDLE_PATH=vendor/bundle BUNDLE_BIN=vendor/bundle/bin BUNDLE_DEPLOYMENT=1 bundle install -j4
remote:        Fetching gem metadata from https://rubygems.org/.........
remote:        Fetching rake 13.3.0
remote:        Installing rake 13.3.0
remote:        Fetching concurrent-ruby 1.3.5
remote:        Fetching bigdecimal 3.2.2
remote:        Fetching base64 0.3.0
remote:        Fetching benchmark 0.4.1
```

Modified Ruby version and re-deploy:

```
$ git push heroku
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 12 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 293 bytes | 293.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Updated 105 paths from 0f9d4c6
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Building on the Heroku-24 stack
remote: -----> Using buildpack: https://github.com/heroku/heroku-buildpack-ruby#schneems/metadata-too
remote: -----> Ruby app detected
remote: -----> Installing bundler 2.5.23
remote: -----> Removing BUNDLED WITH version in the Gemfile.lock
remote: -----> Compiling Ruby/Rails
remote: -----> Using Ruby version: ruby-3.3.9
remote:        Loading bundler cache
remote:        Ruby version change detected. Clearing bundler cache.
remote:        Old: ruby 3.2.4 (2024-04-23 revision af471c0e01) [x86_64-linux]
remote:        New: ruby 3.3.9 (2025-07-24 revision f5c772fc7c) [x86_64-linux]
remote:        Purging bundler cache
remote: -----> Installing dependencies using bundler 2.5.23
remote:        Running: BUNDLE_WITHOUT='development:test' BUNDLE_PATH=vendor/bundle BUNDLE_BIN=vendor/bundle/bin BUNDLE_DEPLOYMENT=1 bundle install -j4
```

(Note that "Ruby version change detected").

Re-deploy with new change (to ensure the metadata cache correctly persisted):

```
$ git push heroku
Enumerating objects: 1, done.
Counting objects: 100% (1/1), done.
Writing objects: 100% (1/1), 188 bytes | 188.00 KiB/s, done.
Total 1 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Updated 105 paths from 0f9d4c6
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Building on the Heroku-24 stack
remote: -----> Using buildpack: https://github.com/heroku/heroku-buildpack-ruby#schneems/metadata-too
remote: -----> Ruby app detected
remote: -----> Installing bundler 2.5.23
remote: -----> Removing BUNDLED WITH version in the Gemfile.lock
remote: -----> Compiling Ruby/Rails
remote: -----> Using Ruby version: ruby-3.3.9
remote:        Loading bundler cache
remote: -----> Installing dependencies using bundler 2.5.23
remote:        Running: BUNDLE_WITHOUT='development:test' BUNDLE_PATH=vendor/bundle BUNDLE_BIN=vendor/bundle/bin BUNDLE_DEPLOYMENT=1 bundle install -j4
remote:        Bundle complete! 13 Gemfile dependencies, 87 gems now installed.
remote:        Gems in the groups 'development' and 'test' were not installed.
remote:        Bundled gems are installed into `./vendor/bundle`
remote:        Bundle completed (1.01s)
remote:        Cleaning up the bundler cache.
remote:        Running: bundle list
remote:        Gems included by the bundle:
```

Author: schneems

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Internal refactor: Remove Cache class dependency from Metadata class (https://github.com/heroku/heroku-buildpack-ruby/pull/1649)
 - Improve message on `bin/detect` failure to include the list of files in the root directory (https://github.com/heroku/heroku-buildpack-ruby/pull/1647)
 
 ## [v322] - 2025-09-29

lib/language_pack/base.rb

@@ -26,7 +26,8 @@ def initialize(app_path: , cache_path: , gemfile_lock: )
     @app_path = app_path
     @stack         = ENV.fetch("STACK")
     @cache         = LanguagePack::Cache.new(cache_path)
-    @metadata      = LanguagePack::Metadata.new(@cache)
+    @metadata      = LanguagePack::Metadata.new(cache_path: cache_path)
+    @new_app       = @metadata.empty?
     @bundler_cache = LanguagePack::BundlerCache.new(@cache, @stack)
     @fetchers      = {:buildpack => LanguagePack::Fetcher.new(VENDOR_URL) }
     @arch = get_arch
@@ -47,6 +48,10 @@ def get_arch
     arch
   end
 
+  def new_app?
+    @new_app
+  end
+
   def self.===(app_path)
     raise "must subclass"
   end

lib/language_pack/metadata.rb

@@ -1,59 +1,43 @@
 require "language_pack"
 require "language_pack/base"
 
+# Store data about the build in the cache
+#
+# Uses `<cache_path>/vendor/heroku` as the metadata directory. Which
+# is special cased in cache clearing code to be durable. This allows
+# for persistant generated data such as SECRET_KEY_BASE that would otherwise
+# cause session invalidation if it changed unexpectedly between deploys.
 class LanguagePack::Metadata
-  FOLDER = "vendor/heroku"
-
-  def initialize(cache)
-    if cache
-      @cache = cache
-      @cache.load FOLDER
-    end
-  end
-
-  def [](key)
-    read(key)
+  def initialize(cache_path: )
+    @dir = Pathname(cache_path)
+      .join("vendor")
+      .join("heroku")
+      .tap(&:mkpath)
   end
 
-  def []=(key, value)
-    write(key, value)
+  def empty?
+    @dir.children.empty?
   end
 
   def read(key)
-    full_key = "#{FOLDER}/#{key}"
-    File.read(full_key).strip if exists?(key)
+    @dir.join(key).read&.strip
   end
 
   def exists?(key)
-    full_key = "#{FOLDER}/#{key}"
-    File.exist?(full_key) && !Dir.exist?(full_key)
+    @dir.join(key).file?
   end
-  alias_method :include?, :exists?
 
-  def write(key, value, isave = true)
-    FileUtils.mkdir_p(FOLDER)
-
-    full_key = "#{FOLDER}/#{key}"
-    File.open(full_key, 'w') {|f| f.puts value }
-    save if isave
-
-    return true
-  end
-
-  def touch(key)
-    write(key, "true")
+  def write(key, value)
+    @dir.join(key).write(value)
   end
 
   def fetch(key)
-    return read(key) if exists?(key)
-
-    value = yield
-
-    write(key, value.to_s)
-    return value
-  end
-
-  def save(file = FOLDER)
-    @cache ? @cache.add(file) : false
+    if exists?(key)
+      read(key)
+    else
+      value = yield
+      write(key, value.to_s)
+      value
+    end
   end
 end

lib/language_pack/ruby.rb

@@ -192,7 +192,7 @@ def warn_bad_binstubs
 
   def default_malloc_arena_max?
     return true if @metadata.exists?("default_malloc_arena_max")
-    return @metadata.touch("default_malloc_arena_max") if new_app?
+    return @metadata.write("default_malloc_arena_max", "true") if new_app?
 
     return false
   end
@@ -613,10 +613,6 @@ def install_ruby(install_path: )
     error message
   end
 
-  def new_app?
-    @new_app ||= !app_path.join("vendor").join("heroku").exist?
-  end
-
   # find the ruby install path for its binstubs during build
   # @return [String] resulting path or empty string if ruby is not vendored
   def ruby_install_binstub_path(ruby_layer_path = ".")
@@ -1086,7 +1082,6 @@ def load_bundler_cache
 
     full_ruby_version       = run_stdout(%q(ruby -v)).strip
     rubygems_version        = run_stdout(%q(gem -v)).strip
-    heroku_metadata         = "vendor/heroku"
     old_rubygems_version    = nil
     ruby_version_cache      = "ruby_version"
     buildpack_version_cache = "buildpack_version"
@@ -1119,13 +1114,11 @@ def load_bundler_cache
       purge_bundler_cache
     end
 
-    FileUtils.mkdir_p(heroku_metadata)
-    @metadata.write(ruby_version_cache, full_ruby_version, false)
-    @metadata.write(buildpack_version_cache, BUILDPACK_VERSION, false)
-    @metadata.write(bundler_version_cache, bundler.version, false)
-    @metadata.write(rubygems_version_cache, rubygems_version, false)
-    @metadata.write(stack_cache, @stack, false)
-    @metadata.save
+    @metadata.write(ruby_version_cache, full_ruby_version)
+    @metadata.write(buildpack_version_cache, BUILDPACK_VERSION)
+    @metadata.write(bundler_version_cache, bundler.version)
+    @metadata.write(rubygems_version_cache, rubygems_version)
+    @metadata.write(stack_cache, @stack)
   end
 
   def purge_bundler_cache(stack = nil)

spec/hatchet/getting_started_spec.rb

@@ -4,18 +4,26 @@
   it "works on Heroku-24" do
     Hatchet::Runner.new("ruby-getting-started", stack: "heroku-24").deploy do |app|
       expect(app.output).to_not include("Purging Cache")
+      expect(app.output).to include("Fetching puma")
+
+      secret_key_base = app.run("echo $SECRET_KEY_BASE")
 
       # Re-deploy with cache
       run!("git commit --allow-empty -m empty")
       app.push!
 
+      # Assert used cached gems
+      expect(app.output).to_not include("Fetching puma")
+
       # Assert no warnings from `cp`
       # https://github.com/heroku/heroku-buildpack-ruby/pull/1586/files#r2064284286
       expect(app.output).to_not include("cp --help")
       expect(app.run("which ruby").strip).to eq("/app/bin/ruby")
 
       environment_variables = app.run("env")
       expect(environment_variables).to match("PUMA_PERSISTENT_TIMEOUT")
+      # Assert cached value persisted
+      expect(environment_variables).to match("SECRET_KEY_BASE=#{secret_key_base}")
 
       profile_d = app.run("cat .profile.d/ruby.sh")
         .strip

spec/helpers/metadata_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+describe "Metadata" do
+  it "can read and write to the metadata" do
+    Dir.mktmpdir do |dir|
+      metadata = LanguagePack::Metadata.new(cache_path: dir)
+      expect(metadata.empty?).to be_truthy
+
+      expect(metadata.exists?("test")).to be_falsey
+      metadata.write("test", "test")
+
+      expect(metadata.exists?("test")).to be_truthy
+      expect(metadata.read("test")).to eq("test")
+      expect(metadata.empty?).to be_falsey
+    end
+  end
+
+  it "can write a value conditionally" do
+    Dir.mktmpdir do |dir|
+      metadata = LanguagePack::Metadata.new(cache_path: dir)
+      called = false
+
+      expect(metadata.empty?).to be_truthy
+      expect(metadata.exists?("test")).to be_falsey
+      metadata.fetch("test") do
+        called = true
+        "test"
+      end
+      expect(metadata.read("test")).to eq("test")
+      expect(called).to be_truthy
+      expect(metadata.empty?).to be_falsey
+    end
+  end
+end