bolt 1.49.0 → 2.0.0

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

@@ -7,12 +7,15 @@ require 'bolt/task'
 # Runs a given instance of a `Task` on the given set of targets and returns the result from each.
 # This function does nothing if the list of targets is empty.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:run_task) do
   # Run a task.
   # @param task_name The task to run.
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
-  # @param args Arguments to the plan. Can also include additional options: '_catch_errors', '_run_as', '_noop'.
+  # @param args A hash of arguments to the task. Can also include additional options.
+  # @option args [Boolean] _catch_errors Whether to catch raised errors.
+  # @option args [String] _run_as User to run as using privilege escalation.
+  # @option args [Boolean] _noop Run the task in noop mode if available.
   # @return A list of results, one entry per target.
   # @example Run a task as root
   #   run_task('facts', $targets, '_run_as' => 'root')
@@ -27,7 +30,10 @@ Puppet::Functions.create_function(:run_task) do
   # @param task_name The task to run.
   # @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 args Arguments to the plan. Can also include additional options: '_catch_errors', '_run_as', '_noop'.
+  # @param args A hash of arguments to the task. Can also include additional options.
+  # @option args [Boolean] _catch_errors Whether to catch raised errors.
+  # @option args [String] _run_as User to run as using privilege escalation.
+  # @option args [Boolean] _noop Run the task in noop mode if available.
   # @return A list of results, one entry per target.
   # @example Run a task
   #   run_task('facts', $targets, 'Gather OS facts')

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

@@ -2,10 +2,11 @@
 
 require 'bolt/error'
 
-# Set configuration options on a target
+# Set configuration options on a target.
 #
-# **NOTE:** Not available in apply block
-# **NOTE:** Only compatible with inventory v2
+# > **Note:** Not available in apply block
+#
+# > **Note:** Only compatible with inventory v2
 Puppet::Functions.create_function(:set_config) do
   # @param target The Target object to configure. See {get_targets}.
   # @param key_or_key_path The configuration setting to update.

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

@@ -5,18 +5,18 @@ require 'bolt/error'
 # Sets a particular feature to present on a target.
 #
 # Features are used to determine what implementation of a task should be run.
-# Currently supported features are
-# - powershell
-# - shell
-# - puppet-agent
+# Supported features are:
+# - `powershell`
+# - `shell`
+# - `puppet-agent`
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:set_feature) do
   # @param target The Target object to add features to. See {get_targets}.
   # @param feature The string identifying the feature.
   # @param value Whether the feature is supported.
   # @return The target with the updated feature
-  # @example Add the puppet-agent feature to a target
+  # @example Add the `puppet-agent` feature to a target
   #   set_feature($target, 'puppet-agent', true)
   dispatch :set_feature do
     param 'Target', :target

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

@@ -2,9 +2,9 @@
 
 require 'bolt/error'
 
-# Sets a variable { key => value } for a target.
+# Sets a variable `{ key => value }` for a target.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:set_var) do
   # @param target The Target object to set the variable for. See {get_targets}.
   # @param key The key for the variable.

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

@@ -5,14 +5,16 @@ require 'bolt/error'
 # Uploads the given file or directory to the given set of targets and returns the result from each upload.
 # This function does nothing if the list of targets is empty.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:upload_file, Puppet::Functions::InternalFunction) do
   # Upload a file or directory.
   # @param source A source path, either an absolute path or a modulename/filename selector for a
   #               file or directory in $MODULEROOT/files.
   # @param destination An absolute path on the target(s).
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
-  # @param options Additional options: '_catch_errors', '_run_as'.
+  # @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.
   # @example Upload a local file to Linux targets and change owner to 'root'
   #   upload_file('/var/tmp/payload.tgz', '/tmp/payload.tgz', $targets, '_run_as' => 'root')
