Better errors on bootstrap failure (heroku#1629)

* Show original error on bootstrap failed download

Current

```
curl --fail --retry 3 --retry-connrefused --connect-timeout "3" --silent --location -o "/tmp/ruby.tgz" "https://heroku-buildpack-ruby.s3.us-east-1.amazonaws.com/heroku-20/ruby-3.3.9.tgz"; echo "Done $?"
# => Done 22
```

After

```
curl --fail --show-error --retry 3 --retry-connrefused --connect-timeout "3" --silent --location -o "/tmp/ruby.tgz" "https://heroku-buildpack-ruby.s3.us-east-1.amazonaws.com/heroku-20/ruby-3.3.9.tgz"; echo "Done $?"
# => curl: (22) The requested URL returned error: 404
# => Done 22
```

Ref heroku#1628

* Don't silently ignore bash failures

This output reported in heroku#1628 is confusing.

```
remote: /tmp/buildpackLSI7t/bin/compile: line 35:   Failed to download a Ruby executable for bootstrapping!
remote: 
remote:   This is most likely a temporary internal error. If the problem
remote:   persists, make sure that you are not running a custom or forked
remote:   version of the Heroku Ruby buildpack which may need updating.
remote: 
remote:   url: https://heroku-buildpack-ruby.s3.us-east-1.amazonaws.com/heroku-20/ruby-3.3.9.tgz
remote: /tmp/tmp.PDOWE1VL34/bin/ruby: File name too long
```

Even though that function exits non-zero, it doesn't propagate due to a missing `set -e` at the top level. This ensures all top level `bin/` executables exit on failure.

* Explicit heroku-20 check and failure

Issue heroku#1628 shows that it's unclear when a Ruby version cannot be found on an unsupported stack, and that it is expected behavior. To avoid this confusion, we can explicitly error when using a recently EOL stack.

* Better stack error message

This guards against execution using unknown or unexpected stacks. In addition, its behavior is tested.

* Fix shellcheck

When I added this function with local variable:

```
function checks::ensure_supported_stack() {
	local stack="${1}"
```

It triggered this shellcheck failure on an unrelated line:

```
$ shellcheck bin/support/bash_functions.sh -x

In bin/support/bash_functions.sh line 35:
  if [ "$STACK" == "heroku-24" ]; then
        ^----^ SC2153 (info): Possible misspelling: STACK may not be assigned. Did you mean stack?
```

This fixes the lint.

Author: schneems

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Explicitly error on end-of-life (EOL) stack `heroku-20` (https://github.com/heroku/heroku-buildpack-ruby/pull/1629)
 - Default Ruby version is now 3.3.9 (https://github.com/heroku/heroku-buildpack-ruby/pull/1624)
 
 ## [v315] - 2025-07-24

bin/compile

@@ -2,6 +2,8 @@
 # The actual compilation code lives in `bin/support/ruby_compile`. This file instead
 # bootstraps the ruby needed and then executes `bin/support/ruby_compile`
 
+set -euo pipefail
+
 BUILD_DIR=$1
 CACHE_DIR=$2
 ENV_DIR=$3
@@ -11,6 +13,8 @@ BUILDPACK_DIR=$(dirname "$BIN_DIR")
 # shellcheck source=bin/support/bash_functions.sh
 source "$BIN_DIR/support/bash_functions.sh"
 
+checks::ensure_supported_stack "${STACK:?Required env var STACK is not set}"
+
 bootstrap_ruby_dir=$(install_bootstrap_ruby "$BIN_DIR" "$BUILDPACK_DIR")
 export PATH="$bootstrap_ruby_dir/bin/:$PATH"
 unset GEM_PATH

bin/detect

@@ -1,4 +1,6 @@
-#!/bin/sh
+#!/usr/bin/env bash
+
+set -euo pipefail
 
 APP_DIR=$1
 

bin/support/bash_functions.sh

@@ -30,9 +30,10 @@ install_bootstrap_ruby()
 {
   local bin_dir=$1
   local buildpack_dir=$2
+  local stack="${STACK:?Required env var STACK is not set}"
 
   # Multi-arch aware stack support
-  if [ "$STACK" == "heroku-24" ]; then
+  if [ "$stack" == "heroku-24" ]; then
     local arch
     arch=$(dpkg --print-architecture)
     local heroku_buildpack_ruby_dir="$buildpack_dir/vendor/ruby/$STACK/$arch"
@@ -154,3 +155,43 @@ compile_buildpack_v2()
   fi
 }
 
+# After a stack is EOL, updates to the buildpack may fail with unexpected or unhelpful errors.
+# This can happen when the buildpack is being used off of the platform such as with `dokku`
+# which is not officially supported.
+function checks::ensure_supported_stack() {
+	local stack="${1}"
+
+	case "${stack}" in
+		# When removing support from a stack, move it to the bottom of the list
+		heroku-22 | heroku-24)
+			return 0
+			;;
+		heroku-18 | heroku-20)
+			# This error will only ever be seen on non-Heroku environments, since the
+			# Heroku build system rejects builds using EOL stacks.
+			cat <<-EOF
+				Error: The '${stack}' stack is no longer supported.
+
+				This buildpack no longer supports the '${stack}' stack since it has
+				reached its end-of-life:
+				https://devcenter.heroku.com/articles/stack#stack-support-details
+
+				Upgrade to a newer stack to continue using this buildpack.
+			EOF
+			exit 1
+			;;
+		*)
+			cat <<-EOF
+				Error: The '${stack}' stack isn't recognised.
+
+				This buildpack doesn't recognise or support the '${stack}' stack.
+
+				If '${stack}' is a valid stack, make sure that you are using the latest
+				version of this buildpack and haven't pinned to an older release:
+				https://devcenter.heroku.com/articles/managing-buildpacks#view-your-buildpacks
+				https://devcenter.heroku.com/articles/managing-buildpacks#classic-buildpacks-references
+			EOF
+			exit 1
+			;;
+	esac
+}

