Module: Homebrew::Livecheck::Strategy Private

Defined in:
livecheck/strategy.rb,
livecheck/strategy/git.rb,
livecheck/strategy/gnu.rb,
livecheck/strategy/npm.rb,
livecheck/strategy/cpan.rb,
livecheck/strategy/pypi.rb,
livecheck/strategy/xorg.rb,
livecheck/strategy/gnome.rb,
livecheck/strategy/apache.rb,
livecheck/strategy/hackage.rb,
livecheck/strategy/sparkle.rb,
livecheck/strategy/bitbucket.rb,
livecheck/strategy/launchpad.rb,
livecheck/strategy/page_match.rb,
livecheck/strategy/sourceforge.rb,
livecheck/strategy/header_match.rb,
livecheck/strategy/extract_plist.rb,
livecheck/strategy/github_latest.rb,
livecheck/strategy/electron_builder.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.

The Livecheck::Strategy module contains the various strategies as well as some general-purpose methods for working with them. Within the context of the brew livecheck command, strategies are established procedures for finding new software versions at a given source.

Defined Under Namespace

Classes: Apache, Bitbucket, Cpan, ElectronBuilder, ExtractPlist, Git, GithubLatest, Gnome, Gnu, Hackage, HeaderMatch, Launchpad, Npm, PageMatch, Pypi, Sourceforge, Sparkle, Xorg

Constant Summary collapse

DEFAULT_PRIORITY =

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.

Homebrew::Livecheck::Strategy priorities informally range from 1 to 10, where 10 is the highest priority. 5 is the default priority because it’s roughly in the middle of this range. Strategies with a priority of 0 (or lower) are ignored.

5
CURL_CONNECT_TIMEOUT =

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.

cURL’s default --connect-timeout value can be up to two minutes, so we need to use a more reasonable duration (in seconds) to avoid a lengthy wait when a connection can’t be established.

10
CURL_MAX_TIME =

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.

cURL does not set a default --max-time value, so we provide a value to ensure cURL will time out in a reasonable amount of time.

CURL_CONNECT_TIMEOUT + 5
CURL_PROCESS_TIMEOUT =

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.

The curl process will sometimes hang indefinitely (despite setting the --max-time argument) and it needs to be quit for livecheck to continue. This value is used to set the timeout argument on Utils::Curl method calls in Homebrew::Livecheck::Strategy.

CURL_MAX_TIME + 5
MAX_REDIRECTIONS =

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.

The maximum number of redirections that curl should allow.

5
MAX_PARSE_ITERATIONS =

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.

This value is passed to #parse_curl_output to ensure that the limit for the number of responses it will parse corresponds to the maximum number of responses in this context. The + 1 here accounts for the situation where there are exactly MAX_REDIRECTIONS number of redirections, followed by a final 200 OK response.

MAX_REDIRECTIONS + 1
DEFAULT_CURL_ARGS =

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.

Baseline curl arguments used in Homebrew::Livecheck::Strategy methods.

[
  # Follow redirections to handle mirrors, relocations, etc.
  "--location",
  "--max-redirs", MAX_REDIRECTIONS.to_s,
  # Avoid progress bar text, so we can reliably identify `curl` error
  # messages in output
  "--silent"
].freeze
PAGE_HEADERS_CURL_ARGS =

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.

curl arguments used in Strategy#page_headers method.

([
  # We only need the response head (not the body)
  "--head",
  # Some servers may not allow a HEAD request, so we use GET
  "--request", "GET"
] + DEFAULT_CURL_ARGS).freeze
PAGE_CONTENT_CURL_ARGS =

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.

curl arguments used in Strategy#page_content method.

([
  "--compressed",
  # Include HTTP response headers in output, so we can identify the
  # final URL after any redirections
  "--include",
] + DEFAULT_CURL_ARGS).freeze
DEFAULT_CURL_OPTIONS =

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.

Baseline curl options used in Homebrew::Livecheck::Strategy methods.

{
  print_stdout:    false,
  print_stderr:    false,
  debug:           false,
  verbose:         false,
  timeout:         CURL_PROCESS_TIMEOUT,
  connect_timeout: CURL_CONNECT_TIMEOUT,
  max_time:        CURL_MAX_TIME,
  retries:         0,
}.freeze
TARBALL_EXTENSION_REGEX =

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.

A regex used to identify a tarball extension at the end of a string.

/
  \.t
  (?:ar(?:\.(?:bz2|gz|lz|lzma|lzo|xz|Z|zst))?|
  b2|bz2?|z2|az|gz|lz|lzma|xz|Z|aZ|zst)
  $
/ix.freeze
INVALID_BLOCK_RETURN_VALUE_MSG =

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.

An error message to use when a strategy block returns a value of an inappropriate type.

"Return value of a strategy block must be a string or array of strings."

Class Method Summary collapse

Class Method Details

.from_symbol(symbol) ⇒ 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.

Returns the strategy that corresponds to the provided Symbol (or nil if there is no matching strategy).

Parameters:

  • symbol (Symbol, nil) —

    the strategy name in snake case as a Symbol (e.g. :page_match)

