Module: Homebrew::API Private

Extended by:
Cachable, Utils::Output::Mixin
Defined in:
api.rb,
api/cask.rb,
api/formula.rb,
api/internal.rb,
api/analytics.rb,
api/json_download.rb,
api/formula_struct.rb,
api/source_download.rb

Overview

This module is part of a private API. This module may only be used in the Homebrew/brew repository. Third parties should avoid using this module if possible, as it may be removed or changed without warning.

Helper functions for using Homebrew's formulae.brew.sh API.

Defined Under Namespace

Modules: Analytics, Cask, Formula, Internal Classes: FormulaStruct, JSONDownload, JSONDownloadStrategy, SourceDownload, SourceDownloadStrategy

Constant Summary collapse

HOMEBREW_CACHE_API =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

T.let((HOMEBREW_CACHE/"api").freeze, Pathname)
HOMEBREW_CACHE_API_SOURCE =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning. 

T.let((HOMEBREW_CACHE/"api-source").freeze, Pathname)
DEFAULT_API_STALE_SECONDS =

This constant is part of a private API. This constant may only be used in the Homebrew/brew repository. Third parties should avoid using this constant if possible, as it may be removed or changed without warning.

1 day

T.let(86400, Integer)

Class Method Summary collapse

Methods included from Utils::Output::Mixin

odebug, odeprecated, odie, odisabled, ofail, oh1, oh1_title, ohai, ohai_title, onoe, opoo, opoo_outside_github_actions, pretty_duration, pretty_installed, pretty_outdated, pretty_uninstalled

Methods included from Cachable

cache, clear_cache

Class Method Details

.cached_cask_json_file_path ⇒ Pathname

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



356
357
358
359
360
361
362
 
# File 'api.rb', line 356

def self.cached_cask_json_file_path
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.cached_cask_json_file_path
  else
    Homebrew::API::Cask.cached_json_file_path
  end
end

.cached_formula_json_file_path ⇒ Pathname

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



320
321
322
323
324
325
326
 
# File 'api.rb', line 320

def self.cached_formula_json_file_path
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.cached_formula_json_file_path
  else
    Homebrew::API::Formula.cached_json_file_path
  end
end

.cask_renames ⇒ Hash{String => String}

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



338
339
340
341
342
343
344
 
# File 'api.rb', line 338

def self.cask_renames
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.cask_renames
  else
    Homebrew::API::Cask.all_renames
  end
end

.cask_tap_migrations ⇒ Hash{String => String}

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



347
348
349
350
351
352
353
 
# File 'api.rb', line 347

def self.cask_tap_migrations
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.cask_tap_migrations
  else
    Homebrew::API::Cask.tap_migrations
  end
end

.cask_tokens ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



329
330
331
332
333
334
335
 
# File 'api.rb', line 329

def self.cask_tokens
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.cask_hashes.keys
  else
    Homebrew::API::Cask.all_casks.keys
  end
end

.fetch(endpoint) ⇒ Hash{String => T.untyped}

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'api.rb', line 24

def self.fetch(endpoint)
  return cache[endpoint] if cache.present? && cache.key?(endpoint)

  api_url = "#{Homebrew::EnvConfig.api_domain}/#{endpoint}"
  output = Utils::Curl.curl_output("--fail", api_url)
  if !output.success? && Homebrew::EnvConfig.api_domain != HOMEBREW_API_DEFAULT_DOMAIN
    # Fall back to the default API domain and try again
    api_url = "#{HOMEBREW_API_DEFAULT_DOMAIN}/#{endpoint}"
    output = Utils::Curl.curl_output("--fail", api_url)
  end
  raise ArgumentError, "No file found at: #{Tty.underline}#{api_url}#{Tty.reset}" unless output.success?

  cache[endpoint] = JSON.parse(output.stdout, freeze: true)
rescue JSON::ParserError
  raise ArgumentError, "Invalid JSON file: #{Tty.underline}#{api_url}#{Tty.reset}"
end

.fetch_api_files! ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'api.rb', line 168

