Module: Downloadable Abstract

Extended by:
T::Helpers
Includes:
Context, Utils::Output::Mixin
Included in:
Bottle, Cask::Download, Homebrew::API::JSONDownload, Homebrew::API::SourceDownload, Homebrew::RetryableDownload, Resource, SoftwareSpec
Defined in:
downloadable.rb

Overview

This module is abstract.

Subclasses must implement the abstract methods below.

Defined Under Namespace

Classes: VerificationCache

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Utils::Output::Mixin

#issue_reporting_message, #odebug, #odeprecated, #odie, #odisabled, #ofail, #oh1, #oh1_title, #ohai, #ohai_title, #onoe, #opoo, #opoo_outside_github_actions, #opoo_without_github_actions_annotation, #pretty_cannot_install, #pretty_deprecated, #pretty_disabled, #pretty_duration, #pretty_install_status, #pretty_installed, #pretty_uninstalled, #pretty_unmarked, #pretty_upgradable, #pretty_warning

Methods included from Context

current, current=, #debug?, #deferred_environment_expansion?, #quiet?, #verbose?, #with_context

Instance Attribute Details

#checksum ⇒ Checksum? (readonly)

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:



155
156
157
 
# File 'downloadable.rb', line 155

def checksum
  @checksum
end

#mirrors ⇒ Array<String> (readonly)

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:



158
159
160
 
# File 'downloadable.rb', line 158

def mirrors
  @mirrors
end

#phase ⇒ Symbol

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:



161
162
163
 
# File 'downloadable.rb', line 161

def phase
  @phase
end

#url ⇒ String, ... (readonly)

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:



152
153
154
 
# File 'downloadable.rb', line 152

def url
  @url
end

Class Method Details

.verification_cache ⇒ VerificationCache

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:



146
147
148
 
# File 'downloadable.rb', line 146

def verification_cache
  @verification_cache ||= T.let(VerificationCache.new, T.nilable(VerificationCache))
end

Instance Method Details

#cached_download ⇒ 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:



230
231
232
 
# File 'downloadable.rb', line 230

def cached_download
  downloader.cached_location
end

#clear_cache ⇒ 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.



235
236
237
 
# File 'downloadable.rb', line 235

def clear_cache
  downloader.clear_cache
end

#download_queue_message ⇒ 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:



209
210
211
 
# File 'downloadable.rb', line 209

def download_queue_message
  "#{download_queue_type} #{download_queue_name}"
end

#download_queue_name ⇒ 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:



203
 
# File 'downloadable.rb', line 203

def download_queue_name = download_name

#download_queue_type ⇒ 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.

This method is abstract.

Returns:



206
 
# File 'downloadable.rb', line 206

def download_queue_type; end

#download_strategy ⇒ T::Class[AbstractDownloadStrategy]

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:



260
261
262
263
264
265
266
267
 
# File 'downloadable.rb', line 260

def download_strategy
  @download_strategy ||= begin
    url = determine_url
    raise ArgumentError, "attempted to use a `Downloadable` without a URL!" if url.nil?

    url.download_strategy
  end
end

#downloaded! ⇒ 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.



166
 
# File 'downloadable.rb', line 166

def downloaded! = (@phase = :downloaded)

#downloaded? ⇒ 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.

Returns:

  • (Boolean) 


214
215
216
 
# File 'downloadable.rb', line 214

def downloaded?
  cached_download.exist?
end

#downloaded_and_valid? ⇒ 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.

Returns:

  • (Boolean) 


219
220
221
222
223
224
225
226
227
 
# File 'downloadable.rb', line 219

def downloaded_and_valid?
  return false unless cached_download.file?
  return false if checksum.blank?

  with_context(quiet: true) { verify_download_integrity(cached_download) }
  true
rescue ChecksumMismatchError
  false
end

#downloader ⇒ AbstractDownloadStrategy

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:



270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'downloadable.rb', line 270

def downloader
  @downloader ||= begin
    primary_url, *mirrors = determine_url_mirrors
    url = determine_url
    raise ArgumentError, "attempted to use a `Downloadable` without a URL!" if url.nil? || primary_url.blank?

    download_strategy.new(primary_url, download_name, version,
                          mirrors:, cache:, **url.specs).tap do |downloader|
      if downloader.is_a?(CurlDownloadStrategy) &&
         AbstractDownloadStrategy.expand_deferred_environment_for?(downloader)
        downloader.allow_deferred_environment_expansion!
      end
    end
  end