@@ -33,7 +35,9 @@ Puppet::Functions.create_function(:upload_file, Puppet::Functions::InternalFunct
   # @param destination An absolute path on the target(s).
   # @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 Additional options: '_catch_errors', '_run_as'.
+  # @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.
   # @example Upload a file
   #   upload_file('/var/tmp/payload.tgz', '/tmp/payload.tgz', $targets, 'Uploading payload to unpack')

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

@@ -4,11 +4,15 @@ require 'bolt/util'
 
 # Wait until all targets accept connections.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:wait_until_available) do
   # Wait until targets are available.
   # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
-  # @param options Additional options: 'description', 'wait_time', 'retry_interval', '_catch_errors'.
+  # @param options A hash of additional options.
+  # @option options [String] description A description for logging. (default: 'wait until available')
+  # @option options [Numeric] wait_time The time to wait. (default: 120)
+  # @option options [Numeric] retry_interval The interval to wait before retrying. (default: 1)
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
   # @return A list of results, one entry per target. Successful results have no value.
   # @example Wait for targets
   #   wait_until_available($targets, wait_time => 300)

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

@@ -3,10 +3,10 @@
 # Define a block where default logging is suppressed.
 #
 # Messages for actions within this block will be logged at `info` level instead
-# of `notice`, so they will not be seen normally but # will still be present
+# of `notice`, so they will not be seen normally but will still be present
 # when `verbose` logging is requested.
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:without_default_logging) do
   # @param block The block where action logging is suppressed.
   # @return [Undef]

data/bolt-modules/ctrl/lib/puppet/functions/ctrl/do_until.rb

@@ -2,7 +2,8 @@
 
 # Repeat the block until it returns a truthy value. Returns the value.
 Puppet::Functions.create_function(:'ctrl::do_until') do
-  # @param options Additional options: 'until'
+  # @param options A hash of additional options.
+  # @option options [Numeric] limit The number of times to repeat the block.
   # @example Run a task until it succeeds
   #   ctrl::do_until() || {
   #     run_task('test', $target, _catch_errors => true).ok()

data/bolt-modules/file/lib/puppet/functions/file/exists.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-# check if a file exists
+# Check if a file exists.
 Puppet::Functions.create_function(:'file::exists', Puppet::Functions::InternalFunction) do
   # @param filename Absolute path or Puppet file path.
+  # @return Whether the file exists.
   # @example Check a file on disk
   #   file::exists('/tmp/i_dumped_this_here')
   # @example check a file from the modulepath

data/bolt-modules/file/lib/puppet/functions/file/join.rb

@@ -3,6 +3,7 @@
 # Join file paths.
 Puppet::Functions.create_function(:'file::join') do
   # @param paths The paths to join.
+  # @return The joined file path.
   # @example Join file paths
   #   file::join('./path', 'to/files')
   dispatch :join do

data/bolt-modules/file/lib/puppet/functions/file/read.rb

@@ -3,6 +3,7 @@
 # Read a file and return its contents.
 Puppet::Functions.create_function(:'file::read', Puppet::Functions::InternalFunction) do
   # @param filename Absolute path or Puppet file path.
+  # @return The file's contents.
   # @example Read a file from disk
   #   file::read('/tmp/i_dumped_this_here')
   # @example Read a file from the modulepath

data/bolt-modules/file/lib/puppet/functions/file/readable.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-# check if a file is readable
+# Check if a file is readable.
 Puppet::Functions.create_function(:'file::readable', Puppet::Functions::InternalFunction) do
   # @param filename Absolute path or Puppet file path.
+  # @return Whether the file is readable.
   # @example Check a file on disk
   #   file::readable('/tmp/i_dumped_this_here')
   # @example check a file from the modulepath

data/bolt-modules/out/lib/puppet/functions/out/message.rb

@@ -5,7 +5,7 @@
 # This will print a message to stdout when using the human output format,
 # and print to stderr when using the json output format
 #
-# **NOTE:** Not available in apply block
+# > **Note:** Not available in apply block
 Puppet::Functions.create_function(:'out::message') do
   # Output a message.
   # @param message The message to output.

data/bolt-modules/system/lib/puppet/functions/system/env.rb

@@ -3,6 +3,7 @@
 # Get an environment variable.
 Puppet::Functions.create_function(:'system::env') do
   # @param name Environment variable name.
+  # @return The environment variable's value.
   # @example Get the USER environment variable
   #   system::env('USER')
   dispatch :env do

data/lib/bolt/applicator.rb

@@ -83,60 +83,7 @@ module Bolt
       end
     end
 
