Set PUMA_PERSISTENT_TIMEOUT for Rails, add Puma version warnings and errors. (heroku#1645)

* Refactor default config vars

* Fix PUMA_PERSISTENT_TIMEOUT not working on Rails

Rails does not inherit from Rack, they both inherit from Ruby.

GUS-W-19585440

* Add test for .profile.d/ (launch/runtime) env

* Set default PUMA_PERSISTENT_TIMEOUT profile.d

* Harden .profile.d check

By checking the full output, it means any change will cause the build to fail rather than needing to explicitly check individual files.

* Fix spelling

* Refactor default_config_vars

Standardize on using `out` as the variable name. Add documentation stating where it's inheriting from.

* Remove outdated comment

The "buildpack-env-args" refers to the ability of customers to have access to their config vars at build time, which used to not be possible. It has been on and the default for many years now. We can remove the comment.

The comment also assumed implementation details of how it would work once implemented. The `||=` here means that any buildpacks that export an environment variable before us will take precedence, which is behavior that we want. These `default_config_vars` should not take precedence over another buildpack explicitly writing an environment variable to their `export`.

* Refactor `default_env_vars` method out

This method is used in a handful of places. We can replace that usage with the literal contents.

* Remove `config_vars` from bin/release

This field is not currently documented at https://devcenter.heroku.com/articles/buildpack-api#bin-release, but it is used for setting config vars for customers. The caveat is that it only affects apps on the first push, which isn't very useful. That's why it's not even documented anymore.

The "correct" way to set an environment variable is:

- `.profile.d/<script>.sh` Sets the value at launch/runtime
- `export` Sets the value at build time for future buildpacks

Previously, the `def default_config_vars` was used in relationship with `bin/release` to set `config_vars`. But, since that's not used (as of this commit) it is repurposed as an interface for writing default values to `.profile.d` scripts. All these values were already being written, but now it's centralized (i.e. this .profile.d part of the change is a literal refactor, it doesn't change any behavior).

There are some implications with the API: Any value that comes out of `def default_config_vars` will be persisted to disk and will take precedent if someone runs `heroku config:unset <env var>` for example. Previously, the values also contained the user's environment variable value i.e. if someone set `heroku config:set RAILS_ENV=my_custom_env` then that change would be propagated to `bin/release`. Now we don't want to write a value like  `        export RACK_ENV=${RACK_ENV:-my_custom_env}` otherwise. We want the default to fall back to OUR default. Therefore only literal values should be used in this API. That part is unexpected and unsafe, so I'm likely going to move/change how the interface works. But I will do that in future commits.

* Add a test for the current buildpack `export`

The `export` file writes environment variables that are visible to future buildpacks. This adds a test to assert the current behavior.

* Add default_config_vars to export automatically

* Remove set empty env var

This env var was set for Bundler <= 2.1.4 compat in this commit heroku@655e246 which explains the behavior.

It has since been reduced over the years to no longer set it to a `1` and instead set it to an empty string. It's also only exported and not set for build time, therefore it can be safely removed.

As to **why** it isn't a problem any more. We list our oldest available Ruby version as 3.1:

https://devcenter.heroku.com/articles/ruby-support-reference#unsupported-ruby-versions

And the default bundler version for that version of ruby is 2.3 which is > 2.1

```
$ gem list | grep bundle
bundler (2.6.9, 2.5.22, default: 2.3.27)
```

* Whitespace

* Flatten inheritance

The `default_config_vars` was using inheritance and calling `super`, and it was very difficult to follow what actual behavior was. This commit flattens the behavior and puts it all into `ruby.rb`.

* Remove un-used inheritance

With the `def default_config_vars` logic flattened, these files no longer serve a purpose and can be deleted.

* Remove un-needed method definition

* Introduce isolated DefaultEnvVars.call function

This provides more protection (isolation) than the comment above `def default_config_vars` to help protect future modification from accidentally persisting customer config vars to disk.

* Replace logic with DefaultEnvVars.call function

* Refactor

* Apply suggestions from code review

Signed-off-by: Richard Schneeman <richard.schneeman+no-recruiters@gmail.com>

---------

Signed-off-by: Richard Schneeman <richard.schneeman+no-recruiters@gmail.com>

Author: schneems

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+- Set `export PUMA_PERSISTENT_TIMEOUT=95` to match recommended router 2.0 settings for Rails applications (https://github.com/heroku/heroku-buildpack-ruby/pull/1645)
+- Warn when using Puma prior to 7.0.0 for Router 2.0 compatibility (https://github.com/heroku/heroku-buildpack-ruby/pull/1645)
+- Error when using Puma 7.0.0 to 7.0.2 (inclusive) to prevent runtime error with `PUMA_PERSISTENT_TIMEOUT` (https://github.com/heroku/heroku-buildpack-ruby/pull/1645)
+- The `config_vars` field is no longer set in `bin/release`, this feature only affected the first deploy and is redundant with `.profile.d` usage that already exists. (https://github.com/heroku/heroku-buildpack-ruby/pull/1645)
 
 ## [v321] - 2025-09-16
 
@@ -10,7 +14,7 @@
 
 ## [v320] - 2025-09-09
 
-- Set `export PUMA_PERSISTENT_TIMEOUT=95` to match recommended router 2.0 settings (https://github.com/heroku/heroku-buildpack-ruby/pull/1641)
+- Set `export PUMA_PERSISTENT_TIMEOUT=95` to match recommended router 2.0 settings for Rack applications (https://github.com/heroku/heroku-buildpack-ruby/pull/1641)
 
 ## [v319] - 2025-08-27
 

changelogs/unreleased/persistent-timeout-rails.md

@@ -0,0 +1,16 @@
+## Rails apps now have `PUMA_PERSISTENT_TIMEOUT=95` set by default
+
+Previously, this setting was only applied to [Rack applications](https://devcenter.heroku.com/changelog-items/3391). With this change, all Ruby applications now have the `PUMA_PERSISTENT_TIMEOUT` environment variable set to a default value of `95`.
+
+Puma [7.0.3+](https://github.com/puma/puma/pull/3378) introduced the ability to configure the `persistent_timeout` value via an environment variable. Router 2.0 uses an idle timeout value of 90s https://devcenter.heroku.com/articles/http-routing#keepalives. To avoid a situation where a request is sent right before Puma closes the connection, the value needs to be slightly higher than the Router's value.
+
+Applications that are not on Puma 7.0.3+ can use it manually in their `config/puma.rb` file:
+
+```ruby
+# config/puma.rb
+
+# Only required for Puma 6 and below
+persistent_timeout(ENV.fetch("PUMA_PERSISTENT_TIMEOUT") { 95 }.to_i)
+```
+
+Other web server users can use this as a stable interface to retrieve a suggested idle timeout setting.

lib/language_pack.rb

@@ -22,7 +22,7 @@ def self.gemfile_lock(app_path: )
 
   # detects which language pack to use
   def self.detect(app_path:, cache_path:, gemfile_lock: )
-    pack_klass = [ Rails8, Rails7, Rails6, Rails5, Rails42, Rails41, Rails4, Rails3, Rails2, Rack, Ruby ].detect do |klass|
+    pack_klass = [ Rails8, Rails7, Rails6, Rails5, Rails4, Rails3, Rails2, Rack, Ruby ].detect do |klass|
       klass.use?
     end
 
@@ -48,7 +48,9 @@ def self.detect(app_path:, cache_path:, gemfile_lock: )
 require "language_pack/helpers/bundle_list"
 require "language_pack/helpers/rake_runner"
 require "language_pack/helpers/rails_runner"
+require "language_pack/helpers/puma_warn_error"
 require "language_pack/helpers/bundler_wrapper"
+require "language_pack/helpers/default_env_vars"
 require "language_pack/helpers/outdated_ruby_version"
 require "language_pack/helpers/download_presence"
 require "language_pack/installers/heroku_ruby_installer"
@@ -58,8 +60,6 @@ def self.detect(app_path:, cache_path:, gemfile_lock: )
 require "language_pack/rails2"
 require "language_pack/rails3"
 require "language_pack/rails4"
-require "language_pack/rails41"
-require "language_pack/rails42"
 require "language_pack/rails5"
 require "language_pack/rails6"
 require "language_pack/rails7"

lib/language_pack/base.rb

@@ -62,13 +62,6 @@ def default_addons
     raise "must subclass"
   end
 
-  # config vars to be set on first push.
-  # @return [Hash] the result
-  # @not: this is only set the first time an app is pushed to.
-  def default_config_vars
-    raise "must subclass"
-  end
-
   # process types to provide for the app
   # Ex. for rails we provide a web process
   # @return [Hash] the result
@@ -96,7 +89,6 @@ def compile
   def build_release
     release = {}
     release["addons"]                = default_addons
-    release["config_vars"]           = default_config_vars
     release["default_process_types"] = default_process_types
 
     release

lib/language_pack/helpers/default_env_vars.rb

@@ -0,0 +1,52 @@
+
+module LanguagePack::Helpers::DefaultEnvVars
+  # Returns a hash of default environment variables for the given inputs
+  #
+  # Values will be written to disk as defaults
+  #
+  # i.e. `export RAILS_ENV=${RAILS_ENV:-production}`
+  #
+  # Therefore it's important that we don't return any values from user provided config vars
+  # or customers will not be able to `heroku config:unset` them.
+  #
+  # @param is_jruby [Boolean] whether the app is using JRuby
+  # @param rack_version [Gem::Version] the version of the rack gem
+  # @param rails_version [Gem::Version] the version of the rails gem
+  # @param secret_key_base [String] the secret key base for the app
+  # @return [Hash] a hash of default environment variables
+  def self.call(is_jruby:, rack_version: , rails_version:, secret_key_base:)
+    out = {}
+    out["LANG"] = "en_US.UTF-8"
+    out["PUMA_PERSISTENT_TIMEOUT"] = "95"
+
+    if is_jruby
+      out["JRUBY_OPTS"] = "-Xcompile.invokedynamic=false"
+    end
+
+    if rack_version
+      out["RACK_ENV"] = "production"
+    end
+
+    if rails_version
+      out["RAILS_ENV"] = "production"
+    end
+
+    if rails_version&. >= Gem::Version.new("4.1.0.beta1")
+      if secret_key_base = secret_key_base&.to_s
+        out["SECRET_KEY_BASE"] = secret_key_base
+      else
+        raise ArgumentError, "secret_key_base is required for rails 4.1+. Provided: #{secret_key_base.inspect}"
+      end
+    end
+
+    if rails_version&. >= Gem::Version.new("4.2.0")
+      out["RAILS_SERVE_STATIC_FILES"] = "enabled"
+    end
+
+    if rails_version&. >= Gem::Version.new("5.0.0")
+      out["RAILS_LOG_TO_STDOUT"] = "enabled"
+    end
+
+    out
+  end
+end

lib/language_pack/helpers/puma_warn_error.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Checks for Puma specific warnings and errors
+class LanguagePack::Helpers::PumaWarnError
+  attr_reader :warnings, :error, :puma_version
+
+  def initialize(puma_version:, env:)
+    @warnings = []
+    @error = nil
+    @env = env
+    @puma_version = puma_version
+
+    warn_router_2_0_compatibility
+    error_persistent_timeout
+  end
+
+  private def warn_router_2_0_compatibility
+    return if @puma_version >= Gem::Version.new("7.0.3")
+    warnings << <<~WARNING
+      Heroku recommends using Puma 7.0.3+ for compatibility with Router 2.0
+
+      Please upgrade your application to Puma 7.0.3+ by running the following commands:
+
+      ```
+      $ gem install puma
+      $ bundle update puma
+      $ git add Gemfile.lock && git commit -m "Upgrade Puma to 7.0.3+"
+      ```
+    WARNING
+  end
+
+  private def error_persistent_timeout
+    return if @puma_version >= Gem::Version.new("7.0.3")
+    return if @puma_version < Gem::Version.new("7.0.0")
+    # If they manually set it, it is likely being used in their `config/puma.rb` file
+    return if @env["PUMA_PERSISTENT_TIMEOUT"]
+
+    @error = <<~ERROR
+      Your application is using Puma #{puma_version}.
+
+      This has a known issue with the `PUMA_PERSISTENT_TIMEOUT` environment variable.
+
+      This is fixed in Puma 7.0.3+ via https://github.com/puma/puma/pull/3749.
+      Please upgrade your application to Puma 7.0.3+ by running the following commands:
+
+      ```
+      $ gem install puma
+      $ bundle update puma
+      $ git add Gemfile.lock && git commit -m "Upgrade Puma to 7.0.3+"
+      ```
+    ERROR
+  end
+end

lib/language_pack/rack.rb

@@ -14,13 +14,6 @@ def name
     "Ruby/Rack"
   end
 
-  def default_config_vars
-    out = super
-    out["RACK_ENV"] = env("RACK_ENV") || "production"
-    out["PUMA_PERSISTENT_TIMEOUT"] = env("PUMA_PERSISTENT_TIMEOUT") || "95"
-    out
-  end
-
   def default_process_types
     # let's special case thin here if we detect it
     web_process = bundler.has_gem?("thin") ?
@@ -31,12 +24,4 @@ def default_process_types
       "web" => web_process
     })
   end
-
-private
-
-  # sets up the profile.d script for this buildpack
-  def setup_profiled(**args)
-    super(**args)
-    set_env_default "RACK_ENV", "production"
-  end
 end

lib/language_pack/rails2.rb

@@ -23,21 +23,6 @@ def name
     "Ruby/Rails"
   end
 
-  def default_env_vars
-    {
-      "RAILS_ENV" => "production",
-      "RACK_ENV" => "production"
-    }
-  end
-
-  def default_config_vars
-    config_vars = super
-    default_env_vars.map do |key, value|
-      config_vars[key] = env(key) || value
-    end
-    config_vars
-  end
-
   def default_process_types
     web_process = bundler.has_gem?("thin") ?
       "bundle exec thin start -e $RAILS_ENV -p ${PORT:-5000}" :
@@ -76,12 +61,4 @@ def install_plugins
     topic "Rails plugin injection"
     LanguagePack::Helpers::PluginsInstaller.new(plugins).install
   end
-
-  # sets up the profile.d script for this buildpack
-  def setup_profiled(**args)
-    super(**args)
-    default_env_vars.each do |key, value|
-      set_env_default key, value
-    end
-  end
 end

lib/language_pack/rails3.rb

@@ -30,7 +30,11 @@ def default_process_types
   end
 
   def rake_env
-    default_env_vars.merge("RAILS_GROUPS" => "assets").merge(super)
+    {
+      "RAILS_ENV" => "production",
+      "RACK_ENV" => "production",
+      "RAILS_GROUPS" => "assets",
+    }.merge(super)
   end
 
   def compile

lib/language_pack/rails4.rb

@@ -11,7 +11,7 @@ def self.use?
     rails_version = bundler.gem_version('railties')
     return false unless rails_version
     is_rails4 = rails_version >= Gem::Version.new('4.0.0.beta') &&
-                rails_version <  Gem::Version.new('4.1.0.beta1')
+                rails_version <  Gem::Version.new('5.x')
     return is_rails4
   end