bolt 2.19.0 → 2.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84c1deb7ddf2b30daf415a36f7949544d3113db8ae05cf927516cf0ecfb21ca8
-  data.tar.gz: 233d6da93d218e63e50287cbcb5ea863a16f15aa8ae6b02c62f26e87d1d43197
+  metadata.gz: a72c179da8e6e3fd3d8f883366e88f98026de00eee08ae2410515b2103a3810d
+  data.tar.gz: 968edc1c0c30a370ed06b1c9bd5498ccaaaa5e15f3c47307cad1e68f2af5dafb
 SHA512:
-  metadata.gz: a9432c3f9d79ae864971ed4e37cd258fe884b5f96addb7dac19688b9b0a8e9b8044a686321b8f6dbaecf0fdfd41ba962ae9b67d0dbc88744357acd8fafa07e15
-  data.tar.gz: 0a62d1499e578c06900855c5cca20e834a73a7a572f81feb602e60fe72775c02cfba97c39a224477b69098948bf2d40c4dc4229ff4e43d3cb784d4d787dc2d85
+  metadata.gz: a906282180c5df824978979d8e12da5cbe2f835ccef2ae65f2e2fc892bcfa1514a4f8f76418b866fe9cbfe8ce8f8f28b66306055b7acc67de6a7a2e13bb7edbf
+  data.tar.gz: ee4c33740e8e29ad4b3026e5b75b3f0d29556c92e9277bc34101c5f8acfe80db599389c8544aab5946c6c444502a49ddb515da0a854b5796b0aae54fc0875ffc

data/bolt-modules/boltlib/lib/puppet/functions/download_file.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'bolt/error'
+
+# Downloads the given file or directory from the given set of targets and saves it to a directory
+# matching the target's name under the given destination directory. Returns the result from each
+# download. This does nothing if the list of targets is empty.
+#
+# > **Note:** Existing content in the destination directory is deleted before downloading from
+# > the targets.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:download_file, Puppet::Functions::InternalFunction) do
+  # Download a file or directory.
+  # @param source The absolute path to the file or directory on the target(s).
+  # @param destination The relative path to the destination directory on the local system. Expands
+  #                    relative to `<project>/downloads/`.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @return A list of results, one entry per target, with the path to the downloaded file under the
+  #         `path` key.
+  # @example Download a file from multiple Linux targets to a destination directory
+  #   download_file('/etc/ssh/ssh_config', '~/Downloads', $targets)
+  # @example Download a directory from multiple Linux targets to a project downloads directory
+  #   download_file('/etc/ssh', 'ssh', $targets)
+  # @example Download a file from multiple Linux targets and compare its contents to a local file
+  #   $results = download_file($source, $destination, $targets)
+  #
+  #   $local_content = file::read($source)
+  #
+  #   $mismatched_files = $results.filter |$result| {
+  #     $remote_content = file::read($result['path'])
+  #     $remote_content == $local_content
+  #   }
+  dispatch :download_file do
+    param 'String[1]', :source
+    param 'String[1]', :destination
+    param 'Boltlib::TargetSpec', :targets
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  # Download a file or directory, logging the provided description.
+  # @param source The absolute path to the file or directory on the target(s).
+  # @param destination The relative path to the destination directory on the local system. Expands
+  #                    relative to `<project>/downloads/`.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param description A description to be output when calling this function.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @return A list of results, one entry per target, with the path to the downloaded file under the
+  #         `path` key.
+  # @example Download a file from multiple Linux targets to a destination directory
+  #   download_file('/etc/ssh/ssh_config', '~/Downloads', $targets, 'Downloading remote SSH config')
+  dispatch :download_file_with_description do
+    param 'String[1]', :source
+    param 'String[1]', :destination
+    param 'Boltlib::TargetSpec', :targets
+    param 'String', :description
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  def download_file(source, destination, targets, options = {})
+    download_file_with_description(source, destination, targets, nil, options)
+  end
+
+  def download_file_with_description(source, destination, targets, description = nil, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'download_file')
+    end
+
+    options = options.select { |opt| opt.start_with?('_') }.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    options[:description] = description if description
+
+    executor = Puppet.lookup(:bolt_executor)
+    inventory = Puppet.lookup(:bolt_inventory)
+
+    if (destination = destination.strip).empty?
+      raise Bolt::ValidationError, "Destination cannot be an empty string"
+    end
+
+    if (destination = Pathname.new(destination)).absolute?
+      raise Bolt::ValidationError, "Destination must be a relative path, received absolute path #{destination}"
+    end
+
+    # Prevent path traversal so downloads can't be saved outside of the project downloads directory
+    if (destination.each_filename.to_a & %w[. ..]).any?
+      raise Bolt::ValidationError, "Destination must not include path traversal, received #{destination}"
+    end
+
+    # Paths expand relative to the default downloads directory for the project
+    # e.g. ~/.puppetlabs/bolt/downloads/
+    destination = Puppet.lookup(:bolt_project_data).downloads + destination
+
+    # If the destination directory already exists, delete any existing contents
+    if Dir.exist?(destination)
+      FileUtils.rm_r(Dir.glob(destination + '*'), secure: true)
+    end
+
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    # Ensure that that given targets are all Target instances
+    targets = inventory.get_targets(targets)
+    if targets.empty?
+      call_function('debug', "Simulating file download of '#{source}' - no targets given - no action taken")
+      r = Bolt::ResultSet.new([])
+    else
+      r = executor.download_file(targets, source, destination, options)
+    end
+
+    if !r.ok && !options[:catch_errors]
+      raise Bolt::RunFailure.new(r, 'download_file', source)
+    end
+    r
+  end
+end

