Add flag to prevent source fallback and improve fallback messaging

[thomas-0816]

What are you trying to do?

Retry binary download if binary is available and github rate limit is exceeded.
Currently rate-limit on binary download directly proceeds to source compilation.

e.g. rate limit:

seq 20 | parallel --halt soon,fail=1 -j10 'echo "=== Attempt {} ==="; curl -i https://api.github.com/repos/asgrim/example-pie-extension/releases/tags/2.0.9'

HTTP/2 403
...
{"message":"API rate limit exceeded for 176.0.50.1. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)","documentation_url":"https://docs.github.com/rest/overview/resources-in-the-rest-api#rate-limiting"}

GithubPackageReleaseAssets::getReleaseAssetsForPackage() currently only handles 404.

CurlDownloader.php can retry, but not for 403:

                // fail 4xx and 5xx responses and capture the response
                if ($statusCode >= 400 && $statusCode <= 599) {
                    $retryableStatusCode = in_array($statusCode, [423, 425, 500, 502, 503, 504, 507, 510], true)
                        // codeload.github.com intermittently returns 400 on reused connections, retry those specifically, see #12958
                        || ($statusCode === 400 && parse_url($job['url'], PHP_URL_HOST) === 'codeload.github.com');

What platform, and PIE version are you using?
(add the output of pie show -v, and information about which OS you're using etc.)

🥧 PHP Installer for Extensions (PIE) 1.4.7, from The PHP Foundation
You are running PHP 8.5.9
Target PHP installation: 8.5.9 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.5)
Using pie.json: /home/tb/.config/pie/php8.5_5830ff28f955df5820d08bc53fb7f06b/pie.json
Using pie.json: /home/tb/.config/pie/php8.5_5830ff28f955df5820d08bc53fb7f06b/pie.json
Tip: to include extensions in this list that PIE does not manage, use the --all flag.

Loaded PIE extensions:
(none)

Steps to reproduce the issue

wait for github rate limit error, run pie install ...

What is actually happening
Describe what is actually happening.

binary download is skipped and source compilation is continued, source compilation may fail if the machine has no compiler

Complete logs/output
Complete error messages and/or logs, including stack traces (hint: use -v for verbose), but please redact sensitive information.

Anything else?
other information that might be helpful...

[asgrim]

Hmm; how would you imagine handling of a rate-limited scenario would work? For example, if you're rate limited and the limit doesn't reduce until say 1 hours time, it doesn't make sense to block this. Or is the idea just to surface the fact you are rate-limited with better messaging? I believe in PIE, the exception already bubbles up explaining the above - you didn't provide an actual example output from PIE, so I'm not entirely sure what you're seeing.

[thomas-0816]

Here is the example output:
https://github.com/thomas-0816/pdo-duckdb-php/actions/runs/31037848709/job/92414469912

Linux runnervmopbwf 7.0.0-1009-azure #9-Ubuntu SMP PREEMPT Fri Jun 19 15:57:36 UTC 2026 x86_64 GNU/Linux
PHP 8.5.9 (cli) (built: Jul 29 2026 08:30:33) (ZTS)
Copyright (c) The PHP Group
Zend Engine v4.5.9, Copyright (c) Zend Technologies
    with Zend OPcache v8.5.9, Copyright (c), by Zend Technologies
🥧 PHP Installer for Extensions (PIE) 1.4.9, from The PHP Foundation
You are running PHP 8.5.9
Target PHP installation: 8.5.9 ts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.5)
Found package: thomas-0816/pdo-duckdb-php:1.5.5.4 which provides ext-pdo_duckdb
Extracted thomas-0816/pdo-duckdb-php:1.5.5.4 source to: /home/runner/.config/pie/php8.5_602145387dc1abc8a2de9648cb5dac45/vendor/thomas-0816/pdo-duckdb-php
phpize complete.
Configure complete with options: --with-php-config=/usr/bin/php-config

In ProcessFailedWithLimitedOutput.php line 35:
                                                                               
  The command "'make' '-j4'" failed. Output was saved in "/tmp/pie_make_outpu  
  t_6a7389c9659169.28472949" as it was too long                                
                                                                               
  Exit Code: 2(Misuse of shell builtins)                                       
                                                                               
  Working directory: /home/runner/.config/pie/php8.5_602145387dc1abc8a2de9648  
  cb5dac45/vendor/thomas-0816/pdo-duckdb-php                                   
                                                                               

install [-j|--make-parallel-jobs MAKE-PARALLEL-JOBS] [--skip-enable-extension] [--force] [-d|--working-dir WORKING-DIR] [--with-php-config WITH-PHP-CONFIG] [--with-php-path WITH-PHP-PATH] [--with-phpize-path WITH-PHPIZE-PATH] [--no-cache] [--allow-non-interactive-project-install] [--auto-install-build-tools] [--no-build-tools-check] [--auto-install-system-dependencies] [--no-system-dependencies-check] [--with-pdo-duckdb] [--] [<requested-package-and-version>]

[asgrim]

@thomas-0816 I'm confused, what does the make invocation failing have to do with GH's API rate limiting? 🤔

[thomas-0816]

The error case:

https://api.github.com/repos/asgrim/example-pie-extension/releases/tags/XX gives 403

Then instead of binary download, sources are fetched and tried to compile.
phpize and configure succeed. "make" is installed but misses dependancies -> failure

The regular case:

https://api.github.com/repos/asgrim/example-pie-extension/releases/tags/XX gives 20x
Binary is downloaded, extracted and installed.

[asgrim]

Ah ok; I think a couple things at play here:

• The falling back to src build is allowed by design, and specifically you allowed it with download-url-method setting. If the issue is specifically due to your CI pipeline sometimes being rate limited, I would suggest, either:
  • supply a GH token to make authenticated requests, to avoid the scenario completely
  • add the build deps (make, whatever else) in case your pipeline falls back
  • if your extension is not able to be compiled on a "typical" system, don't include composer-default as the fallback
• I don't think it makes sense to automatically block and retry on a rate limit scenario. As I mentioned, if we stop processing until the rate limit is lifted, that could be anywhere from a second or two, up until an hour or more (I can't remember GH's specific limits off my head), but it is nonsensical to block for that long.

That said, there are some smaller things we could do to improve this on PIE's side:

1. Looking at the output, it certainly isn't clear that the binary DL failed & for what reason; I believe supplying the verbose -v flag would reveal that PIE did actually try the pre-built binary DL first (or not, perhaps something went wrong - I can't tell from the output in your job log)
2. There is no way for a PIE end user to say "I don't want to fall back to source" (even if the maintainer allows it)

The second one may address your issue, if you do actually want to offer composer-default fallback option, and you're specifically trying to address testing "installing pre-built binaries" in your CI pipeline. WDYT?

[thomas-0816]

If I write a pipeline to test binary download and installation, of course I'm not providing dependancies to compile from source.

In general, userland developers want pre-compiled and pre-tested binaries, so fallback to C is nice, but many don't like it.

To me, if a request to https://api.github.com/repos/asgrim/example-pie-extension/releases/tags/XX fails, the output should clearly state that without "-v".

[asgrim]

OK; I'll look into both the suggestions (improve the output, and provide a flag to prevent falling back to source). Thank you for your understanding! 👍