Class: Dpl::Ctx::Bash

Inherits:
Cl::Ctx
  • Object
show all
Includes:
FileUtils
Defined in:
lib/dpl/ctx/bash.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(stdout = $stdout, stderr = $stderr) ⇒ Bash

Returns a new instance of Bash.



19
20
21
22
23
24
 
# File 'lib/dpl/ctx/bash.rb', line 19

def initialize(stdout = $stdout, stderr = $stderr)
  @stdout = stdout
  @stderr = stderr
  @folds = 0
  super('dpl', abort: false)
end

Instance Attribute Details

#folds ⇒ Object

Returns the value of attribute folds.



17
18
19
 
# File 'lib/dpl/ctx/bash.rb', line 17

def folds
  @folds
end

#last_err ⇒ Object

Returns the value of attribute last_err.



17
18
19
 
# File 'lib/dpl/ctx/bash.rb', line 17

def last_err
  @last_err
end

#last_out ⇒ Object

Returns the value of attribute last_out.



17
18
19
 
# File 'lib/dpl/ctx/bash.rb', line 17

def last_out
  @last_out
end

#stderr ⇒ Object

Returns the value of attribute stderr.



17
18
19
 
# File 'lib/dpl/ctx/bash.rb', line 17

def stderr
  @stderr
end

#stdout ⇒ Object

Returns the value of attribute stdout.



17
18
19
 
# File 'lib/dpl/ctx/bash.rb', line 17

def stdout
  @stdout
end

Instance Method Details

#apt_get(package, cmd = package, opts = {}) ⇒ Object

Installs an APT package

Installs the APT package with the given name, unless the command is already available (as determined by ‘which [cmd]`.

Parameters:

  • package (String) —

    the package name

  • cmd (String) (defaults to: package) —

    an executable installed by the package, defaults to the package name



154
155
156
157
158
159
 
# File 'lib/dpl/ctx/bash.rb', line 154

def apt_get(package, cmd = package, opts = {})
  return if which(cmd)

  apt_update unless opts[:update].is_a?(FalseClass)
  shell "sudo apt-get -qq install #{package}", retry: true
end

#apt_update ⇒ Object 



161
162
163
 
# File 'lib/dpl/ctx/bash.rb', line 161

def apt_update
  shell 'sudo apt-get update', retry: true
end

#apts_get(packages) ⇒ Object 



139
140
141
142
143
144
145
 
# File 'lib/dpl/ctx/bash.rb', line 139

def apts_get(packages)
  packages = packages.reject { |name, cmd = name| which(cmd || name) }
  return unless packages.any?

  apt_update
  packages.each { |package, cmd| apt_get(package, cmd || package, update: false) }
end

#build_dir ⇒ Object

Returns the current build directory

Uses the environment variable ‘TRAVIS_REPO_SLUG` if present, and defaults to `.` otherwise.

Note that this might return an unexpected string outside of the context of Travis CI build environments if the method is called at a time when the current working directory has changed.



373
374
375
 
# File 'lib/dpl/ctx/bash.rb', line 373

def build_dir
  ENV['TRAVIS_BUILD_DIR'] || '.'
end

#build_number ⇒ Object

Returns the current build number

Returns the value of the environment variable ‘TRAVIS_BUILD_NUMBER` if present.



381
382
383
 
# File 'lib/dpl/ctx/bash.rb', line 381

def build_number
  ENV['TRAVIS_BUILD_NUMBER'] || raise('TRAVIS_BUILD_NUMBER not set')
end

#deprecate_opt(key, msg) ⇒ Object

Outputs a deprecation warning for a given deprecated option key to stderr.

Parameters:

  • key (Symbol) —

    the deprecated option key

  • msg (String or Symbol) —

    the deprecation message. if given a Symbol this will be wrapped into the string “Please use #symbol”.



63
64
65
66
 
# File 'lib/dpl/ctx/bash.rb', line 63

def deprecate_opt(key, msg)
  msg = "please use #{msg}" if msg.is_a?(Symbol)
  warn "Deprecated option #{key} used (#{msg})."
end

#encoding(path) ⇒ Object

Returns the encoding of the given file, as determined by ‘file`.



386
387
388
389
390
391
392
393
394
395
396
397
 
# File 'lib/dpl/ctx/bash.rb', line 386

def encoding(path)
  case `file '#{path}'`
  when /gzip compressed/
    'gzip'
  when /compress'd/
    'compress'
  when /text/
    'text'
  when /data/
    # shrugs?
  end
end

#error(message) ⇒ Object

Raises an exception, halting the deployment process.

The calling executable ‘bin/dpl` will catch the exception, and abort the ruby process with the given error message.

This method is intended to be used for all error conditions that require the deployment process to be aborted.

Raises:



107
108
109
 
# File 'lib/dpl/ctx/bash.rb', line 107

def error(message)
  raise Error, message
end

#failed? ⇒ Boolean

Whether or not the last executed shell command has failed.

Returns:

  • (Boolean) 


324
325
326
 
# File 'lib/dpl/ctx/bash.rb', line 324

def failed?
  !success?
end

#file_size(path) ⇒ Object

Returns the size of the given file path



493
494
495
 
# File 'lib/dpl/ctx/bash.rb', line 493

def file_size(path)
  File.size(path)
end

#fold(msg) ⇒ Object

Folds any log output from the given block

Starts a log fold with the given fold message, calls the block, and closes the fold.

Parameters:

  • msg (String) —

    the message that will appear on the log fold



32
33
34
35
36
37
38
39
40
41
 
# File 'lib/dpl/ctx/bash.rb', line 32

def fold(msg)
  self.folds += 1
  print "travis_fold:start:dpl.#{folds}\r\e[K"
  time do
    info "\e[33m#{msg}\e[0m"
    yield
  end
ensure
  print "\ntravis_fold:end:dpl.#{folds}\r\e[K"
end

#gems_require(gems) ⇒ Object

Requires source files from Ruby gems, installing them on demand if required

Installs the Ruby gems with the given version, if not already installed, and requires the specified source files from that gem.

This happens using the bundler/inline API.

Parameters:

  • gems (Array<String, String, Hash>) —

    Array of gem requirements: gem name, version, and options (‘require`: A single path or a list of paths to source files to require from this Ruby gem)