data/lib/bolt/bolt_option_parser.rb

@@ -36,6 +36,9 @@ module Bolt
         when 'upload'
           { flags: ACTION_OPTS + %w[tmpdir],
             banner: FILE_UPLOAD_HELP }
+        when 'download'
+          { flags: ACTION_OPTS,
+            banner: FILE_DOWNLOAD_HELP }
         else
           { flags: OPTIONS[:global],
             banner: FILE_HELP }
@@ -218,10 +221,30 @@ module Bolt
           bolt file <action> [options]
 
       DESCRIPTION
-          Upload a local file or directory
+          Copy files and directories between the controller and targets
 
       ACTIONS
-          upload        Upload a local file or directory
+          download      Download a file or directory to the controller
+          upload        Upload a local file or directory from the controller
+    HELP
+
+    FILE_DOWNLOAD_HELP = <<~HELP
+      NAME
+          download
+
+      USAGE
+          bolt file download <src> <dest> [options]
+
+      DESCRIPTION
+          Download a file or directory from one or more targets.
+
+          Downloaded files and directories are saved to the a subdirectory
+          matching the target's name under the destination directory. The
+          destination directory is expanded relative to the downloads
+          subdirectory of the project directory.
+
+      EXAMPLES
+          bolt file download /etc/ssh_config ssh_config -t all
     HELP
 
     FILE_UPLOAD_HELP = <<~HELP

data/lib/bolt/catalog.rb

@@ -138,9 +138,10 @@ module Bolt
         # That means the apply body either a) consists of just a
         # NodeDefinition, b) consists of a BlockExpression which may
         # contain NodeDefinitions, or c) doesn't contain NodeDefinitions.
-        definitions = if ast.is_a?(Puppet::Pops::Model::BlockExpression)
+        definitions = case ast
+                      when Puppet::Pops::Model::BlockExpression
                         ast.statements.select { |st| st.is_a?(Puppet::Pops::Model::NodeDefinition) }
-                      elsif ast.is_a?(Puppet::Pops::Model::NodeDefinition)
+                      when Puppet::Pops::Model::NodeDefinition
                         [ast]
                       else
                         []

data/lib/bolt/cli.rb

@@ -32,7 +32,7 @@ module Bolt
                  'script' => %w[run],
                  'task' => %w[show run],
                  'plan' => %w[show run convert],
-                 'file' => %w[upload],
+                 'file' => %w[download upload],
                  'puppetfile' => %w[install show-modules generate-types],
                  'secret' => %w[encrypt decrypt createkeys],
                  'inventory' => %w[show],
@@ -75,72 +75,100 @@ module Bolt
     end
     private :help?
 
+    # Wrapper method that is called by the Bolt executable. Parses the command and
+    # then loads the project and config. Once config is loaded, it completes the
+    # setup process by configuring Bolt and issuing warnings.
+    #
+    # This separation is needed since the Bolt::Outputter class that normally handles
+    # printing errors relies on config being loaded. All setup that happens before
+    # config is loaded will have errors printed directly to stdout, while all errors
+    # raised after config is loaded are handled by the outputter.
     def parse