end

#downloading! ⇒ 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.



164
 
# File 'downloadable.rb', line 164

def downloading! = (@phase = :downloading)

#extracting! ⇒ 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.



172
 
# File 'downloadable.rb', line 172

def extracting! = (@phase = :extracting)

#fetch(verify_download_integrity: true, timeout: nil, quiet: false) ⇒ 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.

Parameters:

  • verify_download_integrity (Boolean) (defaults to: true)
  • timeout (Integer, Float, nil) (defaults to: nil)
  • quiet (Boolean) (defaults to: false)

Returns:



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
 
# File 'downloadable.rb', line 293

def fetch(verify_download_integrity: true, timeout: nil, quiet: false)
  downloading!

  cache.mkpath

  begin
    downloader.quiet! if quiet
    downloader.fetch(timeout:)
  rescue ErrorDuringExecution, CurlDownloadStrategyError => e
    raise DownloadError.new(self, e)
  end

  downloaded!

  download = cached_download
  verify_download_integrity(download) if verify_download_integrity
  download
end

#fetched_size ⇒ Integer?

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.

Total bytes downloaded if available.

Returns:



241
242
243
 
# File 'downloadable.rb', line 241

def fetched_size
  downloader.fetched_size
end

#freeze ⇒ T.self_type

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:

  • (T.self_type) 


195
196
197
198
199
200
 
# File 'downloadable.rb', line 195

def freeze
  @checksum.freeze
  @mirrors.freeze
  @version.freeze
  super
end

#initialize ⇒ 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. 



175
176
177
178
179
180
181
182
183
184
 
# File 'downloadable.rb', line 175

def initialize
  @url = T.let(nil, T.nilable(URL))
  @checksum = T.let(nil, T.nilable(Checksum))
  @mirrors = T.let([], T::Array[String])
  @version = T.let(nil, T.nilable(Version))
  @download_strategy = T.let(nil, T.nilable(T::Class[AbstractDownloadStrategy]))
  @downloader = T.let(nil, T.nilable(AbstractDownloadStrategy))
  @download_name = T.let(nil, T.nilable(String))
  @phase = T.let(:preparing, Symbol)
end

#initialize_dup(other) ⇒ 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.

Parameters:



187
188
189
190
191
192
 
# File 'downloadable.rb', line 187

def initialize_dup(other)
  super
  @checksum = @checksum.dup
  @mirrors = @mirrors.dup
  @version = @version.dup
end

#stage_from_download_queue(_download, pour:) ⇒ 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.

Parameters:



321
 
# File 'downloadable.rb', line 321

def stage_from_download_queue(_download, pour:); end

#stage_from_download_queue?(_download, pour:) ⇒ 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) 


313
314
315
 
# File 'downloadable.rb', line 313

def stage_from_download_queue?(_download, pour:)
  false
end

#staged_path_from_download_queue ⇒ 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:



318
 
# File 'downloadable.rb', line 318

def staged_path_from_download_queue; end

#total_size ⇒ Integer?

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.

Total download size if available.

Returns:



247
248
249
 
# File 'downloadable.rb', line 247

def total_size
  @total_size ||= T.let(downloader.total_size, T.nilable(Integer))
end

#verified! ⇒ 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.



170
 
# File 'downloadable.rb', line 170

def verified! = (@phase = :verified)

#verify_download_integrity(filename) ⇒ 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.

Parameters:



324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'downloadable.rb', line 324

def verify_download_integrity(filename)
  verifying!

  if filename.file?
    Downloadable.verification_cache.verify(filename, checksum)
    verified!
  end
rescue ChecksumMissingError
  return if silence_checksum_missing_error?

  opoo <<~EOS
    Cannot verify integrity of '#{filename.basename}'.
    No checksum was provided.
    For your reference, the checksum is:
      sha256 "#{Downloadable.verification_cache.sha256(filename)}"
  EOS
end

#verifying! ⇒ 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
 
# File 'downloadable.rb', line 168

def verifying! = (@phase = :verifying)

#version ⇒ Version?

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:



252
253
254
255
256
257
 
# File 'downloadable.rb', line 252

def version
  return @version if @version && !@version.null?

  version = determine_url&.version
  version unless version&.null?
end