def self.fetch_api_files!
  download_queue = if Homebrew::EnvConfig.download_concurrency > 1
    require "download_queue"
    Homebrew::DownloadQueue.new
  end

  stale_seconds = if ENV["HOMEBREW_API_UPDATED"].present? ||
                     (Homebrew::EnvConfig.no_auto_update? && !Homebrew::EnvConfig.force_api_auto_update?)
    nil
  elsif Homebrew.auto_update_command?
    Homebrew::EnvConfig.api_auto_update_secs.to_i
  else
    DEFAULT_API_STALE_SECONDS
  end

  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.fetch_formula_api!(download_queue:, stale_seconds:)
    Homebrew::API::Internal.fetch_cask_api!(download_queue:, stale_seconds:)
  else
    Homebrew::API::Formula.fetch_api!(download_queue:, stale_seconds:)
    Homebrew::API::Formula.fetch_tap_migrations!(download_queue:, stale_seconds: DEFAULT_API_STALE_SECONDS)
    Homebrew::API::Cask.fetch_api!(download_queue:, stale_seconds:)
    Homebrew::API::Cask.fetch_tap_migrations!(download_queue:, stale_seconds: DEFAULT_API_STALE_SECONDS)
  end

  ENV["HOMEBREW_API_UPDATED"] = "1"

  return unless download_queue

  begin
    download_queue.fetch
  ensure
    download_queue.shutdown
  end
end

.fetch_json_api_file(endpoint, target: HOMEBREW_CACHE_API/endpoint, stale_seconds: nil, download_queue: nil) ⇒ Array<([Array<T.untyped>, Hash{String => T.untyped}], Boolean)>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • endpoint (String)
  • target (Pathname) (defaults to: HOMEBREW_CACHE_API/endpoint)
  • stale_seconds (Integer, nil) (defaults to: nil)
  • download_queue (DownloadQueue, nil) (defaults to: nil)

Returns:



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'api.rb', line 58

