Enhance Bootstrap failures when due to missing snapshot or bootstrap PHP binary

[schneems]

Expected

When setting a custom HEROKU_PHP_PLATFORM_REPOSITORIES , in the event of a failed build, I have enough information to trace the internal logic, so I can debug the problem.

Beyond being used for buildpack dev, this is a documented feature used by customers to host their own extensions https://github.com/heroku/heroku-buildpack-php?tab=readme-ov-file#custom-platform-repositories.

Actual

When setting a php-min for bootstrapping, that is not available in the given S3 bucket the error message is this:

remote: -----> Bootstrapping...
remote:        NOTICE: Default platform repository snapshot not available.
remote:
remote:  !     ERROR: Failed to download minimal PHP 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 PHP buildpack which may need updating.
remote:
remote:  !     Push rejected, failed to compile PHP app.
remote:
remote:  !     Push failed
remote: Verifying deploy...
remote:
remote: !	Push rejected to thawing-inlet-74685.
remote:

This hints that the snapshot is not available, but does not tell us what URL it looked up. It tells us that the PHP it tried to bootstrap with was not downloadable, but it does not tell us the URL it tried to download from. I hit this in https://github.com/heroku/heroku-buildpack-php/pull/799/files#r2085192167.

Suggestion

In this failure mode, the problem is that the snapshot has not yet been uploaded to the stable bucket of S3. Which means that the following URLs do not exist. When a URL doesn't exist it could be because the base url is wrong or misconfigured, the stack or suffix is wrong or misconfigured, the snapshot URL is incorrect, or it's correct but is missing the version. To fully capture each of these failure modes we can emit the desired URL (the min-php) and where we got the information (or didn't in this case) of where the snapshot lives:

• https://lang-php.s3.us-east-1.amazonaws.com/dist-heroku-24-amd64-stable/packages-c0accbcb71bcc1d97eda4015364b8f223cbd965855eb11e3f643455f2513bad3.json
• https://lang-php.s3.us-east-1.amazonaws.com/dist-heroku-24-amd64-stable/php-min-8.3.21.tar.gz

We could add this information to the build output:

remote:        NOTICE: Default platform repository snapshot not available (`c0accbcb71bcc1d97eda4015364b8f223cbd965855eb11e3f643455f2513bad3`)
remote:
remote:  !     ERROR: Failed to download minimal PHP 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 PHP buildpack which may need updating.
remote:  !
remote:  !     - Bootstrap URL (not found): https://lang-php.s3.us-east-1.amazonaws.com/dist-heroku-24-amd64-stable/php-min-8.3.21.tar.gz
remote:  !     - Snapshot URL (not found): https://lang-php.s3.us-east-1.amazonaws.com/dist-heroku-24-amd64-stable/packages-c0accbcb71bcc1d97eda4015364b8f223cbd965855eb11e3f643455f2513bad3.json
remote:  ! 
remote:  !
remote:  !     Push rejected, failed to compile PHP app.
remote:
remote:  !     Push failed
remote: Verifying deploy...
remote:
remote: !	Push rejected to thawing-inlet-74685.
remote:

In a related note, when this initial check that produces the warning message is emitted, we could add an else check here https://github.com/heroku/heroku-buildpack-php/blob/ff2661599d1cf81588c7eeb8d02539277bf5dfb4/bin/compile#L245 and fail early if either there's no custom HEROKU_PHP_PLATFORM_REPOSITORIES or none of the repos have a platform repository and no fallback is allowed.

I also noticed that HEROKU_PHP_PLATFORM_REPOSITORY_SNAPSHOT_FALLBACK is used in this linked code but never mentioned in any documentation.

[baldhadhaval08]

@schneems I'm also facing same issue. Have you find any solution?

[schneems]

@baldhadhaval08 IIRC the issue was that the code was not yet "promoted" from the staging S3 bucket (See GHA runs). After that happened it was fixed. So the focus of this issue isn't on a bug or bugfix, but rather an "enhancement" to give a softer/better failure mode when this happens in the future.

If you're still seeing this, it's best if that's tracked separately. Likely the checksum changed and something else was promoted. If you open a support ticket help.heroku.com and give app permissions, someone from Heroku can take a look. If you can reproduce with the CNB buildpack (versus this repo is "classic") https://github.com/heroku/buildpacks-php locally with pack and an example app (https://www.codetriage.com/example_app) that you're willing to share, you can open an issue on that repo.