bin/support/download_ruby

@@ -51,7 +51,7 @@ fi
 
 mkdir -p "$RUBY_BOOTSTRAP_DIR"
 
-curl_retry_on_18 --fail --retry 3 --retry-connrefused --connect-timeout "${CURL_CONNECT_TIMEOUT:-3}" --silent --location -o "$RUBY_BOOTSTRAP_DIR/ruby.tgz" "$heroku_buildpack_ruby_url" || {
+curl_retry_on_18 --fail --show-error --retry 3 --retry-connrefused --connect-timeout "${CURL_CONNECT_TIMEOUT:-3}" --silent --location -o "$RUBY_BOOTSTRAP_DIR/ruby.tgz" "$heroku_buildpack_ruby_url" || {
 cat<<EOF
   Failed to download a Ruby executable for bootstrapping!
 

bin/test

@@ -2,6 +2,8 @@
 # The actual `bin/test-compile` code lives in `bin/ruby_test-compile`. This file instead
 # bootstraps the ruby needed and then executes `bin/ruby_test-compile`
 
+set -euo pipefail
+
 BIN_DIR=$(cd "$(dirname "$0")" || exit; pwd) # absolute path
 BUILDPACK_DIR=$(dirname "$BIN_DIR")
 

spec/unit/bash_functions_spec.rb

@@ -1,6 +1,23 @@
 require 'spec_helper'
 
 describe "Bash functions" do
+    it "fails on old stacks" do
+      out = exec_with_bash_functions(<<~EOM, raise_on_fail: false)
+        checks::ensure_supported_stack "heroku-20"
+      EOM
+
+      expect($?.success?).to be_falsey, "Expected command failure but got unexpected success. Output:\n\n#{out}"
+      expect(out).to include("This buildpack no longer supports the 'heroku-20' stack")
+    end
+
+    it "knows the latest stacks" do
+      out = exec_with_bash_functions(<<~EOM)
+        checks::ensure_supported_stack "heroku-24"
+      EOM
+
+      expect(out).to be_empty
+    end
+
     it "Detects jruby in the Gemfile.lock" do
       Dir.mktmpdir do |dir|
         dir = Pathname(dir)
@@ -9,7 +26,6 @@
              ruby 2.5.7p001 (jruby 9.2.13.0)
         EOM
 
-
         out = exec_with_bash_functions <<~EOM
           which_java()
           {
@@ -75,7 +91,7 @@ def bash_functions_file
     root_dir.join("bin", "support", "bash_functions.sh")
   end
 
-  def exec_with_bash_functions(code, stack: "heroku-24")
+  def exec_with_bash_functions(code, stack: "heroku-24", raise_on_fail: true)
     contents = <<~EOM
       #! /usr/bin/env bash
       set -eu
@@ -103,21 +119,23 @@ def exec_with_bash_functions(code, stack: "heroku-24")
       out = "Command timed out"
       success = false
     end
-    unless success
+
+    if raise_on_fail && !success
       message = <<~EOM
         Contents:
 
         #{contents.lines.map.with_index { |line, number| "  #{number.next} #{line.chomp}"}.join("\n") }
 
-        Expected running script to succeed, but it did not
+        Expected running script to succeed, but it did not. If this was expected, use `raise_on_fail: false`
 
         Output:
 
           #{out}
       EOM
 
       raise message
+    else
+      out
     end
-    out
   end
 end