See Also:



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/dpl/ctx/bash.rb', line 175

def gems_require(gems)
  # A local Gemfile.lock might interfer with bundler/inline, even though
  # it should not. Switching to a temporary dir fixes this.
  Dir.chdir(tmp_dir) do
    require 'bundler/inline'
    info "Installing gem dependencies: #{gems.map { |name, version, _| "#{name} #{"(#{version})" if version}".strip }.join(', ')}"
    env = ENV.to_h
    # Bundler.reset!
    # Gem.loaded_specs.clear
    gemfile do
      source 'https://rubygems.org'
      gems.each { |g| gem(*g) }
    end
    # https://github.com/bundler/bundler/issues/7181
    ENV.replace(env)
  end
end

#git_author_email ⇒ Object

Returns the comitter email of the commit ‘git_sha`.



415
416
417
 
# File 'lib/dpl/ctx/bash.rb', line 415

def git_author_email
  `git log #{git_sha} -n 1 --pretty=%ae`.chomp
end

#git_author_name ⇒ Object

Returns the committer name of the commit ‘git_sha`.



410
411
412
 
# File 'lib/dpl/ctx/bash.rb', line 410

def git_author_name
  `git log #{git_sha} -n 1 --pretty=%an`.chomp
end

#git_branch ⇒ Object

Returns the current branch name



400
401
402
 
# File 'lib/dpl/ctx/bash.rb', line 400

def git_branch
  ENV['TRAVIS_BRANCH'] || git_rev_parse('HEAD')
end

#git_commit_msg ⇒ Object

Returns the message of the commit ‘git_sha`.



405
406
407
 
# File 'lib/dpl/ctx/bash.rb', line 405

def git_commit_msg
  `git log #{git_sha} -n 1 --pretty=%B`.chomp
end

#git_dirty? ⇒ Boolean

Whether or not the git working directory is dirty or has new or deleted files

Returns:

  • (Boolean) 


420
421
422
 
# File 'lib/dpl/ctx/bash.rb', line 420

def git_dirty?
  !`git status --short`.chomp.empty?
end

#git_log(args) ⇒ Object

