bolt 3.12.0 → 3.16.0

data/lib/bolt/config/options.rb

@@ -202,7 +202,7 @@ module Bolt
                 "level" => {
                   description: "The type of information to log.",
                   type: String,
-                  enum: %w[trace debug error info warn fatal any],
+                  enum: %w[trace debug error info warn fatal],
                   _default: "warn"
                 }
               }
@@ -221,7 +221,7 @@ module Bolt
               "level" => {
                 description: "The type of information to log.",
                 type: String,
-                enum: %w[trace debug error info warn fatal any],
+                enum: %w[trace debug error info warn fatal],
                 _default: "warn"
               }
             }

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

@@ -16,6 +16,18 @@ module Bolt
             _default: false,
             _example: true
           },
+          "batch-mode" => {
+            type: [TrueClass, FalseClass],
+            description: "Whether to disable password querying. When set to `false`, SSH will fall back to "\
+                         "prompting for a password if key authentication fails. This might cause Bolt to hang. "\
+                         "To prevent Bolt from hanging, you can configure `ssh-command` to use an SSH utility "\
+                         "such as sshpass that supports providing a password non-interactively. For more "\
+                         "information, see [Providing a password non-interactively using "\
+                         "`native-ssh`](troubleshooting.md#providing-a-password-non-interactively-using-native-ssh).",
+            _plugin: true,
+            _default: true,
+            _example: false
+          },
           "bundled-ruby" => {
             description: "Whether to use the Ruby bundled with Bolt packages for local targets.",
             type: [TrueClass, FalseClass],

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

@@ -34,6 +34,7 @@ module Bolt
 
         # Options available when using the native ssh transport
         NATIVE_OPTIONS = %w[
+          batch-mode
           cleanup
           copy-command
           host
@@ -49,6 +50,7 @@ module Bolt
         ].concat(RUN_AS_OPTIONS).sort.freeze
 
         DEFAULTS = {
+          "batch-mode"         => true,
           "cleanup"            => true,
           "connect-timeout"    => 10,
           "disconnect-timeout" => 5,
@@ -124,6 +126,11 @@ module Bolt
             msg = 'Cannot use native SSH transport with load-config set to false'
             raise Bolt::ValidationError, msg
           end
+
+          if !@config['batch-mode'] && !@config['ssh-command']
+            raise Bolt::ValidationError,
+                  'Must set ssh-command when batch-mode is set to false'
+          end
         end
       end
     end

data/lib/bolt/executor.rb

@@ -381,8 +381,16 @@ module Bolt
     # overloaded while also minimizing the Puppet lookups needed from plan
     # functions
     #
-    def create_future(scope: nil, name: nil, &block)
-      @fiber_executor.create_future(scope: scope, name: name, &block)
+    def create_future(plan_id:, scope: nil, name: nil, &block)
+      @fiber_executor.create_future(scope: scope, name: name, plan_id: plan_id, &block)
+    end
+
+    def get_current_future(fiber:)
+      @fiber_executor.get_current_future(fiber: fiber)
+    end
+
+    def get_current_plan_id(fiber:)
+      @fiber_executor.get_current_plan_id(fiber: fiber)
     end
 
     def plan_complete?
@@ -401,8 +409,8 @@ module Bolt
       @fiber_executor.wait(futures, **opts)
     end
 
-    def plan_futures
-      @fiber_executor.plan_futures
+    def get_futures_for_plan(plan_id:)
+      @fiber_executor.get_futures_for_plan(plan_id: plan_id)
     end
 
     # Execute a plan function concurrently. This function accepts the executor

data/lib/bolt/fiber_executor.rb

@@ -5,18 +5,19 @@ require 'bolt/plan_future'
 
 module Bolt
   class FiberExecutor
-    attr_reader :plan_futures
+    attr_reader :active_futures, :finished_futures
 
     def initialize
       @logger = Bolt::Logger.logger(self)
       @id = 0
-      @plan_futures = []
+      @active_futures = []
+      @finished_futures = []
     end
 
     # Whether there is more than one fiber running in parallel.
     #
     def in_parallel?
-      plan_futures.length > 1
+      active_futures.length > 1
     end
 
     # Creates a new Puppet scope from the current Plan scope so that variables
@@ -24,7 +25,7 @@ module Bolt
     # Then creates a new Fiber to execute the block, wraps the Fiber in a
     # Bolt::PlanFuture, and returns the Bolt::PlanFuture.
     #
-    def create_future(scope: nil, name: nil)
+    def create_future(plan_id:, scope: nil, name: nil)
       newscope = nil
       if scope
         # Save existing variables to the new scope before starting the future
@@ -46,13 +47,16 @@ module Bolt
       end
 
       # PlanFutures are assigned an ID, which is just a global incrementing
-      # integer. The main plan should always have ID 0.
+      # integer. The main plan should always have ID 0. They also have a
+      # plan_id, which identifies which plan spawned them. This is used for
+      # tracking which Futures to wait on when `wait()` is called without
+      # arguments.
       @id += 1
-      future = Bolt::PlanFuture.new(future, @id, name)
+      future = Bolt::PlanFuture.new(future, @id, name: name, plan_id: plan_id, scope: newscope)
       @logger.trace("Created future #{future.name}")
 
       # Register the PlanFuture with the FiberExecutor to be executed
-      plan_futures << future
+      active_futures << future
       future
     end
 
@@ -63,12 +67,16 @@ module Bolt
     # the PlanFuture and remove the PlanFuture from the FiberExecutor.
     #
     def round_robin
-      plan_futures.each do |future|
-        # If the Fiber is still running and can be resumed, then resume it
+      active_futures.each do |future|
+        # If the Fiber is still running and can be resumed, then resume it.
+        # Override Puppet's global_scope to prevent ephemerals in other scopes
+        # from being popped off in the wrong order due to race conditions.
+        # This primarily happens when running executor functions from custom
+        # Puppet language functions, but may happen elsewhere.
         @logger.trace("Checking future '#{future.name}'")
         if future.alive?
           @logger.trace("Resuming future '#{future.name}'")
-          future.resume
+          Puppet.override(global_scope: future.scope) { future.resume }
         end
 
         # Once we've restarted the Fiber, check to see if it's finished again
@@ -78,19 +86,19 @@ module Bolt
 
         # If the future errored and the main plan has already exited, log the
         # error at warn level.
-        unless plan_futures.map(&:id).include?(0) || future.state == "done"
+        unless active_futures.map(&:id).include?(0) || future.state == "done"
           Bolt::Logger.warn('errored_futures', "Error in future '#{future.name}': #{future.value}")
         end
 
         # Remove the PlanFuture from the FiberExecutor.
-        plan_futures.delete(future)
+        finished_futures.push(active_futures.delete(future))
       end
 
       # If the Fiber immediately returned or if the Fiber is blocking on a
       # `wait` call, Bolt should pause for long enough that something can
       # execute before checking again. This mitigates CPU
       # thrashing.
-      return unless plan_futures.all? { |f| %i[returned_immediately unfinished].include?(f.value) }
+      return unless active_futures.all? { |f| %i[returned_immediately unfinished].include?(f.value) }
       @logger.trace("Nothing can be resumed. Rechecking in 0.5 seconds.")
 
       sleep(0.5)
@@ -101,12 +109,53 @@ module Bolt
     # Bolt can exit.
     #
     def plan_complete?
-      plan_futures.empty?
+      active_futures.empty?
+    end
+
+    def all_futures
+      active_futures + finished_futures
+    end
+
+    # Get the PlanFuture object that is currently executing
+    #
+    def get_current_future(fiber:)
+      all_futures.select { |f| f.fiber == fiber }.first
+    end
+
+    # Get the plan invocation ID for the PlanFuture that is currently executing
+    #
+    def get_current_plan_id(fiber:)
+      get_current_future(fiber: fiber).current_plan
+    end
+
+    # Get the Future objects associated with a particular plan invocation.
+    #
+    def get_futures_for_plan(plan_id:)
+      all_futures.select { |f| f.original_plan == plan_id }
     end
 
     # Block until the provided PlanFuture objects have finished, or the timeout is reached.
     #
     def wait(futures, timeout: nil, catch_errors: false, **_kwargs)
+      if futures.nil?
+        results = []
+        plan_id = get_current_plan_id(fiber: Fiber.current)
+        # Recollect the futures for this plan until all of the futures have
+        # finished. This ensures that we include futures created inside of
+        # futures being waited on.
+        until (futures = get_futures_for_plan(plan_id: plan_id)).map(&:alive?).none?
+          if futures.map(&:fiber).include?(Fiber.current)
+            msg = "The wait() function cannot be called with no arguments inside a "\
+                  "background block in the same plan."
+            raise Bolt::Error.new(msg, 'bolt/infinite-wait')
+          end
+          # Wait for all the futures we know about so far before recollecting
+          # Futures for the plan and waiting again
+          results = wait(futures, timeout: timeout, catch_errors: catch_errors)
+        end
+        return results
+      end
+
       if timeout.nil?
         Fiber.yield(:unfinished) until futures.map(&:alive?).none?
       else

data/lib/bolt/outputter/human.rb

@@ -78,6 +78,8 @@ module Bolt
           @disable_depth += 1
         when :message
           print_message(event[:message])
+        when :verbose
+          print_message(event[:message]) if @verbose
         end
 
         if enabled?
@@ -308,7 +310,12 @@ module Bolt
         )
       end
 
-      def print_tasks(tasks, modulepath)
+      # List available tasks.
+      #
+      # @param tasks [Array] A list of task names and descriptions.
+      # @param modulepath [Array] The modulepath.
+      #
+      def print_tasks(tasks:, modulepath:)
         command = Bolt::Util.powershell? ? 'Get-BoltTask -Name <TASK NAME>' : 'bolt task show <TASK NAME>'
 
         tasks = tasks.map do |name, description|
@@ -328,8 +335,11 @@ module Bolt
         @stream.puts indent(2, "Use '#{command}' to view details and parameters for a specific task.")
       end
 
-      # @param [Hash] task A hash representing the task
-      def print_task_info(task)
+      # Print information about a task.
+      #
+      # @param task [Bolt::Task] The task information.
+      #
+      def print_task_info(task:)
         params = (task.parameters || []).sort
 
         info = +''
@@ -339,7 +349,7 @@ module Bolt
         info << if task.description
                   indent(2, task.description.chomp)
                 else
-                  indent(2, 'No description')
+                  indent(2, 'No description available.')
                 end
         info << "\n\n"
 
@@ -398,7 +408,7 @@ module Bolt
         info << if plan['description']
                   indent(2, plan['description'].chomp)
                 else
-                  indent(2, 'No description')
+                  indent(2, 'No description available.')
                 end
         info << "\n\n"
 
@@ -441,7 +451,7 @@ module Bolt
         @stream.puts info
       end
 
-      def print_plans(plans, modulepath)
+      def print_plans(plans:, modulepath:)
         command = Bolt::Util.powershell? ? 'Get-BoltPlan -Name <PLAN NAME>' : 'bolt plan show <PLAN NAME>'
 
         plans = plans.map do |name, description|
@@ -461,7 +471,11 @@ module Bolt
         @stream.puts indent(2, "Use '#{command}' to view details and parameters for a specific plan.")
       end
 
-      def print_topics(topics)
+      # Print available guide topics.
+      #
+      # @param topics [Array] The available topics.
+      #
+      def print_topics(topics:, **_kwargs)
         info = +"#{colorize(:cyan, 'Topics')}\n"
         info << indent(2, topics.join("\n"))
         info << "\n\n#{colorize(:cyan, 'Additional information')}\n"
@@ -469,8 +483,20 @@ module Bolt
         @stream.puts info
       end
 
-      def print_guide(guide, _topic)
-        @stream.puts(guide)
+      # Print the guide for the specified topic.
+      #
+      # @param guide [String] The guide.
+      #
+      def print_guide(topic:, guide:, documentation: nil, **_kwargs)
+        info = +"#{colorize(:cyan, topic)}\n"
+        info << indent(2, guide)
+
+        if documentation
+          info << "\n#{colorize(:cyan, 'Documentation')}\n"
+          info << indent(2, documentation.join("\n"))
+        end
+
+        @stream.puts info
       end
 
       def print_plan_lookup(value)
@@ -478,15 +504,19 @@ module Bolt
       end
 
       def print_module_list(module_list)
+        info = +''
+
         module_list.each do |path, modules|
-          if (mod = modules.find { |m| m[:internal_module_group] })
-            @stream.puts(colorize(:cyan, mod[:internal_module_group]))
-          else
-            @stream.puts(colorize(:cyan, path))
-          end
+          info << if (mod = modules.find { |m| m[:internal_module_group] })
+                    colorize(:cyan, mod[:internal_module_group])
+                  else
+                    colorize(:cyan, path)
+                  end
+
+          info << "\n"
 
           if modules.empty?
-            @stream.puts('(no modules installed)')
+            info << '(no modules installed)'
           else
             module_info = modules.map do |m|
               version = if m[:version].nil?
@@ -498,24 +528,100 @@ module Bolt
               [m[:name], version]
             end
 
-            @stream.puts format_table(module_info, 2, 1)
+            info << format_table(module_info, 2, 1).to_s
           end
 
-          @stream.write("\n")
+          info << "\n\n"
         end
+
+        command = Bolt::Util.powershell? ? 'Get-BoltModule -Name <MODULE>' : 'bolt module show <MODULE>'
+        info << colorize(:cyan, "Additional information\n")
+        info << indent(2, "Use '#{command}' to view details for a specific module.")
+
+        @stream.puts info
       end
 
-      def print_plugin_list(plugin_list, modulepath)
+      # Prints detailed module information.
+      #
+      # @param name [String] The module's short name.
+      # @param metadata [Hash] The module's metadata.
+      # @param path [String] The path to the module.
+      # @param plans [Array] The module's plans.
+      # @param tasks [Array] The module's tasks.
+      #
+      def print_module_info(name:, metadata:, path:, plans:, tasks:, **_kwargs)
+        info = +''
+
+        info << colorize(:cyan, name)
+
+        info << colorize(:dim, " [#{metadata['version']}]") if metadata['version']
+        info << "\n"
+
+        info << if metadata['summary']
+                  indent(2, wrap(metadata['summary'].strip, 76))
+                else
+                  indent(2, "No description available.\n")
+                end
+        info << "\n"
+
+        if tasks.any?
+          length = tasks.map(&:first).map(&:length).max
+          data   = tasks.map { |task, desc| [task, truncate(desc, 76 - length)] }
+          info << colorize(:cyan, "Tasks\n")
+          info << format_table(data, 2).to_s
+          info << "\n\n"
+        end
+
+        if plans.any?
+          length = plans.map(&:first).map(&:length).max
+          data   = plans.map { |plan, desc| [plan, truncate(desc, 76 - length)] }
+          info << colorize(:cyan, "Plans\n")
+          info << format_table(data, 2).to_s
+          info << "\n\n"
+        end
+
+        if metadata['operatingsystem_support']&.any?
+          supported = metadata['operatingsystem_support'].map do |os|
+            [os['operatingsystem'], os['operatingsystemrelease']&.join(', ')]
+          end
+
+          info << colorize(:cyan, "Operating system support\n")
+          info << format_table(supported, 2).to_s
+          info << "\n\n"
+        end
+
+        if metadata['dependencies']&.any?
+          dependencies = metadata['dependencies'].map do |dep|
+            [dep['name'], dep['version_requirement']]
+          end
+
+          info << colorize(:cyan, "Dependencies\n")
+          info << format_table(dependencies, 2).to_s
+          info << "\n\n"
+        end
+
+        info << colorize(:cyan, "Path\n")
+        info << if path.start_with?(Bolt::Config::Modulepath::MODULES_PATH) ||
+                   path.start_with?(Bolt::Config::Modulepath::BOLTLIB_PATH)
+                  indent(2, 'built-in module')
+                else
+                  indent(2, path)
+                end
+
+        @stream.puts info
+      end
+
+      def print_plugin_list(plugins:, modulepath:)
         info   = +''
-        length = plugin_list.values.map(&:keys).flatten.map(&:length).max + 4
+        length = plugins.values.map(&:keys).flatten.map(&:length).max + 4
 
-        plugin_list.each do |hook, plugins|
-          next if plugins.empty?
+        plugins.each do |hook, plugin|
+          next if plugin.empty?
           next if hook == :validate_resolve_reference
 
           info << colorize(:cyan, "#{hook}\n")
 
-          plugins.each do |name, description|
+          plugin.each do |name, description|
             info << indent(2, name.ljust(length))
             info << truncate(description, 80 - length) if description
             info << "\n"
@@ -533,12 +639,37 @@ module Bolt
         @stream.puts info.chomp
       end
 
-      def print_targets(target_list, inventory_source, default_inventory, target_flag)
-        adhoc = colorize(:yellow, "(Not found in inventory file)")
+      def print_new_plan(name:, path:)
+        if Bolt::Util.powershell?
+          show_command = 'Get-BoltPlan -Name '
+          run_command  = 'Invoke-BoltPlan -Name '
+        else
+          show_command = 'bolt plan show'
+          run_command  = 'bolt plan run'
+        end
+
+        print_message(<<~OUTPUT)
+          Created plan '#{name}' at '#{path}'
+  
+          Show this plan with:
+              #{show_command} #{name}
+          Run this plan with:
+              #{run_command} #{name}
+        OUTPUT
+      end
+
+      # Print target names and where they came from.
+      #
+      # @param adhoc [Hash] Adhoc targets provided on the command line.
+      # @param inventory [Hash] Targets provided from the inventory.
+      # @param flag [Boolean] Whether a targeting command-line option was used.
+      #
+      def print_targets(adhoc:, inventory:, flag:, **_kwargs)
+        adhoc_text = colorize(:yellow, "(Not found in inventory file)")
 
         targets  = []
-        targets += target_list[:inventory].map { |target| [target.name, nil] }
-        targets += target_list[:adhoc].map { |target| [target.name, adhoc] }
+        targets += inventory[:targets].map { |target| [target['name'], nil] }
+        targets += adhoc[:targets].map { |target| [target['name'], adhoc_text] }
 
         info = +''
 
@@ -551,27 +682,31 @@ module Bolt
                 end
         info << "\n\n"
 
-        info << format_inventory_source(inventory_source, default_inventory)
-        info << format_target_summary(target_list[:inventory].count, target_list[:adhoc].count, target_flag, false)
+        info << format_inventory_source(inventory[:file], inventory[:default])
+        info << format_target_summary(inventory[:count], adhoc[:count], flag, false)
 
         @stream.puts info
       end
 
-      def print_target_info(target_list, inventory_source, default_inventory, target_flag)
-        adhoc_targets     = target_list[:adhoc].map(&:name).to_set
-        inventory_targets = target_list[:inventory].map(&:name).to_set
-        targets           = target_list.values.flatten.sort_by(&:name)
+      # Print detailed target information.
+      #
+      # @param adhoc [Hash] Adhoc targets provided on the command line.
+      # @param inventory [Hash] Targets provided from the inventory.
+      # @param flag [Boolean] Whether a targeting command-line option was used.
+      #
+      def print_target_info(adhoc:, inventory:, flag:, **_kwargs)
+        targets = (adhoc[:targets] + inventory[:targets]).sort_by { |t| t['name'] }
 
         info = +''
 
         if targets.any?
-          adhoc = colorize(:yellow, " (Not found in inventory file)")
+          adhoc_text = colorize(:yellow, " (Not found in inventory file)")
 
           targets.each do |target|
-            info << colorize(:cyan, target.name)
-            info << adhoc if adhoc_targets.include?(target.name)
+            info << colorize(:cyan, target['name'])
+            info << adhoc_text if adhoc[:targets].include?(target)
             info << "\n"
-            info << indent(2, target.detail.to_yaml.lines.drop(1).join)
+            info << indent(2, target.to_yaml.lines.drop(1).join)
             info << "\n"
           end
         else
@@ -579,8 +714,8 @@ module Bolt
           info << indent(2, "No targets\n\n")
         end
 
-        info << format_inventory_source(inventory_source, default_inventory)
-        info << format_target_summary(inventory_targets.count, adhoc_targets.count, target_flag, true)
+        info << format_inventory_source(inventory[:file], inventory[:default])
+        info << format_target_summary(inventory[:count], adhoc[:count], flag, true)
 
         @stream.puts info
       end
@@ -626,7 +761,13 @@ module Bolt
         info
       end
 
-      def print_groups(groups, inventory_source, default_inventory)
+      # Print inventory group information.
+      #
+      # @param count [Integer] Number of groups in the inventory.
+      # @param groups [Array] Names of groups in the inventory.
+      # @param inventory [Hash] Where the inventory was loaded from.
+      #
+      def print_groups(count:, groups:, inventory:)
         info = +''
 
         # Add group list
@@ -635,18 +776,18 @@ module Bolt
         info << "\n\n"
 
         # Add inventory file source
-        info << format_inventory_source(inventory_source, default_inventory)
+        info << format_inventory_source(inventory[:source], inventory[:default])
 
         # Add group count summary
         info << colorize(:cyan, "Group count\n")
-        info << indent(2, "#{groups.count} total")
+        info << indent(2, "#{count} total")
 
         @stream.puts info
       end
 
       # @param [Bolt::ResultSet] apply_result A ResultSet object representing the result of a `bolt apply`
-      def print_apply_result(apply_result, elapsed_time)
-        print_summary(apply_result, elapsed_time)
+      def print_apply_result(apply_result)
+        print_summary(apply_result, apply_result.elapsed_time)
       end
 
       # @param [Bolt::PlanResult] plan_result A PlanResult object
@@ -663,6 +804,12 @@ module Bolt
           print_container_result(value.result)
         when Bolt::ResultSet
           print_result_set(value)
+        when Bolt::Result
+          print_result(value)
+        when Bolt::ApplyResult
+          print_apply_result(value)
+        when Bolt::Error
+          print_bolt_error(**value.to_h.transform_keys(&:to_sym))
         else
           @stream.puts(::JSON.pretty_generate(plan_result, quirks_mode: true))
         end
@@ -702,6 +849,17 @@ module Bolt
         @stream.puts(colorize(:red, message))
       end
 
+      def print_bolt_error(msg:, details:, **_kwargs)
+        err = msg
+        if (f = details[:file])
+          err += "\n  (file: #{f}"
+          err += ", line: #{details[:line]}" if details[:line]
+          err += ", column: #{details[:column]}" if details[:column]
+          err += ")"
+        end
+        @stream.puts(colorize(:red, err))
+      end
+
       def print_prompt(prompt)
         @stream.print(colorize(:cyan, indent(4, prompt)))
       end