Returns:

  • (T.untyped) 


128
129
130
 
# File 'livecheck/strategy.rb', line 128

def from_symbol(symbol)
  strategies[symbol] if symbol.present?
end

.from_url(url, livecheck_strategy: nil, url_provided: false, regex_provided: false, block_provided: false) ⇒ Array<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.

Returns an array of strategies that apply to the provided URL.

Parameters:

  • url (String) —

    the URL to check for matching strategies

  • livecheck_strategy (Symbol, nil) (defaults to: nil) —

    a strategy symbol from the livecheck block

  • url_provided (Boolean) (defaults to: false) —

    whether a url is provided in the livecheck block

  • regex_provided (Boolean) (defaults to: false) —

    whether a regex is provided in the livecheck block

  • block_provided (Boolean) (defaults to: false) —

    whether a strategy block is provided in the livecheck block

Returns:

  • (Array<T.untyped>) 


153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'livecheck/strategy.rb', line 153

def from_url(url, livecheck_strategy: nil, url_provided: false, regex_provided: false, block_provided: false)
  usable_strategies = strategies.values.select do |strategy|
    if strategy == PageMatch
      # Only treat the `PageMatch` strategy as usable if a regex is
      # present in the `livecheck` block
      next if !regex_provided && !block_provided
    elsif strategy.const_defined?(:PRIORITY) &&
          !strategy::PRIORITY.positive? &&
          from_symbol(livecheck_strategy) != strategy
      # Ignore strategies with a priority of 0 or lower, unless the
      # strategy is specified in the `livecheck` block
      next
    end

    strategy.respond_to?(:match?) && strategy.match?(url)
  end

  # Sort usable strategies in descending order by priority, using the
  # DEFAULT_PRIORITY when a strategy doesn't contain a PRIORITY constant
  usable_strategies.sort_by do |strategy|
    (strategy.const_defined?(:PRIORITY) ? -strategy::PRIORITY : -DEFAULT_PRIORITY)
  end
end

.handle_block_return(value) ⇒ 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.

Handles the return value from a strategy block in a livecheck block.

Parameters:

  • value (T.untyped) —

    [] the return value from a strategy block

Returns:



249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'livecheck/strategy.rb', line 249

def self.handle_block_return(value)
  case value
  when String
    [value]
  when Array
    value.compact.uniq
  when nil
    []
  else
    raise TypeError, INVALID_BLOCK_RETURN_VALUE_MSG
  end
end

.page_content(url, homebrew_curl: false) ⇒ Hash{Symbol => 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.

Fetches the content at the URL and returns a hash containing the content and, if there are any redirections, the final URL. If curl encounters an error, the hash will contain a :messages array with the error message instead.

Parameters:

  • url (String) —

    the URL of the content to check

  • homebrew_curl (Boolean) (defaults to: false) —

    whether to use brewed curl with the URL

Returns:



214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
 
# File 'livecheck/strategy.rb', line 214

def self.page_content(url, homebrew_curl: false)
  stderr = nil
  [:default, :browser].each do |user_agent|
    stdout, stderr, status = curl_with_workarounds(
      *PAGE_CONTENT_CURL_ARGS, url,
      **DEFAULT_CURL_OPTIONS,
      use_homebrew_curl: homebrew_curl,
      user_agent:        user_agent
    )
    next unless status.success?

    # stdout contains the header information followed by the page content.
    # We use #scrub here to avoid "invalid byte sequence in UTF-8" errors.
    output = stdout.scrub

    # Separate the head(s)/body and identify the final URL (after any
    # redirections)
    parsed_output = parse_curl_output(output, max_iterations: MAX_PARSE_ITERATIONS)
    final_url = curl_response_last_location(parsed_output[:responses], absolutize: true, base_url: url)

    data = { content: parsed_output[:body] }
    data[:final_url] = final_url if final_url.present? && final_url != url
    return data
  end

  error_msgs = stderr&.scan(/^curl:.+$/)
  { messages: error_msgs.presence || ["cURL failed without a detectable error"] }
end

.page_headers(url, homebrew_curl: false) ⇒ Array<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.

Collects HTTP response headers, starting with the provided URL. Redirections will be followed and all the response headers are collected into an array of hashes.

Parameters:

  • url (String) —

    the URL to fetch

  • homebrew_curl (Boolean) (defaults to: false) —

    whether to use brewed curl with the URL

Returns:



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'livecheck/strategy.rb', line 185

def self.page_headers(url, homebrew_curl: false)
  headers = []

  [:default, :browser].each do |user_agent|
    output, _, status = curl_with_workarounds(
      *PAGE_HEADERS_CURL_ARGS, url,
      **DEFAULT_CURL_OPTIONS,
      use_homebrew_curl: homebrew_curl,
      user_agent:        user_agent
    )
    next unless status.success?

    parsed_output = parse_curl_output(output, max_iterations: MAX_PARSE_ITERATIONS)
    parsed_output[:responses].each { |response| headers << response[:headers] }
    break if headers.present?
  end

  headers
end