Detect and/or wrap common retrieval failures

[colindean]

Verification

• This issue's title and/or description do not reference a single formula e.g. brew install wget. If they do, open an issue at https://github.com/Homebrew/homebrew-core/issues/new/choose instead.

Provide a detailed description of the proposed feature

The Docs team at AGM surfaced that common GH Discussions topics include retrieval failures that are outside of Homebrew's immediate control. As we use curl and git under the hood, we could provide better error handling by intermediating the exit status or stderr and directing the user to the docs for common errors.

What is the motivation for the feature?

We desire to reduce the frequency of common discussion topics related to troubleshooting user-responsible workstation configuration or transient connectivity issues outside Homebrew's control.

How will the feature be relevant to at least 90% of Homebrew users?

Reducing maintainer and discussions answer contributors' work addressing common misconfiguration and transient errors can leave their efforts for more complex issues.

What alternatives to the feature have been considered?

The status quo is a less programatically complex way of handling errors: let the user know that the subbed out executable failed and to simply check its output. When users copy-paste this error into search engines, they may not quickly find the right information. If we can detect the error, we can own the resolution experience, within limits of known cases with generally-working solutions.

[NeimadTL]

Hi @colindean, I would like to make an attempt at this with your help and guidance. What should be the first step for tackling this according to you ? Thank you.

[colindean]

Thanks for the interest, @NeimadTL. I'd start by inventorying how Homebrew invokes curl and examining what it can return to the caller: a process exit code and data via STDOUT or STDERR. If you can find a table of exit codes and then embed that table in a reference within Homebrew, you may have step one toward a wrapper. Exhaust what wrappers may be available in RubyGems, too, but don't pull in something huge, as it'd be vendored and have to meet Homebrew's requirements. You could likely copy something already written in Ruby elsewhere.

At first, you might want to emit the error from curl—it will likely pass through to STDERR—but Homebrew could offer a more helpful error message or direct you to an as-yet-unwritten troubleshooting section for common curl errors.

For my personal ax to be ground, the MVP is catching curl exit code 60. If I recall correctly, that's the exit code most commonly associated with TLS certification verification failure.

I defer on implementation to the active maintainers, who can further counsel you.