-    def compile(target, ast, plan_vars)
-      # This simplified Puppet node object is what .local uses to determine the
-      # certname of the target
-      node = Puppet::Node.from_data_hash('name' => target.name,
-                                         'parameters' => { 'clientcert' => target.name })
-      trusted = Puppet::Context::TrustedInformation.local(node)
-      facts = @inventory.facts(target).merge('bolt' => true)
-
-      catalog_input = {
-        code_ast: ast,
-        modulepath: @modulepath,
-        pdb_config: @pdb_client.config.to_hash,
-        hiera_config: @hiera_config,
-        target: {
-          name: target.name,
-          facts: facts,
-          variables: @inventory.vars(target).merge(plan_vars),
-          trusted: trusted.to_h
-        },
-        inventory: @inventory.data_hash
-      }
-
-      bolt_catalog_exe = File.join(libexec, 'bolt_catalog')
-      old_path = ENV['PATH']
-      ENV['PATH'] = "#{RbConfig::CONFIG['bindir']}#{File::PATH_SEPARATOR}#{old_path}"
-      out, err, stat = Open3.capture3('ruby', bolt_catalog_exe, 'compile', stdin_data: catalog_input.to_json)
-      ENV['PATH'] = old_path
-
-      # stderr may contain formatted logs from Puppet's logger or other errors.
-      # Print them in order, but handle them separately. Anything not a formatted log is assumed
-      # to be an error message.
-      logs = err.lines.map do |l|
-        begin
-          JSON.parse(l)
-        rescue StandardError
-          l
-        end
-      end
-      logs.each do |log|
-        if log.is_a?(String)
-          @logger.error(log.chomp)
-        else
-          log.map { |k, v| [k.to_sym, v] }.each do |level, msg|
-            bolt_level = Bolt::Util::PuppetLogLevel::MAPPING[level]
-            @logger.send(bolt_level, "#{target.name}: #{msg.chomp}")
-          end
-        end
-      end
-
-      raise(ApplyError, target.name) unless stat.success?
-      JSON.parse(out)
-    end
-
-    def future_compile(target, catalog_input)
+    def compile(target, catalog_input)
       # This simplified Puppet node object is what .local uses to determine the
       # certname of the target
       node = Puppet::Node.from_data_hash('name' => target.name,
@@ -148,9 +95,6 @@ module Bolt
         variables: @inventory.vars(target),
         trusted: trusted.to_h
       }
-      # rubocop:disable Style/GlobalVars
-      catalog_input[:future] = $future
-      # rubocop:enable Style/GlobalVars
 
       bolt_catalog_exe = File.join(libexec, 'bolt_catalog')
       old_path = ENV['PATH']
@@ -158,29 +102,30 @@ module Bolt
       out, err, stat = Open3.capture3('ruby', bolt_catalog_exe, 'compile', stdin_data: catalog_input.to_json)
       ENV['PATH'] = old_path
 
-      # stderr may contain formatted logs from Puppet's logger or other errors.
-      # Print them in order, but handle them separately. Anything not a formatted log is assumed
-      # to be an error message.
-      logs = err.lines.map do |l|
-        begin
-          JSON.parse(l)
-        rescue StandardError
-          l
-        end
+      # Any messages logged by Puppet will be on stderr as JSON hashes, so we
+      # parse those and store them here. Any message on stderr that is not
+      # properly JSON formatted is assumed to be an error message.  If
+      # compilation was successful, we print the logs as they may include
+      # important warnings. If compilation failed, we don't print the logs as
+      # they are likely redundant with the error that caused the failure, which
+      # will be handled separately.
+      logs = err.lines.map do |line|
+        JSON.parse(line)
+      rescue JSON::ParserError
+        { 'level' => 'err', 'message' => line }
       end
-      logs.each do |log|
-        if log.is_a?(String)
-          @logger.error(log.chomp)
-        else
-          log.map { |k, v| [k.to_sym, v] }.each do |level, msg|
-            bolt_level = Bolt::Util::PuppetLogLevel::MAPPING[level]
-            @logger.send(bolt_level, "#{target.name}: #{msg.chomp}")
-          end
+
+      result = JSON.parse(out)
+      if stat.success?
+        logs.each do |log|
+          bolt_level = Bolt::Util::PuppetLogLevel::MAPPING[log['level'].to_sym]
+          message = log['message'].chomp
+          @logger.send(bolt_level, "#{target.name}: #{message}")
         end
+        result
+      else
+        raise ApplyError.new(target.name, result['message'])
       end
-
-      raise(ApplyError, target.name) unless stat.success?
-      JSON.parse(out)
     end
 
     def validate_hiera_config(hiera_config)