-      begin
-        parser = BoltOptionParser.new(options)
-        # This part aims to handle both `bolt <mode> --help` and `bolt help <mode>`.
-        remaining = handle_parser_errors { parser.permute(@argv) } unless @argv.empty?
-        if @argv.empty? || help?(remaining)
-          # Update the parser for the subcommand (or lack thereof)
-          parser.update
-          puts parser.help
-          raise Bolt::CLIExit
+      parse_command
+      load_config
+      finalize_setup
+    end
+
+    # Parses the command and validates options. All errors that are raised here
+    # are not handled by the outputter, as it relies on config being loaded.
+    def parse_command
+      parser = BoltOptionParser.new(options)
+      # This part aims to handle both `bolt <mode> --help` and `bolt help <mode>`.
+      remaining = handle_parser_errors { parser.permute(@argv) } unless @argv.empty?
+      if @argv.empty? || help?(remaining)
+        # Update the parser for the subcommand (or lack thereof)
+        parser.update
+        puts parser.help
+        raise Bolt::CLIExit
+      end
+
+      options[:object] = remaining.shift
+
+      # Only parse task_options for task or plan
+      if %w[task plan].include?(options[:subcommand])
+        task_options, remaining = remaining.partition { |s| s =~ /.+=/ }
+        if options[:task_options]
+          unless task_options.empty?
+            raise Bolt::CLIError,
+                  "Parameters must be specified through either the --params " \
+                  "option or param=value pairs, not both"
+          end
+          options[:params_parsed] = true
+        elsif task_options.any?
+          options[:params_parsed] = false
+          options[:task_options] = Hash[task_options.map { |a| a.split('=', 2) }]
+        else
+          options[:params_parsed] = true
+          options[:task_options] = {}
         end
+      end
+      options[:leftovers] = remaining
 
-        options[:object] = remaining.shift
+      # Default to verbose for everything except plans
+      unless options.key?(:verbose)
+        options[:verbose] = options[:subcommand] != 'plan'
+      end
 
-        # Only parse task_options for task or plan
-        if %w[task plan].include?(options[:subcommand])
-          task_options, remaining = remaining.partition { |s| s =~ /.+=/ }
-          if options[:task_options]
-            unless task_options.empty?
-              raise Bolt::CLIError,
-                    "Parameters must be specified through either the --params " \
-                    "option or param=value pairs, not both"
-            end
-            options[:params_parsed] = true
-          elsif task_options.any?
-            options[:params_parsed] = false
-            options[:task_options] = Hash[task_options.map { |a| a.split('=', 2) }]
-          else
-            options[:params_parsed] = true
-            options[:task_options] = {}
-          end
-        end
-        options[:leftovers] = remaining
-
-        validate(options)
-
-        @config = if ENV['BOLT_PROJECT']
-                    project = Bolt::Project.create_project(ENV['BOLT_PROJECT'], 'environment')
-                    Bolt::Config.from_project(project, options)
-                  elsif options[:configfile]
-                    Bolt::Config.from_file(options[:configfile], options)
-                  else
-                    project = if options[:boltdir]
-                                dir = Pathname.new(options[:boltdir])
-                                if (dir + Bolt::Project::BOLTDIR_NAME).directory?
-                                  Bolt::Project.create_project(dir + Bolt::Project::BOLTDIR_NAME)
-                                else
-                                  Bolt::Project.create_project(dir)
-                                end
+      validate(options)
+
+      # Deprecation warnings can't be issued until after config is loaded, so
+      # store them for later.
+      @parser_deprecations = parser.deprecations
+    rescue Bolt::Error => e
+      fatal_error(e)
+      raise e
+    end
+
+    # Loads the project and configuration. All errors that are raised here are not
+    # handled by the outputter, as it relies on config being loaded.
+    def load_config
+      @config = if ENV['BOLT_PROJECT']
+                  project = Bolt::Project.create_project(ENV['BOLT_PROJECT'], 'environment')
+                  Bolt::Config.from_project(project, options)
+                elsif options[:configfile]
+                  Bolt::Config.from_file(options[:configfile], options)
+                else
+                  project = if options[:boltdir]
+                              dir = Pathname.new(options[:boltdir])
+                              if (dir + Bolt::Project::BOLTDIR_NAME).directory?
+                                Bolt::Project.create_project(dir + Bolt::Project::BOLTDIR_NAME)
                               else
-                                Bolt::Project.find_boltdir(Dir.pwd)
+                                Bolt::Project.create_project(dir)
                               end
-                    Bolt::Config.from_project(project, options)
-                  end
-
-        Bolt::Logger.configure(config.log, config.color)
-        Bolt::Logger.analytics = analytics
-      rescue Bolt::Error => e
-        if $stdout.isatty
-          # Print the error message in red, mimicking outputter.fatal_error
-          $stdout.puts("\033[31m#{e.message}\033[0m")
-        else
-          $stdout.puts(e.message)
-        end
-        raise e
-      end
+                            else
+                              Bolt::Project.find_boltdir(Dir.pwd)
+                            end
+                  Bolt::Config.from_project(project, options)
+                end
+    rescue Bolt::Error => e
+      fatal_error(e)
+      raise e
+    end
+
+    # Completes the setup process by configuring Bolt and issuing warnings
+    def finalize_setup
+      Bolt::Logger.configure(config.log, config.color)
+      Bolt::Logger.analytics = analytics
 
       # Logger must be configured before checking path case and project file, otherwise warnings will not display
       config.check_path_case('modulepath', config.modulepath)
@@ -151,28 +179,11 @@ module Bolt
 
       # Display warnings created during parser and config initialization
       config.warnings.each { |warning| @logger.warn(warning[:msg]) }
