Add HOMEBREW_API_AUTO_UPDATE_SECS

This sets the default and allows customising how often we try to
download files from the API.

This does not affect `brew update` as we want to always check every time
on an explicit call.

Library/Homebrew/api.rb

@@ -42,19 +42,31 @@ module Homebrew
       retry_count = 0
       url = "#{Homebrew::EnvConfig.api_domain}/#{endpoint}"
       default_url = "#{HOMEBREW_API_DEFAULT_DOMAIN}/#{endpoint}"
+
+      # TODO: consider using more of Utils::Curl
       curl_args = %W[
         --compressed
         --speed-limit #{ENV.fetch("HOMEBREW_CURL_SPEED_LIMIT")}
         --speed-time #{ENV.fetch("HOMEBREW_CURL_SPEED_TIME")}
       ]
-      curl_args.prepend("--silent") unless Context.current.debug?
+      curl_args << "--progress-bar" unless Context.current.verbose?
+      curl_args << "--verbose" if Homebrew::EnvConfig.curl_verbose?
+      curl_args << "--silent" unless $stdout.tty?
+
+      skip_download = target.exist? &&
+                      !target.empty? &&
+                      (Homebrew::EnvConfig.no_auto_update? ||
+                      ((Time.now - Homebrew::EnvConfig.api_auto_update_secs.to_i) < target.mtime))
 
       begin
         begin
           args = curl_args.dup
           args.prepend("--time-cond", target) if target.exist? && !target.empty?
-          # Disable retries here, we handle them ourselves below.
-          Utils::Curl.curl_download(*args, url, to: target, retries: 0, show_error: false)
+          unless skip_download
+            ohai "Downloading #{url}" if $stdout.tty?
+            # Disable retries here, we handle them ourselves below.
+            Utils::Curl.curl_download(*args, url, to: target, retries: 0, show_error: false)
+          end
         rescue ErrorDuringExecution
           if url == default_url
             raise unless target.exist?
@@ -64,6 +76,7 @@ module Homebrew
             # This block will be executed only once, because we set `url` to `default_url`
             url = default_url
             target.unlink if target.exist? && target.empty?
+            skip_download = false
 
             retry
           end
@@ -71,10 +84,12 @@ module Homebrew
           opoo "#{target.basename}: update failed, falling back to cached version."
         end
 
+        FileUtils.touch target
         JSON.parse(target.read)
       rescue JSON::ParserError
         target.unlink
         retry_count += 1
+        skip_download = false
         odie "Cannot download non-corrupt #{url}!" if retry_count > Homebrew::EnvConfig.curl_retries.to_i
 
         retry

Library/Homebrew/brew.sh

@@ -276,7 +276,7 @@ auto-update() {
       fi
     fi
 
-    # Skip auto-update if the repository has been updated in the
+    # Skip auto-update if the Homebrew/brew repository has been checked in the
     # last $HOMEBREW_AUTO_UPDATE_SECS.
     repo_fetch_head="${HOMEBREW_REPOSITORY}/.git/FETCH_HEAD"
     if [[ -f "${repo_fetch_head}" ]] &&

Library/Homebrew/env_config.rb

@@ -37,6 +37,12 @@ module Homebrew
                      "to instead be downloaded from " \
                      "`http://localhost:8080/v2/homebrew/core/gettext/manifests/0.21`",
       },
+      HOMEBREW_API_AUTO_UPDATE_SECS:             {
+        description: "Check Homebrew's API for new formulae or cask data every " \
+                     "`HOMEBREW_API_AUTO_UPDATE_SECS` seconds. Alternatively, disable API auto-update " \
+                     "checks entirely with HOMEBREW_NO_AUTO_UPDATE.",
+        default:     1800,
+      },
       HOMEBREW_AUTO_UPDATE_SECS:                 {
         description:  "Run `brew update` once every `HOMEBREW_AUTO_UPDATE_SECS` seconds before some commands, " \
                       "e.g. `brew install`, `brew upgrade` and `brew tap`. Alternatively, " \

docs/Manpage.md

@@ -1995,6 +1995,11 @@ example, run `export HOMEBREW_NO_INSECURE_REDIRECT=1` rather than just
 - `HOMEBREW_ARTIFACT_DOMAIN`
   <br>Prefix all download URLs, including those for bottles, with this value. For example, `HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080` will cause a formula with the URL `https://example.com/foo.tar.gz` to instead download from `http://localhost:8080/https://example.com/foo.tar.gz`. Bottle URLs however, have their domain replaced with this prefix. This results in e.g. `https://ghcr.io/v2/homebrew/core/gettext/manifests/0.21` to instead be downloaded from `http://localhost:8080/v2/homebrew/core/gettext/manifests/0.21`
 
+- `HOMEBREW_API_AUTO_UPDATE_SECS`
+  <br>Check Homebrew's API for new formulae or cask data every `HOMEBREW_API_AUTO_UPDATE_SECS` seconds. Alternatively, disable API auto-update checks entirely with HOMEBREW_NO_AUTO_UPDATE.
+
+  *Default:* `1800`.
+
 - `HOMEBREW_AUTO_UPDATE_SECS`
   <br>Run `brew update` once every `HOMEBREW_AUTO_UPDATE_SECS` seconds before some commands, e.g. `brew install`, `brew upgrade` and `brew tap`. Alternatively, disable auto-update entirely with `HOMEBREW_NO_AUTO_UPDATE`.
 

manpages/brew.1

@@ -2849,6 +2849,15 @@ Linux only: Pass this value to a type name representing the compiler\'s \fB\-mar
 Prefix all download URLs, including those for bottles, with this value\. For example, \fBHOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080\fR will cause a formula with the URL \fBhttps://example\.com/foo\.tar\.gz\fR to instead download from \fBhttp://localhost:8080/https://example\.com/foo\.tar\.gz\fR\. Bottle URLs however, have their domain replaced with this prefix\. This results in e\.g\. \fBhttps://ghcr\.io/v2/homebrew/core/gettext/manifests/0\.21\fR to instead be downloaded from \fBhttp://localhost:8080/v2/homebrew/core/gettext/manifests/0\.21\fR
 .
 .TP
+\fBHOMEBREW_API_AUTO_UPDATE_SECS\fR
+.
+.br
+Check Homebrew\'s API for new formulae or cask data every \fBHOMEBREW_API_AUTO_UPDATE_SECS\fR seconds\. Alternatively, disable API auto\-update checks entirely with HOMEBREW_NO_AUTO_UPDATE\.
+.
+.IP
+\fIDefault:\fR \fB1800\fR\.
+.
+.TP
 \fBHOMEBREW_AUTO_UPDATE_SECS\fR
 .
 .br