def self.fetch_json_api_file(endpoint, target: HOMEBREW_CACHE_API/endpoint,
                             stale_seconds: nil, download_queue: nil)
  # Lazy-load dependency.
  require "development_tools"

  retry_count = 0
  url = "#{Homebrew::EnvConfig.api_domain}/#{endpoint}"
  default_url = "#{HOMEBREW_API_DEFAULT_DOMAIN}/#{endpoint}"

  if Homebrew.running_as_root_but_not_owned_by_root? &&
     (!target.exist? || target.empty?)
    odie "Need to download #{url} but cannot as root! Run `brew update` without `sudo` first then try again."
  end

  curl_args = Utils::Curl.curl_args(retries: 0) + %W[
    --compressed
    --speed-limit #{ENV.fetch("HOMEBREW_CURL_SPEED_LIMIT")}
    --speed-time #{ENV.fetch("HOMEBREW_CURL_SPEED_TIME")}
  ]

  insecure_download = DevelopmentTools.ca_file_substitution_required? ||
                      DevelopmentTools.curl_substitution_required?
  skip_download = skip_download?(target:, stale_seconds:)

  if download_queue
    unless skip_download
      require "api/json_download"
      download = Homebrew::API::JSONDownload.new(endpoint, target:, stale_seconds:)
      download_queue.enqueue(download)
    end
    return [{}, false]
  end

  json_data = begin
    begin
      args = curl_args.dup
      args.prepend("--time-cond", target.to_s) if target.exist? && !target.empty?
      if insecure_download
        opoo DevelopmentTools.insecure_download_warning(endpoint)
        args.append("--insecure")
      end
      unless skip_download
        ohai "Downloading #{url}" if $stdout.tty? && !Context.current.quiet?
        # 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?
        raise if target.empty?
      elsif retry_count.zero? || !target.exist? || target.empty?
        # Fall back to the default API domain and try again
        # 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

      opoo "#{target.basename}: update failed, falling back to cached version."
    end

    mtime = insecure_download ? Time.new(1970, 1, 1) : Time.now
    FileUtils.touch(target, mtime:) unless skip_download
    # Can use `target.read` again when/if https://github.com/sorbet/sorbet/pull/8999 is merged/released.
    JSON.parse(File.read(target, encoding: Encoding::UTF_8), freeze: true)
  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
  end

  if endpoint.end_with?(".jws.json")
    success, data = verify_and_parse_jws(json_data)
    unless success
      target.unlink
      odie <<~EOS
        Failed to verify integrity (#{data}) of:
          #{url}
        Potential MITM attempt detected. Please run `brew update` and try again.
      EOS
    end
    [data, !skip_download]
  else
    [json_data, !skip_download]
  end
end

.formula_aliases ⇒ Hash{String => String}

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



293
294
295
296
297
298
299
 
# File 'api.rb', line 293

def self.formula_aliases
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.formula_aliases
  else
    Homebrew::API::Formula.all_aliases
  end
end

.formula_names ⇒ Array<String>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



284
285
286
287
288
289
290
 
# File 'api.rb', line 284

def self.formula_names
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.formula_arrays.keys
  else
    Homebrew::API::Formula.all_formulae.keys
  end
end

.formula_renames ⇒ Hash{String => String}

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



302
303
304
305
306
307
308
 
# File 'api.rb', line 302

def self.formula_renames
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.formula_renames
  else
    Homebrew::API::Formula.all_renames
  end
end

.formula_tap_migrations ⇒ Hash{String => String}

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



311
312
313
314
315
316
317
 
# File 'api.rb', line 311

def self.formula_tap_migrations
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.formula_tap_migrations
  else
    Homebrew::API::Formula.tap_migrations
  end
end

.merge_variations(json, bottle_tag: T.unsafe(nil)) ⇒ Hash{String => T.untyped}

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'api.rb', line 154

def self.merge_variations(json, bottle_tag: T.unsafe(nil))
  return json unless json.key?("variations")

  bottle_tag ||= Homebrew::SimulateSystem.current_tag

  if (variation = json.dig("variations", bottle_tag.to_s).presence) ||
     (variation = json.dig("variations", bottle_tag.to_sym).presence)
    json = json.merge(variation)
  end

  json.except("variations")
end

.skip_download?(target:, stale_seconds:) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • target (Pathname)
  • stale_seconds (Integer, nil)

Returns:

  • (Boolean) 


42
43
44
45
46
47
48
 
# File 'api.rb', line 42

def self.skip_download?(target:, stale_seconds:)
  return true if Homebrew.running_as_root_but_not_owned_by_root?
  return false if !target.exist? || target.empty?
  return true unless stale_seconds

  (Time.now - stale_seconds) < target.mtime
end

.tap_from_source_download(path) ⇒ Tap?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:



272
273
274
275
276
277
278
279
280
281
 
# File 'api.rb', line 272

def self.tap_from_source_download(path)
  path = path.expand_path
  source_relative_path = path.relative_path_from(Homebrew::API::HOMEBREW_CACHE_API_SOURCE)
  return if source_relative_path.to_s.start_with?("../")

  org, repo = source_relative_path.each_filename.first(2)
  return if org.blank? || repo.blank?

  Tap.fetch(org, repo)
end

.write_aliases_file!(aliases, type, regenerate:) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'api.rb', line 228

def self.write_aliases_file!(aliases, type, regenerate:)
  aliases_path = HOMEBREW_CACHE_API/"#{type}_aliases.txt"
  if !aliases_path.exist? || regenerate
    aliases_text = aliases.map do |alias_name, real_name|
      "#{alias_name}|#{real_name}"
    end
    aliases_path.unlink if aliases_path.exist?
    aliases_path.write(aliases_text.sort.join("\n"))
    return true
  end

  false
end

.write_names_and_aliases ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



205
206
207
208
209
210
211
212
213
 
# File 'api.rb', line 205

def self.write_names_and_aliases
  if Homebrew::EnvConfig.use_internal_api?
    Homebrew::API::Internal.write_formula_names_and_aliases
    Homebrew::API::Internal.write_cask_names
  else
    Homebrew::API::Formula.write_names_and_aliases
    Homebrew::API::Cask.write_names
  end
end

.write_names_file!(names, type, regenerate:) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


216
217
218
219
220
221
222
223
224
225
 
# File 'api.rb', line 216

def self.write_names_file!(names, type, regenerate:)
  names_path = HOMEBREW_CACHE_API/"#{type}_names.txt"
  if !names_path.exist? || regenerate
    names_path.unlink if names_path.exist?
    names_path.write(names.sort.join("\n"))
    return true
  end

  false
end