-      parser.deprecations.each { |dep| Bolt::Logger.deprecation_warning(dep[:type], dep[:msg]) }
+      @parser_deprecations.each { |dep| Bolt::Logger.deprecation_warning(dep[:type], dep[:msg]) }
       config.deprecations.each { |dep| Bolt::Logger.deprecation_warning(dep[:type], dep[:msg]) }
 
-      # After validation, initialize inventory and targets. Errors here are better to catch early.
-      # After this step
-      # options[:target_args] will contain a string/array version of the targetting options this is passed to plans
-      # options[:targets] will contain a resolved set of Target objects
-      unless options[:subcommand] == 'puppetfile' ||
-             options[:subcommand] == 'secret' ||
-             options[:subcommand] == 'project' ||
-             options[:action] == 'show' ||
-             options[:action] == 'convert'
-
-        update_targets(options)
-      end
-
-      unless options.key?(:verbose)
-        # Default to verbose for everything except plans
-        options[:verbose] = options[:subcommand] != 'plan'
-      end
-
       warn_inventory_overrides_cli(options)
+
       options
     rescue Bolt::Error => e
       outputter.fatal_error(e)
@@ -329,6 +340,17 @@ module Bolt
         exit!
       end
 
+      # Initialize inventory and targets. Errors here are better to catch early.
+      # options[:target_args] will contain a string/array version of the targetting options this is passed to plans
+      # options[:targets] will contain a resolved set of Target objects
+      unless options[:subcommand] == 'puppetfile' ||
+             options[:subcommand] == 'secret' ||
+             options[:subcommand] == 'project' ||
+             options[:action] == 'show' ||
+             options[:action] == 'convert'
+        update_targets(options)
+      end
+
       if options[:action] == 'convert'
         convert_plan(options[:object])
         return 0
@@ -357,30 +379,32 @@ module Bolt
 
       analytics.screen_view(screen, screen_view_fields)
 
-      if options[:action] == 'show'
-        if options[:subcommand] == 'task'
+      case options[:action]
+      when 'show'
+        case options[:subcommand]
+        when 'task'
           if options[:object]
             show_task(options[:object])
           else
             list_tasks
           end
-        elsif options[:subcommand] == 'plan'
+        when 'plan'
           if options[:object]
             show_plan(options[:object])
           else
             list_plans
           end
-        elsif options[:subcommand] == 'inventory'
+        when 'inventory'
           if options[:detail]
             show_targets
           else
             list_targets
           end
-        elsif options[:subcommand] == 'group'
+        when 'group'
           list_groups
         end
         return 0
-      elsif options[:action] == 'show-modules'
+      when 'show-modules'
         list_modules
         return 0
       end
@@ -393,17 +417,19 @@ module Bolt
 
       case options[:subcommand]
       when 'project'
-        if options[:action] == 'init'
+        case options[:action]
+        when 'init'
           code = initialize_project
-        elsif options[:action] == 'migrate'
+        when 'migrate'
           code = migrate_project
         end
       when 'plan'
         code = run_plan(options[:object], options[:task_options], options[:target_args], options)
       when 'puppetfile'
-        if options[:action] == 'generate-types'
+        case options[:action]
+        when 'generate-types'
           code = generate_types
-        elsif options[:action] == 'install'
+        when 'install'
           code = install_puppetfile(config.puppetfile_config, config.puppetfile, config.modulepath)
         end
       when 'secret'
@@ -445,11 +471,22 @@ module Bolt
               src = options[:object]
               dest = options[:leftovers].first
 
+              if src.nil?
+                raise Bolt::CLIError, "A source path must be specified"
+              end
+
               if dest.nil?
                 raise Bolt::CLIError, "A destination path must be specified"
               end
-              validate_file('source file', src, true)
-              executor.upload_file(targets, src, dest, executor_opts)
+
+              case options[:action]
+              when 'download'
+                dest = File.expand_path(dest, Dir.pwd)
+                executor.download_file(targets, src, dest, executor_opts)
+              when 'upload'
+                validate_file('source file', src, true)
+                executor.upload_file(targets, src, dest, executor_opts)
+              end
             end
         end
 
@@ -879,5 +916,15 @@ module Bolt
     def incomplete_install?
       (Dir.children(Bolt::PAL::MODULES_PATH) - %w[aggregate canary puppetdb_fact]).empty?
     end
+
+    # Mimicks the output from Outputter::Human#fatal_error. This should be used to print
+    # errors prior to config being loaded, as the outputter relies on config being loaded.
+    def fatal_error(error)
+      if $stdout.isatty
+        $stdout.puts("\033[31m#{error.message}\033[0m")
+      else
+        $stdout.puts(error.message)
+      end
+    end
   end
 end