Returns the output of ‘git log`, using the given args.



425
426
427
 
# File 'lib/dpl/ctx/bash.rb', line 425

def git_log(args)
  `git log #{args}`.chomp
end

#git_ls_files ⇒ Object

Returns the Git log, separated by NULs

Returns the output of ‘git ls-files -z`, which separates log entries by NULs, rather than newline characters.



433
434
435
 
# File 'lib/dpl/ctx/bash.rb', line 433

def git_ls_files
  `git ls-files -z`.split("\x0")
end

#git_ls_remote?(url, ref) ⇒ Boolean

Returns true if the given ref exists remotely

Returns:

  • (Boolean) 


438
439
440
 
# File 'lib/dpl/ctx/bash.rb', line 438

def git_ls_remote?(url, ref)
  Kernel.system("git ls-remote --exit-code #{url} #{ref} > /dev/null 2>&1")
end

#git_remote_urls ⇒ Object

Returns known Git remote URLs



443
444
445
 
# File 'lib/dpl/ctx/bash.rb', line 443

def git_remote_urls
  `git remote -v`.scan(/\t[^\s]+\s/).map(&:strip).uniq
end

#git_rev_parse(ref) ⇒ Object

Returns the sha for the given Git ref



448
449
450
 
# File 'lib/dpl/ctx/bash.rb', line 448

def git_rev_parse(ref)
  `git rev-parse #{ref}`.strip
end

#git_sha ⇒ Object

Returns the current commit sha



458
459
460
 
# File 'lib/dpl/ctx/bash.rb', line 458

def git_sha
  ENV['TRAVIS_COMMIT'] || `git rev-parse HEAD`.chomp
end

#git_tag ⇒ Object

Returns the latest tag name, if any



453
454
455
 
# File 'lib/dpl/ctx/bash.rb', line 453

def git_tag
  `git describe --tags --exact-match 2>/dev/null`.chomp
end

#info(*msgs) ⇒ Object

Outputs an info level message to stdout.



69
70
71
 
# File 'lib/dpl/ctx/bash.rb', line 69

def info(*msgs)
  stdout.puts(*msgs)
end

#last_process_status ⇒ Object

Returns the last child process’ exit status

Internal, and not to be used by implementors. $? is a read-only variable, so we use a method that we can stub during tests.



332
333
334
 
# File 'lib/dpl/ctx/bash.rb', line 332

def last_process_status
  $CHILD_STATUS.success?
end

#logger(level = :info) ⇒ Object

Returns a logger

Returns a logger instance, with the given log level set. This can be used to pass to clients that accept a Ruby logger, such as Faraday, for debugging purposes.

Use with care.

Parameters:

  • level (Symbol) (defaults to: :info) —

    the Ruby logger log level



120
121
122
123
124
 
# File 'lib/dpl/ctx/bash.rb', line 120

def logger(level = :info)
  logger = Logger.new(stderr)
  logger.level = Logger.const_get(level.to_s.upcase)
  logger
end

#machine_name ⇒ Object

Returns the local machine’s hostname



463
464
465
 
# File 'lib/dpl/ctx/bash.rb', line 463

def machine_name
  `hostname`.strip
end

#move_files(paths) ⇒ Object 



497
498
499
500
501
502
 
# File 'lib/dpl/ctx/bash.rb', line 497

def move_files(paths)
  paths.each do |path|
    target = "#{tmp_dir}/#{File.basename(path)}"
    mv(path, target) if File.exist?(path)
  end
end

#mv(src, dest) ⇒ Object 



511
512
513
 
# File 'lib/dpl/ctx/bash.rb', line 511

def mv(src, dest)
  Kernel.system("sudo mv #{src} #{dest} 2> /dev/null")
end

#node_version ⇒ Object

Returns the current Node.js version



468
469
470
 
# File 'lib/dpl/ctx/bash.rb', line 468

def node_version
  `node -v`.sub(/^v/, '').chomp
end

#npm_install(package, cmd = package) ⇒ Object

Installs an NPM package

