bolt 2.16.0 → 2.21.0

data/lib/bolt/config/transport/ssh.rb

@@ -32,13 +32,14 @@ module Bolt
           user
         ].concat(RUN_AS_OPTIONS).sort.freeze
 
-        # Options available when using the external ssh transport
-        EXTERNAL_OPTIONS = %w[
+        # Options available when using the native ssh transport
+        NATIVE_OPTIONS = %w[
           cleanup
           copy-command
           host
           host-key-check
           interpreters
+          native-ssh
           port
           private-key
           script-dir
@@ -56,17 +57,30 @@ module Bolt
           "tty"                => false
         }.freeze
 
-        # The set of options available for the ssh and external ssh transports overlap, so we
+        # The set of options available for the ssh and native ssh transports overlap, so we
         # need to check which transport is used before fully initializing, otherwise options
         # may not be filtered correctly.
         def initialize(data = {}, project = nil)
           assert_hash_or_config(data)
-          @external = true if data['ssh-command']
+          @native = true if data['native-ssh']
           super(data, project)
         end
 
+        # This method is used to filter CLI options in the Config class. This
+        # should include `ssh-command` so that we can later warn if the option
+        # is present without `native-ssh`
+        def self.options
+          %w[ssh-command native-ssh].concat(OPTIONS)
+        end
+
         private def filter(unfiltered)
-          @external ? unfiltered.slice(*EXTERNAL_OPTIONS) : unfiltered.slice(*OPTIONS)
+          # Because we filter before merging config together it's impossible to
+          # know whether both ssh-command *and* native-ssh will be specified
+          # unless they are both in the filter. However, we can't add
+          # ssh-command to OPTIONS since that's used for documenting available
+          # options. This makes it so that ssh-command is preserved so we can
+          # warn once all config is resolved if native-ssh isn't set.
+          @native ? unfiltered.slice(*NATIVE_OPTIONS) : unfiltered.slice(*self.class.options)
         end
 
         private def validate
@@ -83,11 +97,11 @@ module Bolt
               @config['private-key'] = File.expand_path(key_opt, @project)
 
               # We have an explicit test for this to only warn if using net-ssh transport
-              Bolt::Util.validate_file('ssh key', @config['private-key']) if @config['ssh-command']
+              Bolt::Util.validate_file('ssh key', @config['private-key']) if @config['native-ssh']
             end
 
-            if key_opt.instance_of?(Hash) && @config['ssh-command']
-              raise Bolt::ValidationError, 'private-key must be a filepath when using ssh-command'
+            if key_opt.instance_of?(Hash) && @config['native-ssh']
+              raise Bolt::ValidationError, 'private-key must be a filepath when using native-ssh'
             end
           end
 
@@ -117,8 +131,8 @@ module Bolt
             end
           end
 
-          if @config['ssh-command'] && !@config['load-config']
-            msg = 'Cannot use external SSH transport with load-config set to false'
+          if @config['native-ssh'] && !@config['load-config']
+            msg = 'Cannot use native SSH transport with load-config set to false'
             raise Bolt::ValidationError, msg
           end
         end

data/lib/bolt/executor.rb

@@ -320,6 +320,27 @@ module Bolt
       end
     end
 
+    def download_file(targets, source, destination, options = {})
+      description = options.fetch(:description, "file download from #{source} to #{destination}")
+
+      begin
+        FileUtils.mkdir_p(destination)
+      rescue Errno::EEXIST => e
+        message = "#{e.message}; unable to create destination directory #{destination}"
+        raise Bolt::Error.new(message, 'bolt/file-exist-error')
+      end
+
+      log_action(description, targets) do
+        options[:run_as] = run_as if run_as && !options.key?(:run_as)
+
+        batch_execute(targets) do |transport, batch|
+          with_node_logging("Downloading file #{source} to #{destination}", batch) do
+            transport.batch_download(batch, source, destination, options, &method(:publish_event))
+          end
+        end
+      end
+    end
+
     def run_plan(scope, plan, params)
       plan.call_by_name_with_scope(scope, params, true)
     end

data/lib/bolt/inventory/group.rb

@@ -50,10 +50,11 @@ module Bolt
           # or it could be a name/alias of a target defined in another group.
           # We can't tell the difference until all groups have been resolved,
           # so we store the string on its own here and process it later.
-          if target.is_a?(String)
+          case target
+          when String
             @string_targets << target
           # Handle plugins at this level so that lookups cannot trigger recursive lookups
-          elsif target.is_a?(Hash)
+          when Hash
             add_target_definition(target)
           else
             raise ValidationError.new("Target entry must be a String or Hash, not #{target.class}", @name)

data/lib/bolt/inventory/inventory.rb

@@ -109,11 +109,12 @@ module Bolt
       private :resolve_name
 
       def expand_targets(targets)
-        if targets.is_a? Bolt::Target
+        case targets
+        when Bolt::Target
           targets
-        elsif targets.is_a? Array
+        when Array
           targets.map { |tish| expand_targets(tish) }
-        elsif targets.is_a? String
+        when String
           # Expand a comma-separated list
           targets.split(/[[:space:],]+/).reject(&:empty?).map do |name|
             ts = resolve_name(name)

data/lib/bolt/logger.rb

@@ -15,6 +15,7 @@ module Bolt
       return if Logging.initialized?
 
       Logging.init :debug, :info, :notice, :warn, :error, :fatal, :any
+      @mutex = Mutex.new
 
       Logging.color_scheme(
         'bolt',
@@ -66,6 +67,10 @@ module Bolt
       end
     end
 
+    def self.analytics=(analytics)
+      @analytics = analytics
+    end
+
     def self.console_layout(color)
       color_scheme = :bolt if color
       Logging.layouts.pattern(
@@ -89,8 +94,10 @@ module Bolt
       :notice
     end
 
+    # Explicitly check the log level names instead of the log level number, as levels
+    # that are stringified integers (e.g. "level" => "42") will return a truthy value
     def self.valid_level?(level)
-      !Logging.level_num(level).nil?
+      Logging::LEVELS.include?(Logging.levelify(level))
     end
 
     def self.levels
@@ -100,5 +107,21 @@ module Bolt
     def self.reset_logging
       Logging.reset
     end
+
+    def self.warn_once(type, msg)
+      @mutex.synchronize {
+        @warnings ||= []
+        @logger ||= Logging.logger[self]
+        unless @warnings.include?(type)
+          @logger.warn(msg)
+          @warnings << type
+        end
+      }
+    end
+
+    def self.deprecation_warning(type, msg)
+      @analytics&.event('Warn', 'deprecation', label: type)
+      warn_once(type, msg)
+    end
   end
 end

data/lib/bolt/outputter.rb

@@ -26,5 +26,5 @@ end
 
 require 'bolt/outputter/human'
 require 'bolt/outputter/json'
-require 'bolt/outputter/rainbow'
 require 'bolt/outputter/logger'
+require 'bolt/outputter/rainbow'

data/lib/bolt/outputter/rainbow.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
 require 'bolt/pal'
-require 'paint'
 
 module Bolt
   class Outputter
     class Rainbow < Bolt::Outputter::Human
       def initialize(color, verbose, trace, stream = $stdout)
+        begin
+          require 'paint'
+          if Bolt::Util.windows?
+            # the Paint gem thinks that windows does not support ansi colors
+            # but windows 10 or later does
+            # we can display colors if we force mode to TRUE_COLOR
+            Paint.mode = 0xFFFFFF
+          end
+        rescue LoadError
+          raise "The 'paint' gem is required to use the rainbow outputter."
+        end
         super
         @line_color = 0
         @color = 0
@@ -29,9 +39,10 @@ module Bolt
             a = string.chars.map do |c|
               case @state
               when :normal
-                if c == "\e"
+                case c
+                when "\e"
                   @state = :ansi
-                elsif c == "\n"
+                when "\n"
                   @line_color += 1
                   @color = @line_color
                   c

data/lib/bolt/pal.rb

@@ -15,25 +15,36 @@ module Bolt
     # PALError is used to convert errors from executing puppet code into
     # Bolt::Errors
     class PALError < Bolt::Error
-      # Puppet sometimes rescues exceptions notes the location and reraises.
-      # Return the original error.
       def self.from_preformatted_error(err)
         if err.cause&.is_a? Bolt::Error
           err.cause
         else
-          from_error(err.cause || err)
+          from_error(err)
         end
       end
 
       # Generate a Bolt::Pal::PALError for non-bolt errors
       def self.from_error(err)
-        e = new(err.message)
+        # Use the original error message if available
+        message = err.cause ? err.cause.message : err.message
+
+        # Provide the location of an error if it came from a plan
+        details = if defined?(err.file) && err.file
+                    { file:   err.file,
+                      line:   err.line,
+                      column: err.pos }.compact
+                  else
+                    {}
+                  end
+
+        e = new(message, details)
+
         e.set_backtrace(err.backtrace)
         e
       end
 
-      def initialize(msg)
-        super(msg, 'bolt/pal-error')
+      def initialize(msg, details = {})
+        super(msg, 'bolt/pal-error', details)
       end
     end
 
@@ -139,7 +150,12 @@ module Bolt
       r = Puppet::Pal.in_tmp_environment('bolt', modulepath: @modulepath, facts: {}) do |pal|
         # Only load the project if it a) exists, b) has a name it can be loaded with
         bolt_project = @project if @project&.name
+        # Puppet currently won't receive the project unless it is a named project. Since
+        # the download_file plan function needs access to the project path, add it to the
+        # context.
+        bolt_project_data = @project
         Puppet.override(bolt_project: bolt_project,
+                        bolt_project_data: bolt_project_data,
                         yaml_plan_instantiator: Bolt::PAL::YamlPlan::Loader) do
           pal.with_script_compiler do |compiler|
             alias_types(compiler)
@@ -159,8 +175,9 @@ module Bolt
               if e.issue_code == :UNKNOWN_VARIABLE &&
                  %w[facts trusted server_facts settings].include?(e.arguments[:name])
                 message = "Evaluation Error: Variable '#{e.arguments[:name]}' is not available in the current scope "\
-                  "unless explicitly defined. (file: #{e.file}, line: #{e.line}, column: #{e.pos})"
-                PALError.new(message)
+                          "unless explicitly defined."
+                details = { file: e.file, line: e.line, column: e.pos }
+                PALError.new(message, details)
               else
                 PALError.from_preformatted_error(e)
               end
@@ -267,9 +284,10 @@ module Bolt
 
     def parse_params(type, object_name, params)
       in_bolt_compiler do |compiler|
-        if type == 'task'
+        case type
+        when 'task'
           param_spec = compiler.task_signature(object_name)&.task_hash&.dig('parameters')
-        elsif type == 'plan'
+        when 'plan'
           plan = compiler.plan_signature(object_name)
           param_spec = plan.params_type.elements&.each_with_object({}) { |t, h| h[t.name] = t.value_type } if plan
         end

data/lib/bolt/pal/yaml_plan/evaluator.rb

@@ -73,7 +73,7 @@ module Bolt
         end
 
         def upload_step(scope, step)
-          source = step['source']
+          source = step['upload'] || step['source']
           destination = step['destination']
           targets = step['targets'] || step['target']
           description = step['description']
@@ -83,6 +83,17 @@ module Bolt
           scope.call_function('upload_file', args)
         end
 
+        def download_step(scope, step)
+          source = step['download']
+          destination = step['destination']
+          targets = step['targets'] || step['target']
+          description = step['description']
+
+          args = [source, destination, targets]
+          args << description if description
+          scope.call_function('download_file', args)
+        end
+
         def eval_step(_scope, step)
           step['eval']
         end
@@ -97,6 +108,10 @@ module Bolt
           apply_manifest(scope, targets, manifest)
         end
 
+        def message_step(scope, step)
+          scope.call_function('out::message', step['message'])
+        end
+
         def generate_manifest(resources)
           # inspect returns the Ruby representation of the resource hashes,
           # which happens to be the same as the Puppet representation
@@ -142,7 +157,13 @@ module Bolt
           if plan.steps.any? { |step| step.body.key?('target') }
             msg = "The 'target' parameter for YAML plan steps is deprecated and will be removed "\
                   "in a future version of Bolt. Use the 'targets' parameter instead."
-            @logger.warn(msg)
+            Bolt::Logger.deprecation_warning("Using 'target' parameter for YAML plan steps, not 'targets'", msg)
+          end
+
+          if plan.steps.any? { |step| step.body.key?('source') }
+            msg = "The 'source' parameter for YAML plan upload steps is deprecated and will be removed "\
+                  "in a future version of Bolt. Use the 'upload' parameter instead."
+            Bolt::Logger.deprecation_warning("Using 'source' parameter for YAML upload steps, not 'upload'", msg)
           end
 
           plan_result = closure_scope.with_local_scope(args_hash) do |scope|

data/lib/bolt/pal/yaml_plan/step.rb

@@ -12,7 +12,19 @@ module Bolt
           Set['name', 'description', 'target', 'targets']
         end
 
-        STEP_KEYS = %w[command script task plan source destination eval resources].freeze
+        STEP_KEYS = %w[
+          command
+          destination
+          download
+          eval
+          message
+          plan
+          resources
+          script
+          source
+          task
+          upload
+        ].freeze
 
         def self.create(step_body, step_number)
           type_keys = (STEP_KEYS & step_body.keys)
@@ -22,8 +34,10 @@ module Bolt
           when 1
             type = type_keys.first
           else
-            if type_keys.to_set == Set['source', 'destination']
+            if [Set['source', 'destination'], Set['upload', 'destination']].include?(type_keys.to_set)
               type = 'upload'
+            elsif type_keys.to_set == Set['download', 'destination']
+              type = 'download'
             else
               raise step_error("Multiple action keys detected: #{type_keys.inspect}", step_body['name'], step_number)
             end
@@ -89,6 +103,12 @@ module Bolt
             missing_keys -= ['targets']
           end
 
+          # Handle cases where upload step uses deprecated 'source' key instead of 'upload'
+          # TODO: Remove when 'source' is removed
+          if body.include?('source')
+            missing_keys -= ['upload']
+          end
+
           if missing_keys.any?
             error_message = "The #{step_type.inspect} step requires: #{missing_keys.to_a.inspect} key(s)"
             err = step_error(error_message, body['name'], step_number)
@@ -156,3 +176,5 @@ require 'bolt/pal/yaml_plan/step/resources'
 require 'bolt/pal/yaml_plan/step/script'
 require 'bolt/pal/yaml_plan/step/task'
 require 'bolt/pal/yaml_plan/step/upload'
+require 'bolt/pal/yaml_plan/step/download'
+require 'bolt/pal/yaml_plan/step/message'

data/lib/bolt/pal/yaml_plan/step/download.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Bolt
+  class PAL
+    class YamlPlan
+      class Step
+        class Download < Step
+          def self.allowed_keys
+            super + Set['download', 'destination']
+          end
+
+          def self.required_keys
+            Set['download', 'destination', 'targets']
+          end
+
+          def initialize(step_body)
+            super
+            @source = step_body['download']
+            @destination = step_body['destination']
+          end
+
+          def transpile
+            code = String.new("  ")
+            code << "$#{@name} = " if @name
+
+            fn = 'download_file'
+            args = [@source, @destination, @targets]
+            args << @description if @description
+
+            code << function_call(fn, args)
+
+            code << "\n"
+          end
+        end
+      end
+    end
+  end
+end