@@ -232,25 +177,22 @@ module Bolt
     def apply_ast(raw_ast, targets, options, plan_vars = {})
       ast = Puppet::Pops::Serialization::ToDataConverter.convert(raw_ast, rich_data: true, symbol_to_string: true)
 
-      # rubocop:disable Style/GlobalVars
-      if $future
-        # Serialize as pcore for *Result* objects
-        plan_vars = Puppet::Pops::Serialization::ToDataConverter.convert(plan_vars,
-                                                                         rich_data: true,
-                                                                         symbol_as_string: true,
-                                                                         type_by_reference: true,
-                                                                         local_reference: false)
-        scope = {
-          code_ast: ast,
-          modulepath: @modulepath,
-          pdb_config: @pdb_client.config.to_hash,
-          hiera_config: @hiera_config,
-          plan_vars: plan_vars,
-          # This data isn't available on the target config hash
-          config: @inventory.config.transport_data_get
-        }
-      end
-      # rubocop:enable Style/GlobalVars
+      # Serialize as pcore for *Result* objects
+      plan_vars = Puppet::Pops::Serialization::ToDataConverter.convert(plan_vars,
+                                                                       rich_data: true,
+                                                                       symbol_as_string: true,
+                                                                       type_by_reference: true,
+                                                                       local_reference: false)
+
+      scope = {
+        code_ast: ast,
+        modulepath: @modulepath,
+        pdb_config: @pdb_client.config.to_hash,
+        hiera_config: @hiera_config,
+        plan_vars: plan_vars,
+        # This data isn't available on the target config hash
+        config: @inventory.config.transport_data_get
+      }
 
       description = options[:description] || 'apply catalog'
 
@@ -258,9 +200,7 @@ module Bolt
         futures = targets.map do |target|
           Concurrent::Future.execute(executor: @pool) do
             @executor.with_node_logging("Compiling manifest block", [target]) do
-              # rubocop:disable Style/GlobalVars
-              $future ? future_compile(target, scope) : compile(target, ast, plan_vars)
-              # rubocop:enable Style/GlobalVars
+              compile(target, scope)
             end
           end
         end
@@ -269,27 +209,39 @@ module Bolt
           @executor.queue_execute([target]) do |transport, batch|
             @executor.with_node_logging("Applying manifest block", batch) do
               catalog = future.value
-              raise future.reason if future.rejected?
-
-              arguments = {
-                'catalog' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(catalog),
-                'plugins' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(plugins),
-                'apply_settings' => @apply_settings,
-                '_task' => catalog_apply_task.name,
-                '_noop' => options[:noop]
-              }
-
-              callback = proc do |event|
-                if event[:type] == :node_result
-                  event = event.merge(result: ApplyResult.from_task_result(event[:result]))
+              if future.rejected?
+                batch.map do |batch_target|
+                  # If an unhandled exception occurred, wrap it in an ApplyError
+                  error = if future.reason.is_a?(Bolt::ApplyError)
+                            future.reason
+                          else
+                            Bolt::ApplyError.new(batch_target, future.reason.message)
+                          end
+                  result = Bolt::ApplyResult.new(batch_target, error: error.to_h)
+                  @executor.publish_event(type: :node_result, result: result)
+                  result
                 end
-                @executor.publish_event(event)
-              end
-              # Respect the run_as default set on the executor
-              options[:run_as] = @executor.run_as if @executor.run_as && !options.key?(:run_as)
+              else
+                arguments = {
+                  'catalog' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(catalog),
+                  'plugins' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(plugins),
+                  'apply_settings' => @apply_settings,
+                  '_task' => catalog_apply_task.name,
+                  '_noop' => options[:noop]
+                }
+
+                callback = proc do |event|
+                  if event[:type] == :node_result
+                    event = event.merge(result: ApplyResult.from_task_result(event[:result]))
+                  end
+                  @executor.publish_event(event)
+                end
+                # Respect the run_as default set on the executor
+                options[:run_as] = @executor.run_as if @executor.run_as && !options.key?(:run_as)
 
-              results = transport.batch_task(batch, catalog_apply_task, arguments, options, &callback)
-              Array(results).map { |result| ApplyResult.from_task_result(result) }
+                results = transport.batch_task(batch, catalog_apply_task, arguments, options, &callback)
+                Array(results).map { |result| ApplyResult.from_task_result(result) }
+              end
             end
           end
         end