Installs the NPM package with the given name, unless the command is already available (as determined by ‘which [cmd]`.

Parameters:

  • package (String) —

    the package name

  • cmd (String) (defaults to: package) —

    an executable installed by the package, defaults to the package name



200
201
202
 
# File 'lib/dpl/ctx/bash.rb', line 200

def npm_install(package, cmd = package)
  shell "npm install -g #{package}", retry: true unless which(cmd)
end

#npm_version ⇒ Object

Returns the current NPM version



473
474
475
 
# File 'lib/dpl/ctx/bash.rb', line 473

def npm_version
  `npm --version`
end

#only(hash, *keys) ⇒ Object

Returns a copy of the given hash, reduced to the given keys



540
541
542
 
# File 'lib/dpl/ctx/bash.rb', line 540

def only(hash, *keys)
  hash.select { |key, _| keys.include?(key) }.to_h
end

#open3(cmd, opts) ⇒ Object

Runs a shell command and captures stdout, stderr, and the exit status

Runs the given command using ‘Open3.capture3`, which will capture the stdout and stderr streams, as well as the exit status. I.e. this will not stream log output in real time, but capture the output, and allow implementors to display it later (using the `%out` and `%err` interpolation variables.

Use sparingly.

Parameters:

  • chdir (Hash) —

    a customizable set of options



299
300
301
302
303
 
# File 'lib/dpl/ctx/bash.rb', line 299

def open3(cmd, opts)
  opts = [opts[:chdir] ? only(opts, :chdir) : nil].compact
  out, err, status = Open3.capture3(cmd, *opts)
  [out, err, status.success?]
end

#pip_install(package, cmd = package, version = nil) ⇒ Object

Installs a Python package

Installs the Python package with the given name. A previously installed package is uninstalled before that, but only if ‘version` was given.

Parameters:

  • package (String) —

    Package name (required).

  • cmd (String) (defaults to: package) —

    Executable command installed by that package (optional, defaults to the package name).

  • version (String) (defaults to: nil) —

    Package version (optional).



212
213
214
215
216
217
218
219
220
 
# File 'lib/dpl/ctx/bash.rb', line 212

def pip_install(package, cmd = package, version = nil)
  ENV['VIRTUAL_ENV'] = File.expand_path('~/dpl_venv')
  ENV['PATH'] = File.expand_path("~/dpl_venv/bin:#{ENV['PATH']}")
  shell 'virtualenv ~/dpl_venv', echo: true
  shell 'pip install urllib3[secure]'
  cmd = "pip install #{package}"
  cmd << pip_version(version) if version
  shell cmd, retry: true
end

#pip_version(version) ⇒ Object 



222
223
224
 
# File 'lib/dpl/ctx/bash.rb', line 222

def pip_version(version)
  version =~ /^\d+/ ? "==#{version}" : version
end

#print(chars) ⇒ Object

Prints an info level message to stdout.

This method does not append a newline character to the given message, which usually is not the desired behaviour. The method is intended to be used if an initial, partial message is supposed to be printed, which will be completed later (using the method ‘info`).

For example:

print 'Starting a long running task ...'
run_long_running_task
info 'done.'



85
86
87
 
# File 'lib/dpl/ctx/bash.rb', line 85

def print(chars)
  stdout.print(chars)
end

#python_version ⇒ Object

Returns the current Node.js version



478
479
480
 
# File 'lib/dpl/ctx/bash.rb', line 478

def python_version
  `python --version 2>&1`.sub(/^Python /, '').chomp
end

#repo_name ⇒ Object

Returns current repository name

Uses the environment variable ‘TRAVIS_REPO_SLUG` if present, or the current directory’s base name.

Note that this might return an unexpected string outside of the context of Travis CI build environments if the method is called at a time when the current working directory has changed.



349
350
351
 
# File 'lib/dpl/ctx/bash.rb', line 349

def repo_name
  ENV['TRAVIS_REPO_SLUG'] ? ENV['TRAVIS_REPO_SLUG'].split('/').last : File.basename(Dir.pwd)
end

#repo_slug ⇒ Object

Returns current repository slug

Uses the environment variable ‘TRAVIS_REPO_SLUG` if present, or the last two segmens of the current working directory’s path.

Note that this might return an unexpected string outside of the context of Travis CI build environments if the method is called at a time when the current working directory has changed.



361
362
363
 
# File 'lib/dpl/ctx/bash.rb', line 361

def repo_slug
  ENV['TRAVIS_REPO_SLUG'] || Dir.pwd.split('/')[-2, 2].join('/')
end

#retrying(max, tries = 0, status = false) ⇒ Object 



280
281
282
283
284
285
286
 
# File 'lib/dpl/ctx/bash.rb', line 280

def retrying(max, tries = 0, status = false)
  loop do
    tries += 1
    out, err, status = yield
    return [out, err, status] if status || tries > max
  end
end

#shell(cmd, opts = {}) ⇒ Boolean

Runs a single shell command

This the is the central point of executing any shell commands. It allows two strategies for running commands in subprocesses:

  • Using [Kernel#system](ruby-doc.org/core-2.6.3/Kernel.html#method-i-system) which is the default strategy, and should be used when possible. The stdout and stderr streams will not be captured, but streamed directly to the parent process (so any output on these streams appears in the build log as soon as possible).

  • Using [Open3.capture3](ruby-doc.org/stdlib-2.6.3/libdoc/open3/rdoc/Open3.html#method-c-capture3) which captures both stdout and stderr, and does not automatically output it to the build log. Implementors can choose to display it after the shell command has completed, using the ‘%out` and `%err` interpolation variables. Use sparingly.

The method accepts the following options:

Parameters:

  • cmd (String) —

    the shell command to execute

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :echo (Boolean) —

    output the command to stdout before running it

  • :silence (Boolean) —

    silence all log output by redirecting stdout and stderr to ‘/dev/null`

  • :capture (Boolean) —

    use ‘Open3.capture3` to capture stdout and stderr

  • :python (String) —

    wrap the command into Bash code that enforces the given Python version to be used

  • :retry (String) —

    retries the command 2 more times if it fails

  • :info (String) —

    message to output to stdout if the command has exited with the exit code 0 (supports the interpolation variable ‘$out` for stdout in case it was captured.

  • :assert (String) —

    error message to be raised if the command has exited with a non-zero exit code (supports the interpolation variable ‘$out` for stdout in case it was captured.

Returns:

  • (Boolean) —

    whether or not the command was successful (has exited with the exit code 0)



265
266
267
268
269
270
271
272
273
274
275
276
277
278
 
# File 'lib/dpl/ctx/bash.rb', line 265

def shell(cmd, opts = {})
  cmd = Cmd.new(nil, cmd, opts) if cmd.is_a?(String)
  info cmd.msg if cmd.msg?
  info cmd.echo if cmd.echo?

  @last_out, @last_err, @last_status = retrying(cmd.retry ? 2 : 0) do
    send(cmd.capture? ? :open3 : :system, cmd.cmd, cmd.opts)
  end

  info format(cmd.success, out: last_out) if success? && cmd.success?
  error format(cmd.error, err: last_err) if failed? && cmd.assert?

  success? && cmd.capture? ? last_out.chomp : @last_status
end

#sleep(sec) ⇒ Object 



531
532
533
 
# File 'lib/dpl/ctx/bash.rb', line 531

def sleep(sec)
  Kernel.sleep(sec)
end

#ssh_keygen(name, file) ⇒ Object

Generates an SSH key

Parameters:

  • name (String) —

    the key name

  • file (String) —

    path to the key file



230
231
232
 
# File 'lib/dpl/ctx/bash.rb', line 230

def ssh_keygen(name, file)
  shell %(ssh-keygen -t rsa -N "" -C #{name} -f #{file})
end

#success? ⇒ Boolean

Whether or not the last executed shell command was successful.

Returns:

  • (Boolean) 


319
320
321
 
# File 'lib/dpl/ctx/bash.rb', line 319

def success?
  !!@last_status
end

#sudo? ⇒ Boolean

Whether or not the current Ruby process runs with superuser priviledges.

Returns:

  • (Boolean) 


337
338
339
 
# File 'lib/dpl/ctx/bash.rb', line 337

def sudo?
  Process::UID.eid.zero?
end

#system(cmd, opts = {}) ⇒ Object

Runs a shell command, streaming any stdout or stderr output, and returning the exit status

This is the default method for executing shell commands. The stdout and stderr will not be captured, but streamed directly to the parent process.

Parameters:

  • chdir (Hash) —

    a customizable set of options



312
313
314
315
316
 
# File 'lib/dpl/ctx/bash.rb', line 312

def system(cmd, opts = {})
  opts = [opts[:chdir] ? only(opts, :chdir) : nil].compact
  Kernel.system(cmd, *opts)
  ['', '', last_process_status]
end

#test? ⇒ Boolean

Returns:

  • (Boolean) 


544
545
546
 
# File 'lib/dpl/ctx/bash.rb', line 544

def test?
  false
end

#time ⇒ Object

Times the given block

Starts a travis time log tag, calls the block, and closes the tag, including timing information. This makes a timing badge appear on the surrounding log fold.



48
49
50
51
52
53
54
55
56
57
 
# File 'lib/dpl/ctx/bash.rb', line 48

def time
  id = SecureRandom.hex[0, 8]
  start = Time.now.to_i * (10**9)
  print "travis_time:start:#{id}\r\e[K"
  yield
ensure
  finish = Time.now.to_i * (10**9)
  duration = finish - start
  print "\ntravis_time:end:#{id}:start=#{start},finish=#{finish},duration=#{duration}\r\e[K"
end

#tmp_dir ⇒ Object

Returns a unique temporary directory name



488
489
490
 
# File 'lib/dpl/ctx/bash.rb', line 488

def tmp_dir
  @tmp_dir ||= Dir.mktmpdir
end

#tty? ⇒ Boolean

Returns:

  • (Boolean) 


535
536
537
 
# File 'lib/dpl/ctx/bash.rb', line 535

def tty?
  $stdout.isatty
end

#unmove_files(paths) ⇒ Object 



504
505
506
507
508
509
 
# File 'lib/dpl/ctx/bash.rb', line 504

def unmove_files(paths)
  paths.each do |path|
    source = "#{tmp_dir}/#{File.basename(path)}"
    mv(source, path) if File.exist?(source)
  end
end

#validate_runtime(args) ⇒ Object 



132
133
134
135
136
137
 
# File 'lib/dpl/ctx/bash.rb', line 132

def validate_runtime(args)
  name, required = *args
  info "Validating required runtime version: #{name} (#{required.join(', ')})"
  version = name == :node_js ? node_version : python_version
  required.all? { |required| Version.new(version).satisfies?(required) }
end

#validate_runtimes(runtimes) ⇒ Object 



126
127
128
129
130
 
# File 'lib/dpl/ctx/bash.rb', line 126

def validate_runtimes(runtimes)
  failed = runtimes.reject(&method(:validate_runtime))
  failed = failed.map { |name, versions| "#{name} (#{versions.join(', ')})" }
  error "Failed validating runtimes: #{failed.join(', ')}" if failed.any?
end

#warn(*msgs) ⇒ Object

Outputs an warning message to stderr

This method is intended to be used for warning messages that are supposed to show up in the build log, but do not qualify as errors that would abort the deployment process. The warning will be highlighted as yellow text. Use sparingly.



95
96
97
98
 
# File 'lib/dpl/ctx/bash.rb', line 95

def warn(*msgs)
  msgs = msgs.join("\n").lines
  msgs.each { |msg| stderr.puts("\e[33;1m#{msg}\e[0m") }
end

#which(cmd) ⇒ Object

Returns true or false depending if the given command can be found



483
484
485
 
# File 'lib/dpl/ctx/bash.rb', line 483

def which(cmd)
  !`which #{cmd}`.chomp.empty? if cmd
end

#write_file(path, content, chmod = nil) ⇒ Object

Writes the given content to the given file path



516
517
518
519
520
521
 
# File 'lib/dpl/ctx/bash.rb', line 516

def write_file(path, content, chmod = nil)
  path = File.expand_path(path)
  FileUtils.mkdir_p(File.dirname(path))
  File.open(path, 'w+') { |f| f.write(content) }
  FileUtils.chmod(chmod, path) if chmod
end

#write_netrc(machine, login, password) ⇒ Object

Writes the given machine, login, and password to ~/.netrc



524
525
526
527
528
529
 
# File 'lib/dpl/ctx/bash.rb', line 524

def write_netrc(machine, , password)
  require 'netrc'
  netrc = Netrc.read
  netrc[machine] = [, password]
  netrc.save
end